Reject HTML formatting tags in Markdown Javadoc via checkstyle

[koppor]

🤖 Summary

Markdown Javadoc (///) comments kept accumulating HTML formatting tags (<code>, <tt>, …) — especially from AI-assisted edits — instead of Markdown. A new checkstyle rule now rejects HTML formatting tags in /// comments (backtick-quoted tags documenting literal HTML/XML stay allowed), the existing occurrences are converted, and AGENTS.md states the rule.

Analogies: Like honey, this PR preserves what is already good and keeps it from spoiling; like chocolate, it is a small piece with a disproportionate effect on wellbeing; and like the moon, it does not shine by itself — it only reflects the style rules already written down.

jabref-contrib-policy:4.2:reviewed​:ok

Steps to test

1. Add /// returns <code>true</code> to any Java file.
2. Run ./gradlew :jablib:checkstyleMain — it fails with MarkdownJavadocNoHtmlFormattingTags.

Related issues and pull requests

None — follow-up to #16765 (which banned JavaDoc inline tags in /// comments).

AI usage

Claude Code (model claude-fable-5), AIL4 (AI-authored, human-directed and reviewed).

AI CHECKLIST.md walkthrough

Nullability and control flow

• [/] No == null / != null checks — comment/config-only change.
• [/] No Objects.requireNonNull(...).
• [/] New classes annotated with @NullMarked.
• [/] Optional consumed with ifPresent / ifPresentOrElse / map / orElseThrow.
• [/] StringUtil.isBlank(...) used.

Exceptions

• [/] No catch (Exception e) — not applicable to this group (no executable code touched).
• [/] No throw new RuntimeException(...) / IllegalStateException(...).
• [/] Logged exceptions passed as last logger argument.

Style and idioms

• [/] New BibEntry objects built with withers — not applicable to this group.
• [/] Modern Java used.
• [/] Regexes use a precompiled Pattern.compile(...) constant.
• [/] Background work uses BackgroundTask.
• No commented-out code, no trivial comments, no AI-disclosure comments in source.
• Markdown Javadoc (///) uses Markdown syntax, not JavaDoc inline tags.

User-facing text

• [/] All user-facing text localized — not applicable to this group (no user-facing text).
• [/] Sentence case.
• [/] Variance via placeholders.

Security

• [/] User-controlled data HTML-escaped — no runtime code touched.

Tests

• [/] Behavior changes have tests — no behavior change; the checkstyle rule is CI-verified.
• [/] Tests assert object contents.
• [/] Fetcher tests hit live endpoints.

Verification commands

• ./gradlew :jablib:check — not run in full; checkstyle + javadoc run instead (comment-only change).
• ./gradlew checkstyleMain checkstyleTest — all modules pass, including the new rule.
• [/] ./gradlew modernizer — no executable code changed.
• ./gradlew rewriteRun run; no further changes.
• ./gradlew :jablib:javadoc passes on the converted comments.
• [/] npx markdownlint-cli2 — AGENTS.md edit is a single list-item rewording.
• Touched Java files formatted with IntelliJ IDEA (.idea/codeStyles/Project.xml, IU-253).

Documentation

• [/] CHANGELOG.md — not visible to users (one "not applicable" note for this group).
• Issue search done; no matching issue, follow-up to PR Use Markdown syntax instead of JavaDoc inline tags in Markdown Javadoc comments #16765.
• [/] Requirement doc — internal tooling change.
• Developer documentation (AGENTS.md) updated.

Pull request

• PR body built from template, every section filled.
• All checklist items kept and marked.
• All HTML comments removed.
• Created with gh pr create --body-file.
• [/] No TODO placeholder used.

Checklist

• I own the copyright of the code submitted and I license it under the MIT license
• If AI tools were used, I disclosed them in the "AI usage" section and reviewed, understood, and take full ownership of all AI-generated code
• [/] I manually tested my changes in running JabRef (always required) — comment/CI-config-only change, verified via checkstyle and javadoc builds
• [/] I added JUnit tests for changes (if applicable)
• [/] I added screenshots in the PR description (if change is visible to the user)
• [/] I added one sentence (max 20 words) to CHANGELOG.md describing the change from the user's point of view (if the change is visible to the user)
• [/] I checked the user documentation for up to dateness and submitted a pull request to our user documentation repository

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Enforce Markdown formatting in Markdown Javadoc

✨ Enhancement 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Reject HTML formatting tags in Markdown Javadoc across standard and reviewdog Checkstyle runs.
• Preserve backtick-quoted literal tags and avoid uppercase generic-parameter false positives.
• Convert existing comments to Markdown code, tables, and paragraph spacing.

Diagram

graph TD
  A["Contributors"] --> B["AGENTS guidance"] --> C["Markdown Javadoc"]
  D["Checkstyle configs"] --> E["HTML tag rule"] --> F["CI validation"]
  C --> F

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Implement a custom Checkstyle check

• ➕ Could parse Markdown code spans more accurately than line-based lookarounds.
• ➕ Could provide tag-specific diagnostics and dedicated unit-test fixtures.
• ➖ Adds Java implementation and maintenance overhead for a narrow policy.
• ➖ Requires integrating and distributing a custom Checkstyle extension.

Recommendation: Keep the RegexpSingleline approach for this bounded tag list: it is declarative, inexpensive, and deploys consistently in both existing Checkstyle paths. A custom check becomes preferable only if exemptions expand beyond the documented one-line backtick heuristic or false positives emerge.

Files changed (34) +146 / -127

Documentation (32) +122 / -127

AGENTS.mdDocument the HTML-free Markdown Javadoc policy +1/-1

Document the HTML-free Markdown Javadoc policy

• Expands contributor guidance to prohibit both JavaDoc inline tags and HTML formatting tags in '///' comments. It recommends Markdown code spans, links, and fenced code blocks instead.

AGENTS.md

ActionHelper.javaReplace an HTML break with Markdown spacing +1/-1

Replace an HTML break with Markdown spacing

• Removes a '<br>' tag from Markdown Javadoc and uses an empty '///' line for paragraph separation.

jabgui/src/main/java/org/jabref/gui/actions/ActionHelper.java

UnlinkedFilesCrawler.javaConvert crawler documentation breaks to Markdown +9/-9

Convert crawler documentation breaks to Markdown

• Replaces repeated HTML line breaks with Markdown Javadoc paragraph separators throughout the recursive search documentation.

jabgui/src/main/java/org/jabref/gui/externalfiles/UnlinkedFilesCrawler.java

GroupTreeViewModel.javaUse Markdown paragraph spacing in group documentation +2/-1

Use Markdown paragraph spacing in group documentation

• Removes the trailing HTML break and separates the following explanation with an empty Markdown Javadoc line.

jabgui/src/main/java/org/jabref/gui/groups/GroupTreeViewModel.java

PersistenceVisualStateTable.javaRemove an HTML break from sort-order documentation +1/-1

Remove an HTML break from sort-order documentation

• Uses Markdown paragraph spacing between the sort-order summary and implementation constraint.

jabgui/src/main/java/org/jabref/gui/maintable/PersistenceVisualStateTable.java

Bootstrap.javaConvert Bootstrap examples to fenced Java blocks +4/-4

Convert Bootstrap examples to fenced Java blocks

• Replaces two '<pre>' examples with Markdown fenced code blocks annotated as Java.

jabgui/src/main/java/org/jabref/gui/openoffice/Bootstrap.java

PreferencesMigrations.javaRewrite cleanup migration details as Markdown +16/-19

Rewrite cleanup migration details as Markdown

• Replaces an HTML heading and table with a Markdown heading and table. Cleanup preference formats remain documented with inline code spans.

jabgui/src/main/java/org/jabref/migrations/PreferencesMigrations.java

AbstractCitationKeyPatterns.javaRemove HTML breaks from fallback documentation +2/-2

Remove HTML breaks from fallback documentation

• Rephrases the citation-key pattern fallback sequence as normal Markdown prose without '<br>' tags.

jablib/src/main/java/org/jabref/logic/citationkeypattern/AbstractCitationKeyPatterns.java

BracketedPattern.javaFormat the BibTeX example as Markdown code +2/-2

Format the BibTeX example as Markdown code

• Replaces '<code>' markup around the inline BibTeX expansion example with a Markdown code span.

jablib/src/main/java/org/jabref/logic/citationkeypattern/BracketedPattern.java

JabRefItemDataProvider.javaRemove a redundant HTML break before table documentation +0/-1

Remove a redundant HTML break before table documentation

• Drops the '<br>' preceding the existing table while retaining Markdown paragraph spacing.

jablib/src/main/java/org/jabref/logic/citationstyle/JabRefItemDataProvider.java

AuthorListParser.javaConvert parser identifier markup to code spans +17/-17

Convert parser identifier markup to code spans

• Replaces uppercase '<CODE>' tags around parser fields, token constants, booleans, and return values with Markdown inline code.

jablib/src/main/java/org/jabref/logic/importer/AuthorListParser.java

ArXivFetcher.javaReplace DOI documentation breaks with Markdown paragraphs +4/-4

Replace DOI documentation breaks with Markdown paragraphs

• Removes paired HTML break tags from four ArXiv DOI method comments and preserves separation using empty Markdown Javadoc lines.

jablib/src/main/java/org/jabref/logic/importer/fetcher/ArXivFetcher.java

BibtexParser.javaConvert the parser usage example to a fenced block +2/-2

Convert the parser usage example to a fenced block

• Replaces nested '<code><pre>' markup with a Java Markdown code fence.

jablib/src/main/java/org/jabref/logic/importer/fileformat/BibtexParser.java

EndnoteImporter.javaRemove an HTML break from importer documentation +1/-1

Remove an HTML break from importer documentation

• Uses an empty Markdown Javadoc line to separate the importer description from its format reference.

jablib/src/main/java/org/jabref/logic/importer/fileformat/EndnoteImporter.java

ModsImporter.javaConvert MODS documentation breaks to Markdown spacing +4/-2

Convert MODS documentation breaks to Markdown spacing

• Removes '<br>' tags and separates the importer summary, format link, and schema link with Markdown paragraphs.

jablib/src/main/java/org/jabref/logic/importer/fileformat/ModsImporter.java

LayoutHelper.javaConvert the layout example to fenced Java +2/-4

Convert the layout example to fenced Java

• Replaces nested '<pre>' and '<code>' tags with a Java Markdown code fence.

jablib/src/main/java/org/jabref/logic/layout/LayoutHelper.java

MSBibEntry.javaReformat address-pattern documentation as Markdown +8/-4

Reformat address-pattern documentation as Markdown

• Replaces HTML line breaks with Markdown paragraph separators around the supported address form, regex, and examples.

jablib/src/main/java/org/jabref/logic/msbib/MSBibEntry.java

DatabaseFileLookup.javaReplace file-lookup HTML breaks with Markdown paragraphs +7/-7

Replace file-lookup HTML breaks with Markdown paragraphs

• Removes '<br>' tags from class and method documentation while preserving logical paragraph separation.

jablib/src/main/java/org/jabref/logic/util/io/DatabaseFileLookup.java

StringUtil.javaModernize StringUtil Markdown Javadoc formatting +3/-2

Modernize StringUtil Markdown Javadoc formatting

• Replaces an HTML break with Markdown spacing and converts '<tt>String</tt>' to an inline code span.

jablib/src/main/java/org/jabref/logic/util/strings/StringUtil.java

BibDatabaseMode.javaConsolidate parse return documentation without breaks +1/-2

Consolidate parse return documentation without breaks

• Rewrites the two parse outcomes as one semicolon-separated Markdown Javadoc return description.

jablib/src/main/java/org/jabref/model/database/BibDatabaseMode.java

Author.javaConvert author value markup to Markdown code +6/-6

Convert author value markup to Markdown code

• Replaces uppercase '<CODE>' tags around nulls, booleans, and examples with inline code spans.

jablib/src/main/java/org/jabref/model/entry/Author.java

AuthorList.javaConvert AuthorList terminology to Markdown code +9/-9

Convert AuthorList terminology to Markdown code

• Replaces uppercase '<CODE>' markup throughout class and accessor documentation with Markdown inline code, including generic type text.

jablib/src/main/java/org/jabref/model/entry/AuthorList.java

BibEntry.javaNormalize BibEntry Markdown Javadoc +3/-7

Normalize BibEntry Markdown Javadoc

• Converts '<code>' values and a '<br>' separator to Markdown syntax. It also removes redundant blank documentation lines.

jablib/src/main/java/org/jabref/model/entry/BibEntry.java

OrFields.javaReplace OrFields HTML breaks with Markdown spacing +2/-2

Replace OrFields HTML breaks with Markdown spacing

• Uses empty Markdown Javadoc lines around the required-fields example instead of '<br>' tags.

jablib/src/main/java/org/jabref/model/entry/field/OrFields.java

ARK.javaRemove HTML breaks from ARK documentation +0/-2

Remove HTML breaks from ARK documentation

• Replaces paired '<br>' tags with Markdown paragraph spacing and removes a redundant empty documentation line.

jablib/src/main/java/org/jabref/model/entry/identifier/ARK.java

MetaData.javaRemove an inline break from parameter documentation +1/-1

Remove an inline break from parameter documentation

• Joins the citation-key pattern parameter explanation into Markdown-compatible prose without '<br />'.

jablib/src/main/java/org/jabref/model/metadata/MetaData.java

BstWidthCalculatorTest.javaConvert BibTeX test instructions to fenced blocks +7/-8

Convert BibTeX test instructions to fenced blocks

• Replaces HTML paragraph and code tags with Markdown spacing and two fenced code examples.

jablib/src/test/java/org/jabref/logic/bst/util/BstWidthCalculatorTest.java

BibEntryRelationsRepositoryTestHelpers.javaRemove an HTML break from mock-helper documentation +1/-1

Remove an HTML break from mock-helper documentation

• Uses Markdown paragraph spacing between the mock factory summary and its testing purpose.

jablib/src/test/java/org/jabref/logic/citation/repository/BibEntryRelationsRepositoryTestHelpers.java

LayoutEntryTest.javaReplace a test-comment paragraph tag with Markdown +1/-1

Replace a test-comment paragraph tag with Markdown

• Removes the self-closing HTML paragraph tag and retains separation with an empty Markdown Javadoc line.

jablib/src/test/java/org/jabref/logic/layout/LayoutEntryTest.java

ServerCli.javaUse Markdown spacing in server startup documentation +2/-1

Use Markdown spacing in server startup documentation

• Replaces the trailing HTML break with an empty Markdown Javadoc line before the argument explanation.

jabsrv-cli/src/main/java/org/jabref/http/server/cli/ServerCli.java

EntryResource.javaRemove HTML breaks from entry endpoint documentation +2/-2

Remove HTML breaks from entry endpoint documentation

• Drops paired '<br>' tags from the plain-text and HTML representation endpoint comments while retaining paragraph separation.

jabsrv/src/main/java/org/jabref/http/server/resources/EntryResource.java

MapResource.javaRemove HTML breaks from map endpoint documentation +1/-1

Remove HTML breaks from map endpoint documentation

• Removes paired '<br>' tags from the map endpoint comment and relies on Markdown paragraph spacing.

jabsrv/src/main/java/org/jabref/http/server/resources/MapResource.java

Other (2) +24 / -0

checkstyle.xmlEnforce Markdown-only formatting in standard Checkstyle +12/-0

Enforce Markdown-only formatting in standard Checkstyle

• Adds a RegexpSingleline rule rejecting formatting, break, paragraph, and preformatted HTML tags in Markdown Javadoc. Backtick-adjacent literal tags and uppercase single-letter generic parameters are exempted.

config/checkstyle/checkstyle.xml

checkstyle_reviewdog.xmlMirror Markdown Javadoc enforcement in reviewdog +12/-0

Mirror Markdown Javadoc enforcement in reviewdog

• Adds the same HTML-tag rejection rule and exemptions to the reviewdog Checkstyle configuration, keeping local and review feedback consistent.

config/checkstyle/checkstyle_reviewdog.xml

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (2) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Backtick adjacency bypasses rule 📘 Rule violation ≡ Correctness

Description

The regex exempts a forbidden HTML tag when either neighboring character is a backtick, even when
that backtick belongs to a separate Markdown code span. Thus a line such as ``///
prefix<code>value</code>suffix `` passes while still using active HTML formatting.

Code

config/checkstyle/checkstyle.xml[101]

+        <property name="format" value="^\s*///.*(?&lt;!`)&lt;/?((?i:code|tt|em|strong|br|pre)|b|i|p)\s*/?&gt;(?!`)" />

Evidence

Rule 11 prohibits HTML formatting in Markdown Javadoc. The added expression uses independent
(?<!) and (?!) assertions, so each tag is skipped based on only one adjacent backtick rather
than verifying that it lies inside a code span; the accompanying comment explicitly confirms this
one-character heuristic.

AGENTS.md: Use Markdown Javadoc for Multiline Documentation: AGENTS.md: Use Markdown Javadoc for Multiline Documentation: AGENTS.md: Use Markdown Javadoc for Multiline Documentation: AGENTS.md: Use Markdown Javadoc for Multiline Documentation: AGENTS.md: Use Markdown Javadoc for Multiline Documentation: AGENTS.md: Use Markdown Javadoc for Multiline Documentation: AGENTS.md: Use Markdown Javadoc for Multiline Documentation: AGENTS.md: Use Markdown Javadoc for Multiline Documentation
config/checkstyle/checkstyle.xml[93-101]
config/checkstyle/checkstyle_reviewdog.xml[82-90]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The HTML-tag check treats any immediately adjacent backtick as proof that a tag is inside a Markdown code span. Separate code spans can therefore surround active HTML and bypass enforcement.
## Issue Context
Literal HTML/XML tags should remain allowed only when the complete tag occurrence is actually enclosed within a Markdown code span. Keep the normal and reviewdog Checkstyle configurations synchronized and add regression coverage for both legitimate literal tags and adjacency bypasses.
## Fix Focus Areas
- config/checkstyle/checkstyle.xml[93-103]
- config/checkstyle/checkstyle_reviewdog.xml[82-92]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Checker behavior lacks tests 📘 Rule violation ☼ Reliability

Description

The PR adds nontrivial Checkstyle behavior and documented exceptions but no deterministic tests for
rejected tags, allowed literal tags, or edge cases. Configuration loading only proves that current
sources pass; it does not protect the rule's intended behavior from regressions.

Code

config/checkstyle/checkstyle.xml[R98-101]

+    <module name="RegexpSingleline">
+        <property name="id" value="MarkdownJavadocNoHtmlFormattingTags"/>
+        <property name="message" value="Markdown Javadoc (///) must use Markdown syntax, not HTML formatting tags: `code` instead of &lt;code&gt;code&lt;/code&gt;, fenced code blocks (```) instead of &lt;pre&gt;&lt;code&gt;." />
+        <property name="format" value="^\s*///.*(?&lt;!`)&lt;/?((?i:code|tt|em|strong|br|pre)|b|i|p)\s*/?&gt;(?!`)" />

Evidence

Rule 27 requires deterministic tests for behavioral changes. The cited configuration introduces
matching behavior and multiple exceptions, while repository searches found no Checkstyle test class
or test reference to MarkdownJavadocNoHtmlFormattingTags; only the two production configuration
declarations exist.

AGENTS.md: Add Deterministic Tests for Behavioral and Core Logic Changes: AGENTS.md: Add Deterministic Tests for Behavioral and Core Logic Changes: AGENTS.md: Add Deterministic Tests for Behavioral and Core Logic Changes: AGENTS.md: Add Deterministic Tests for Behavioral and Core Logic Changes: AGENTS.md: Add Deterministic Tests for Behavioral and Core Logic Changes: AGENTS.md: Add Deterministic Tests for Behavioral and Core Logic Changes: AGENTS.md: Add Deterministic Tests for Behavioral and Core Logic Changes: AGENTS.md: Add Deterministic Tests for Behavioral and Core Logic Changes
config/checkstyle/checkstyle.xml[93-103]
config/checkstyle/checkstyle_reviewdog.xml[82-92]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new Markdown Javadoc HTML-tag enforcement has no automated positive and negative behavior tests.
## Issue Context
Add deterministic coverage that verifies prohibited formatting tags fail, backtick-quoted literal HTML/XML passes, supported casing behaves intentionally, and both Checkstyle configurations retain equivalent enforcement.
## Fix Focus Areas
- config/checkstyle/checkstyle.xml[93-103]
- config/checkstyle/checkstyle_reviewdog.xml[82-92]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. `` bypasses enforcement ✓ Resolved 📘 Rule violation ≡ Correctness

Description

The new rule claims to reject preformatted HTML, but its tag alternation omits pre, so a Markdown
Javadoc line containing only ... passes. This leaves the explicitly prohibited syntax unenforced.

Code

config/checkstyle/checkstyle.xml[98]

+        <property name="format" value="^\s*///.*(?&lt;!`)&lt;/?(code|tt|b|i|em|strong)&gt;" />

Evidence

PR Compliance ID 8 prohibits preformatted HTML. The new pattern enumerates code|tt|b|i|em|strong
but not pre, while the updated guidance explicitly says to replace `` with fenced code blocks.

AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments
config/checkstyle/checkstyle.xml[97-98]
AGENTS.md[136-136]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new Checkstyle expression does not reject standalone `<pre>` tags even though preformatted HTML is prohibited.
## Issue Context
The rule message and developer guidance direct authors to use fenced code blocks instead of `<pre>`, and PR Compliance ID 8 explicitly prohibits preformatted HTML in Markdown Javadoc.
## Fix Focus Areas
- config/checkstyle/checkstyle.xml[98-98]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View action required (2)

4. Backticked closing tags rejected ✓ Resolved 📘 Rule violation ≡ Correctness

Description

The one-character negative lookbehind exempts only an opening tag immediately preceded by a
backtick, so valid Markdown such as ` <code>value</code> ` is still matched at the closing tag.
This contradicts the documented exception for backtick-quoted literal HTML/XML and can cause
Checkstyle to reject compliant documentation.

Code

config/checkstyle/checkstyle.xml[98]

+        <property name="format" value="^\s*///.*(?&lt;!`)&lt;/?(code|tt|b|i|em|strong)&gt;" />

Evidence

PR Compliance ID 8 prescribes backticks for code, and the configuration comment explicitly states
that backtick-quoted literal tags remain allowed. However, (?<!\x60) inspects only the character
immediately before the matched <; in ` <code>text</code> `, the opening tag is exempt because
it follows a backtick, while the closing tag follows t and therefore matches.

AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments: AGENTS.md: Use Markdown Javadoc Syntax for Multiline Documentation Comments
config/checkstyle/checkstyle.xml[93-98]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The regular expression checks only the character immediately before each tag, causing closing HTML/XML tags inside valid backtick-delimited literals to be reported even though the complete fragment is quoted.
## Issue Context
The documented exception applies to tags quoted in backticks, including paired literal markup such as `` `<code>text</code>` ``. In that example, the opening tag is immediately preceded by a backtick, but the closing tag is preceded by text and therefore matches; update the check to distinguish tags inside complete Markdown inline code spans and add coverage for both opening and closing literal tags.
## Fix Focus Areas
- config/checkstyle/checkstyle.xml[93-100]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Uppercase tags bypass rule ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new regex matches only lowercase tag names, so existing Markdown Javadocs containing ...
continue to pass despite the rule's stated ban. This leaves dozens of current violations unenforced
and permits the same formatting through case changes.

Code

config/checkstyle/checkstyle.xml[98]

+        <property name="format" value="^\s*///.*(?&lt;!`)&lt;/?(code|tt|b|i|em|strong)&gt;" />

Evidence

The rule enumerates only lowercase alternatives, while multiple active Markdown Javadocs use
uppercase `` formatting that therefore cannot match this case-sensitive regex.

config/checkstyle/checkstyle.xml[93-100]
jablib/src/main/java/org/jabref/logic/importer/AuthorListParser.java[225-225]
jablib/src/main/java/org/jabref/model/entry/Author.java[31-31]
jablib/src/main/java/org/jabref/model/entry/AuthorList.java[18-18]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The Markdown-Javadoc HTML formatting rule only recognizes lowercase tag names, allowing uppercase or mixed-case HTML formatting tags such as `<CODE>` to bypass Checkstyle.
## Issue Context
HTML tag names are case-insensitive in this usage, and the repository already contains many uppercase formatting tags in `///` comments.
## Fix Focus Areas
- config/checkstyle/checkstyle.xml[93-100]
- jablib/src/main/java/org/jabref/logic/importer/AuthorListParser.java[225-225]
- jablib/src/main/java/org/jabref/model/entry/Author.java[31-31]
- jablib/src/main/java/org/jabref/model/entry/AuthorList.java[18-18]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Tag attributes bypass rule 🐞 Bug ≡ Correctness

Description

The regex requires whitespace or > immediately after the tag name, so prohibited formatting such
as text or `` passes Checkstyle. This defeats the new enforcement whenever an HTML formatting tag
has attributes.

Code

config/checkstyle/checkstyle.xml[101]

+        <property name="format" value="^\s*///.*(?&lt;!`)&lt;/?((?i:code|tt|em|strong|br|pre)|b|i|p)\s*/?&gt;(?!`)" />

Evidence

The rule explicitly bans the listed HTML formatting tags, but the expression transitions directly
from the tag-name group to \s*/?>; therefore any non-whitespace attribute text after the name
prevents a match. The same incomplete expression is duplicated in the reviewdog configuration.

config/checkstyle/checkstyle.xml[93-103]
config/checkstyle/checkstyle_reviewdog.xml[82-92]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new Markdown Javadoc rule does not match prohibited HTML formatting tags when their opening tag contains attributes.
## Issue Context
Keep the main and reviewdog Checkstyle configurations synchronized. Match valid attribute-bearing opening tags without weakening the backtick exception or confusing `>` characters inside quoted attribute values.
## Fix Focus Areas
- config/checkstyle/checkstyle.xml[93-103]
- config/checkstyle/checkstyle_reviewdog.xml[82-92]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. Pipe table renders literally ✓ Resolved 🐞 Bug ≡ Correctness

Description

The replacement uses GitHub-style pipe-table syntax, which is not part of Java's standard Markdown
doc-comment syntax, so the generated Javadoc displays pipe-delimited text instead of the previous
formatted table. This makes the cleanup migration's old/new preference mapping substantially harder
to read.

Code

jabgui/src/main/java/org/jabref/migrations/PreferencesMigrations.java[R537-538]

+    /// | key                                  | value                                                                    |
+    /// |--------------------------------------|--------------------------------------------------------------------------|

Evidence

The changed comment contains a pipe header, separator, and rows as its only table structure. The
repository compiles Markdown doc comments with Java 25, while the other conversions in this PR use
supported fenced blocks rather than extension-specific Markdown constructs.

jabgui/src/main/java/org/jabref/migrations/PreferencesMigrations.java[533-550]
build-logic/src/main/kotlin/org.jabref.gradle.feature.compile.gradle.kts[32-33]
jabgui/src/main/java/org/jabref/gui/openoffice/Bootstrap.java[69-73]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The converted cleanup-preference table uses pipe-table syntax that standard Markdown Javadoc does not render as a table.
## Issue Context
Preserve the old/new mapping's readable structure using syntax supported by Java Markdown doc comments, such as headings plus lists or a fenced plain-text block.
## Fix Focus Areas
- jabgui/src/main/java/org/jabref/migrations/PreferencesMigrations.java[535-550]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-free-for-open-source-projects]

1. Backtick adjacency bypasses rule 📘 Rule violation ≡ Correctness

The regex exempts a forbidden HTML tag when either neighboring character is a backtick, even when
that backtick belongs to a separate Markdown code span. Thus a line such as ``///
prefix<code>value</code>suffix `` passes while still using active HTML formatting.

Agent Prompt

## Issue description
The HTML-tag check treats any immediately adjacent backtick as proof that a tag is inside a Markdown code span. Separate code spans can therefore surround active HTML and bypass enforcement.

## Issue Context
Literal HTML/XML tags should remain allowed only when the complete tag occurrence is actually enclosed within a Markdown code span. Keep the normal and reviewdog Checkstyle configurations synchronized and add regression coverage for both legitimate literal tags and adjacency bypasses.

## Fix Focus Areas
- config/checkstyle/checkstyle.xml[93-103]
- config/checkstyle/checkstyle_reviewdog.xml[82-92]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-free-for-open-source-projects]

