Issue #20984: Added new check PreferLiteralJavadocInlineTag by Aman-Baliyan · Pull Request #20397 · checkstyle/checkstyle

@romani what jdkVersion should we use in checkstyle-checks.xml. Is it 25 or below 18?
if it is 18 or above then i have create separate pr for violations in checkstyle codes because there are almost 500 violations for <pre> tag

romani · 2026-07-21T18:51:43Z

I do not understand why we need update anything .
plaase share link to problem.

we use jdk21, all jdk25 source goes to non-compiled folders

ok I see, semaphore ....
[ERROR] [checkstyle] [ERROR] /home/semaphore/checkstyle/.ci-temp/sevntu.checkstyle/sevntu-checks/src/main/java/com/github/sevntu/checkstyle/checks/annotation/ForbidAnnotationCheck.java:35:4: Prefer Javadoc inline tag '{@snippet ...}' over '<pre>'. [PreferJavadocInlineTags]

please send supplemental PR to fix this, we eat food we produce, if we can not fix violation, it means Check has problems in design.

sevntu still on jdk11, I hope to upgrade it to jdk21 after release of 13.9.0.
So for now please send update as it is jdk11.

romani

quick look:

romani · 2026-07-21T19:04:32Z

+  <suppress checks="JavadocStyle" files="JavadocParagraphCheck\.java"/>
+
+  <!-- Suppress PreferJavadocInlineTags for all files -->
+  <suppress checks="PreferJavadocInlineTags"/>


we need to come back to it, we should fix all Inputs of Openjdk for sure.

please point to few problems link and violation with others

we need to come back to it, we should fix all Inputs of Openjdk for sure.

please point to few problems link and violation with others

ok i will create a issue for this.

romani · 2026-07-21T19:04:53Z

+
+  <!-- JavadocStyle incorrectly parses HTML tags inside {@code} blocks -->
+  <suppress checks="JavadocStyle"
+            files="PreferJavadocInlineTagsCheck\.java"/>


remove this , JavadocStyle is removed.

remove this , JavadocStyle is removed.

done

romani · 2026-07-21T19:04:56Z


+  <!-- JavadocStyle incorrectly parses HTML tags inside {@literal}, {@code} blocks as real HTML,
+          until #19145 -->
+  <suppress checks="JavadocStyle" files="JavadocParagraphCheck\.java"/>


#19145 is closed

#19145 is closed

done

romani · 2026-07-21T19:06:24Z

+
+  <!-- EscapedEntity is an error-prone warning, needs @SuppressWarnings to suppress -->
+  <suppress checks="SuppressWarnings"
+            files="PreferJavadocInlineTagsCheck\.java"/>


please share details, it is very unusual ....

please share details, it is very unusual ....

PreferInlineJavadocTagsCheck file contains escaped entity which needs to be suppressed.
I have used the suppression annotation then i got violation from suppression check that's why i have used this

Aman-Baliyan · 2026-07-22T05:26:59Z

I do not understand why we need update anything . plaase share link to problem.

we use jdk21, all jdk25 source goes to non-compiled folders

sorry the message #20397 (comment) is not clearly written.

i am asking that i have added a new property jdkVersion in PreferInlineJavadocTagCheck due to snippet inline tag which is added in jdk 18 .
So the question here is what jdkVersion should we used in checkstyle-checks.xml for PreferInlineJavadocTagCheck
because there are huge violations from snippet tag in checkstyle javadocs.

The violations are -> https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/1dbbeec_2026171053/reports/diff/checkstyle/index.html

Aman-Baliyan · 2026-07-22T05:42:02Z

sevntu still on jdk11, I hope to upgrade it to jdk21 after release of 13.9.0.
So for now please send update as it is jdk11.

if it is on jdk11 then violation for pre tag cannot be resolved. Should we use jdkVersion less than 18 for now in checkstyle-checks.xml for PreferJavadocInlineTags.

romani · 2026-07-22T06:06:06Z

yes, it will good example on what update is expected for jdk21 and for jdk18. Pretty sad that fixes are different.
give me some small preview of updates to let me feel a pain.
Over-demanding Checks usually doomed to die in no-usage, we need to try to make it less painful.

Aman-Baliyan · 2026-07-23T16:37:28Z

give me some small preview of updates to let me feel a pain.

Example -> if we use jdkVersion >= 18 then we have to change the <pre> tag with {@snippet} inline tag as given below:

    // violation below

    /**
     * Content inside pre blocks should be ignored:
     * <pre>
     * &lt;code&gt;sample&lt;/code&gt;
     * &lt;a href="#method"&gt;link&lt;/a&gt;
     * </pre>
     */
    public void insidePreBlock() {
    }

   // violation fixed
  
    /**
     * Content inside snippet blocks should be ignored:
     * {@snippet :
     * <code>sample</code>
     * <a href="#method">link</a>
     * }
     */
    public void insideSnippetTag() {
    }

Although there is a advantage of using snippet tag because we do not need escaping characters inside it like pre.

Aman-Baliyan · 2026-07-23T17:58:19Z

working on ci/semaphore failures.

romani · 2026-07-23T23:07:36Z

@Aman-Baliyan , what is refactoring for jdk < 18 ?

is it same but @code should be used ?

ok, I see:
[ERROR] [checkstyle] [ERROR] /home/semaphore/checkstyle/.ci-temp/sevntu.checkstyle/sevntu-checks/src/main/java/com/github/sevntu/checkstyle/checks/coding/UnnecessaryParenthesesExtendedCheck.java:340:16: Prefer Javadoc inline tag '{@code ...}' over '<code>'. [PreferJavadocInlineTags]
https://github.com/sevntu-checkstyle/sevntu.checkstyle/blob/f852bff1047f2669ff06e17aec3676cd094c1ce5/sevntu-checks/src/main/java/com/github/sevntu/checkstyle/checks/coding/UnnecessaryParenthesesExtendedCheck.java#L43-L45

now I am thinking that we do not need to new property.
@code - Short, single-line code text.
@snippet - Rich, multi-line code examples.

https://openjdk.org/jeps/413

Although {@code ...} can be used by itself for small fragments of code, .....

