Skip to content

InvalidJavadocPosition: false positive on module-info.java Javadoc #21112

Closed

Description

@vivek-0509

I have read check documentation: https://checkstyle.org/checks/javadoc/invalidjavadocposition.html
I have downloaded the latest checkstyle from: https://checkstyle.org/cmdline.html#Download_and_Run
I have executed the cli and showed it below, as cli describes the problem better than 1,000 words

Note: module-info.java is only parseable after #8240, so this is reproduced on that branch.

vivek@Viveks-MacBook-Air checkstyle % cat > config.xml <<'EOF'
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
    "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
  <module name="TreeWalker">
    <module name="InvalidJavadocPosition"/>
  </module>
</module>
EOF

vivek@Viveks-MacBook-Air checkstyle % cat > mod/module-info.java <<'EOF'
/**
 * Javadoc for the module.
 */
module com.example.app {
    requires java.base;
}
EOF

vivek@Viveks-MacBook-Air checkstyle % RUN_LOCALE="-Duser.language=en -Duser.country=US"
java $RUN_LOCALE -jar target/checkstyle-13.10.0-SNAPSHOT-all.jar -c config.xml mod/module-info.java

Starting audit...
[ERROR] mod/module-info.java:1:1: Javadoc comment is placed in the wrong location. [InvalidJavadocPosition]
Audit done.
Checkstyle ends with 1 errors.

The same Javadoc shape on a package declaration is accepted:

vivek@Viveks-MacBook-Air checkstyle % cat > pkg/package-info.java <<'EOF'
/**
 * Javadoc for the package.
 */
package com.example;
EOF

vivek@Viveks-MacBook-Air checkstyle % java $RUN_LOCALE -jar target/checkstyle-13.10.0-SNAPSHOT-all.jar -c config.xml pkg/package-info.java

Starting audit...
Audit done.

Describe what you expect in detail.

No violation. Javadoc on a module declaration is real documentation. The doc comment specification defines two block tags that may only appear there, @provides and @uses, both since JDK 9, and the javadoc tool generates a documentation page per module from these comments.

I verified this with the javadoc tool rather than relying on the specification alone. Running javadoc on a module whose declaration carries Javadoc with @provides and @uses descriptions produces a module-summary.html that contains the module Javadoc text and both tag descriptions:

vivek@Viveks-MacBook-Air jdocdemo % mkdir -p /tmp/jdocdemo/src/com.example.app/com/example/api && cd /tmp/jdocdemo

cat > src/com.example.app/module-info.java <<'EOF'
/**
 * Module level javadoc, this one is real documentation.
 *
 * @provides com.example.api.Service the default implementation
 * @uses com.example.api.Service looked up at runtime
 * @since 1.0
 */
module com.example.app {
    /**
     * Javadoc placed on a directive, does this appear anywhere?
     */
    exports com.example.api;

    uses com.example.api.Service;

    provides com.example.api.Service with com.example.api.Impl;
}
EOF
vivek@Viveks-MacBook-Air jdocdemo % cat > src/com.example.app/com/example/api/Service.java <<'EOF'
package com.example.api;

/** A service that can be discovered at runtime. */
public interface Service {
}
EOF
vivek@Viveks-MacBook-Air jdocdemo % cat > src/com.example.app/com/example/api/Impl.java <<'EOF'
package com.example.api;

/** The default implementation. */
public class Impl implements Service {

    /** Creates an instance. */
    public Impl() {
    }
}
EOF
vivek@Viveks-MacBook-Air jdocdemo % 
javadoc -quiet -d out --module-source-path src --module com.example.app
Image ---

The position is decided by JavadocUtil.isJavadocComment:

return sibling == null
    && (BlockCommentPosition.isOnType(blockComment)
        || BlockCommentPosition.isOnMember(blockComment)
        || BlockCommentPosition.isOnPackage(blockComment));

BlockCommentPosition has a branch for PACKAGE_DEF in isOnPackage and no equivalent for MODULE_DEF, so a module Javadoc satisfies none of the three. An isOnModule accepting the comment both before MODULE_DEF and on an annotated MODULE_DEF, added to that disjunction, resolves it.

Expected on the input above: no violations.

Precision requirement

The fix must accept Javadoc on the module declaration only, not anywhere inside the directive block. As the javadoc run above shows, the comment placed on the exports directive appears in no generated file at all, so it is not documentation and must keep being reported. Directives are documented through the @provides and @uses tags in the module's own Javadoc instead.