2. Checker behavior lacks tests 📘 Rule violation ☼ Reliability

The PR adds nontrivial Checkstyle behavior and documented exceptions but no deterministic tests for
rejected tags, allowed literal tags, or edge cases. Configuration loading only proves that current
sources pass; it does not protect the rule's intended behavior from regressions.

Agent Prompt

## Issue description
The new Markdown Javadoc HTML-tag enforcement has no automated positive and negative behavior tests.

## Issue Context
Add deterministic coverage that verifies prohibited formatting tags fail, backtick-quoted literal HTML/XML passes, supported casing behaves intentionally, and both Checkstyle configurations retain equivalent enforcement.

## Fix Focus Areas
- config/checkstyle/checkstyle.xml[93-103]
- config/checkstyle/checkstyle_reviewdog.xml[82-92]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[qodo-free-for-open-source-projects]

Code review by qodo was updated up to the latest commit 7fe48ea

[koppor]

🤖 Generated with Claude Code

Merged origin/main into enforce-markdown-javadoc to resolve the merge conflict.

• Conflicting file: jablib/src/main/java/org/jabref/model/entry/AuthorList.java (class-level Javadoc).
• main meanwhile rewrote that whole Javadoc block into proper Markdown lists, dropping the <ol>/</ol> wrapper and already converting every <CODE>…</CODE> to backticks — i.e. it subsumes this PR's edits to that file. Resolution: took main's version; the file is now identical to main and HTML-tag-free, which is what this PR's checkstyle rule wants.
• No other files needed manual resolution; the build was not run locally (dependency hosts are unreachable here), so CI is the compile check.

---

Generated by Claude Code

[calixtus]

'syntax — neither' tell me you used ai without saying, that you used ai... ;-)

[Siedlerchr]

em dashes