So there is two migrations:
single-line and and <pre><code&gt... all escaped content - to {@code or {@snippet.
multi-line and and <pre><code&gt... all escaped content - to {@snippet.
multi-line and <pre>{@code ... - to {@snippet.
single-line and {@code ... (no <pre>) should be ok.

World is moved to jdk21, so all new javadoc tags are already out and this is most used jdk in world. old code will continue to stay with old jdk, no need to change that legacy code that works and docs are written.
Checkstyle is already using jdk21 as minimal requirements. So it means that this Check can be run only in jdk21, so no need for such property. Users naturally forced to use jdk21 minimum.

So our logic should be fully focus on chunks that are multi-line or single-line and suggest to upgrade.

May be in future users will ask us to make special property to always demand @snippet but it will be in far future, and we will get to know in what case @code is not good.

Do you agree with me ?

Aman-Baliyan · 2026-07-24T07:19:22Z

Do you agree with me ?

i agree with u.
So in this pr which one should we cover PreferJavadocLiteralInlineTags, PreferJavadocCodeOrSnippetInlineTags, PreferLinkJavadocInlineTag.

romani · 2026-07-24T07:25:07Z

up to you, you can close this PR and start new to not be confusing, might be the best approach.

start from PreferJavadocLiteralInlineTags (sounds like easy Check), then PreferJavadocCodeOrSnippetInlineTags

PreferLinkJavadocInlineTag is not clear for me, lets have issue creation for now and share there details ..

Aman-Baliyan · 2026-07-25T04:41:49Z

up to you, you can close this PR and start new to not be confusing, might be the best approach.

start from PreferJavadocLiteralInlineTags (sounds like easy Check), then PreferJavadocCodeOrSnippetInlineTags

PreferLinkJavadocInlineTag is not clear for me, lets have issue creation for now and share there details ..

as this pr contains a lot of work so better option is to change its description and names only . I will changed it to PreferJavadocLiteralInlineTags.

Aman-Baliyan · 2026-07-25T04:44:07Z

i will create a parent a umbrella issue for these check and create sub-issues for literal, link and code.

Aman-Baliyan · 2026-07-26T05:35:16Z

#20980

Aman-Baliyan · 2026-07-27T18:25:38Z

Current Implementation of this check ->

This check will flag -> < and > html entities.
Text inside code and pre html tags are skipped.
Text inside code, literal, snippet tags are skipped

Aman-Baliyan · 2026-07-27T18:31:39Z

@romani , according to current implementation we takes a text line traverse the line through loops and through violations for each entity found. Is this good?
Or should we throw a single error for all similar type of entities in a line.

By example ->

/**
 * Multiple: &lt;T&gt; and &lt;E&gt; generics.
 */
public class InputPreferLiteralJavadocInlineTagMultipleEntities {
}

Current ,

// 4 violations:
// 'Prefer Javadoc inline tag '{@literal <}' over '<'.'
// 'Prefer Javadoc inline tag '{@literal >}' over '>'.'
// 'Prefer Javadoc inline tag '{@literal <}' over '<'.'
// 'Prefer Javadoc inline tag '{@literal >}' over '>'.'

Should i change it to only 2 violations ->

// 'Prefer Javadoc inline tag '{@literal <}' over '<'.'
// 'Prefer Javadoc inline tag '{@literal >}' over '>'.'

romani added the blocked label Jul 9, 2026

romani removed the blocked label Jul 19, 2026

Aman-Baliyan force-pushed the inline branch from 1dbbeec to 6079c5c Compare July 20, 2026 20:07

Aman-Baliyan marked this pull request as draft July 20, 2026 20:08

Aman-Baliyan force-pushed the inline branch from 6079c5c to 62b34e0 Compare July 21, 2026 16:23

Aman-Baliyan marked this pull request as ready for review July 21, 2026 16:27

romani requested changes Jul 21, 2026

View reviewed changes

Aman-Baliyan force-pushed the inline branch from 62b34e0 to 5016b34 Compare July 23, 2026 16:20

Aman-Baliyan marked this pull request as draft July 23, 2026 18:44

Aman-Baliyan force-pushed the inline branch from 5016b34 to f0e522c Compare July 27, 2026 18:13

Issue 20984: Added new Check PreferLiteralJavadocInlineTag

9ccbe17

Aman-Baliyan force-pushed the inline branch from f0e522c to 9ccbe17 Compare July 27, 2026 18:20

Aman-Baliyan changed the title ~~Issue #18570: Added new check PreferJavadocInlineTags~~ Issue #20984: Added new check PreferLiteralJavadocInlineTag Jul 27, 2026

Aman-Baliyan mentioned this pull request Jul 28, 2026

new Check: PreferLiteralJavadocInlineTag #20984

Open

Uh oh!

Uh oh!

Conversation

Aman-Baliyan commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Aman-Baliyan commented Jun 20, 2026

Uh oh!

github-actions Bot commented Jun 20, 2026

Uh oh!

romani commented Jun 22, 2026

Uh oh!

romani commented Jun 22, 2026

Uh oh!

romani commented Jun 22, 2026

Uh oh!

romani commented Jul 9, 2026

Uh oh!

Aman-Baliyan commented Jul 21, 2026

Uh oh!

Aman-Baliyan commented Jul 21, 2026

Uh oh!

github-actions Bot commented Jul 21, 2026

Uh oh!

github-actions Bot commented Jul 21, 2026

Uh oh!

Aman-Baliyan commented Jul 21, 2026

Uh oh!

romani commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

romani left a comment

Choose a reason for hiding this comment

Uh oh!

romani Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Aman-Baliyan Jul 22, 2026

Choose a reason for hiding this comment

Uh oh!

romani Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Aman-Baliyan Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

romani Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Aman-Baliyan Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

romani Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Aman-Baliyan Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Aman-Baliyan commented Jul 22, 2026

Uh oh!

Aman-Baliyan commented Jul 22, 2026

Uh oh!

romani commented Jul 22, 2026

Uh oh!

Aman-Baliyan commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Aman-Baliyan commented Jul 23, 2026

Uh oh!

romani commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Aman-Baliyan commented Jul 24, 2026

Uh oh!

romani commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Aman-Baliyan commented Jul 25, 2026

Uh oh!

Aman-Baliyan commented Jun 20, 2026 •

edited

Loading

romani commented Jul 21, 2026 •

edited

Loading

Aman-Baliyan Jul 22, 2026 •

edited

Loading

Aman-Baliyan commented Jul 23, 2026 •

edited

Loading

romani commented Jul 23, 2026 •

edited

Loading

romani commented Jul 24, 2026 •

edited

Loading

Aman-Baliyan commented Jul 25, 2026 •

edited

Loading