So on this input:

1: /**
2:  * Module javadoc.
3:  */
4: module com.example.app {
5:     /**
6:      * Javadoc on a directive.
7:      */
8:     requires java.base;
9: }

current output reports both comments:

1:1: Javadoc comment is placed in the wrong location. [InvalidJavadocPosition]
5:5: Javadoc comment is placed in the wrong location. [InvalidJavadocPosition]

and expected output after the fix keeps the second one:

5:5: Javadoc comment is placed in the wrong location. [InvalidJavadocPosition]

Additional context

This is not only a false positive, it also suppresses every Javadoc Check on module files, since Javadoc Checks process a comment only if isJavadocComment returns true. MissingDeprecated shows the effect, the module case is silent while the identical package case is reported:

vivek@Viveks-MacBook-Air checkstyle % cat > config2.xml <<'EOF'
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
    "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
    "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
  <module name="TreeWalker">
    <module name="MissingDeprecated"/>
  </module>
</module>
EOF

vivek@Viveks-MacBook-Air checkstyle % cat > mod2/module-info.java <<'EOF'
/**
 * Javadoc without the deprecated tag.
 */
@Deprecated
module com.example.app {
    requires java.base;
}
EOF

vivek@Viveks-MacBook-Air checkstyle % cat > pkg2/package-info.java <<'EOF'
/**
 * Javadoc without the deprecated tag.
 */
@Deprecated
package com.example;
EOF

vivek@Viveks-MacBook-Air checkstyle % java $RUN_LOCALE -jar target/checkstyle-13.10.0-SNAPSHOT-all.jar -c config2.xml mod2/module-info.java

Starting audit...
Audit done.

vivek@Viveks-MacBook-Air checkstyle % java $RUN_LOCALE -jar target/checkstyle-13.10.0-SNAPSHOT-all.jar -c config2.xml pkg2/package-info.java

Starting audit...
[ERROR] pkg2/package-info.java:5: Must include both @java.lang.Deprecated annotation and @deprecated Javadoc tag with description. [MissingDeprecated]
Audit done.
Checkstyle ends with 1 errors.

Fixing the position check removes this false positive and enables the Javadoc Checks that validate the comment itself: SummaryJavadoc, JavadocParagraph, SingleLineJavadoc, JavadocContentLocation, JavadocLeadingAsteriskAlign, JavadocMissingLeadingAsterisk, JavadocMissingWhitespaceAfterAsterisk, JavadocTagContinuationIndentation, NonEmptyAtclauseDescription and RequireEmptyLineBeforeBlockTagGroup. JavadocBlockTagLocation already lists provides and uses among its known tags.

Two Checks will need separate follow ups after this, since the position fix alone is not enough for them. MissingDeprecated resolves the annotation through AnnotationUtil.getAnnotationHolder, which maps PACKAGE_DEF and ENUM_CONSTANT_DEF to ANNOTATIONS and everything else to MODIFIERS, and MODULE_DEF has no MODIFIERS. AtclauseOrder has a DEFAULT_ORDER that does not include @provides or @uses.

Activity

  1. shrey070998 commented on Aug 6, 2026

    @shrey070998
    Contributor

    Hi, I’d like to work on this issue.

    I’ll add module declaration support to the Javadoc position classification,
    including tests for plain and annotated module declarations. I’ll also add
    negative coverage to ensure Javadoc placed on directives inside the module body
    continues to be reported.

  2. vivek-0509 commented on Aug 6, 2026

    @vivek-0509
    MemberAuthor

    @shrey070998 Please pick some other issue, the module grammar pr is not merged yet, and its already planned to be build on top of that PR...

  3. shrey070998 commented on Aug 6, 2026

    @shrey070998
    Contributor

    Understood, thank you for clarifying. I’ll pick another issue.

  4. added
    false positiveissues where check places violations on code, but should not
    on Aug 6, 2026
  5. added 6 commits that reference this issue on Aug 13, 2026
  6. added a commit that references this issue on Aug 18, 2026
  7. added this to the 14.0.0 milestone on Aug 18, 2026
  8. romani commented on Aug 18, 2026

    @romani
    Member

    fix is merged

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    approvedbugfalse positiveissues where check places violations on code, but should not

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions