Repository navigation
Description
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
---
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
shrey070998 commentedon Aug 6, 2026
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.
vivek-0509 commentedon Aug 6, 2026
@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...
shrey070998 commentedon Aug 6, 2026
Understood, thank you for clarifying. I’ll pick another issue.
Issue checkstyle#21112: Fix InvalidJavadocPosition false positive on …
Issue checkstyle#21112: Fix InvalidJavadocPosition false positive on …
Issue checkstyle#21112: Fix InvalidJavadocPosition false positive on …
Issue checkstyle#21112: Fix InvalidJavadocPosition false positive on …
Issue checkstyle#21112: Fix InvalidJavadocPosition false positive on …
Issue checkstyle#21112: Fix InvalidJavadocPosition false positive on …
Issue #21112: Fix InvalidJavadocPosition false positive on module Jav…
romani commentedon Aug 18, 2026
fix is merged