Skip to content

Javadoc for package-info file is not validated #5769

@rnveach

Description

@rnveach
$ cat package-info.java
/** */
@javax.xml.bind.annotation.XmlSchema(namespace = "http://www.niku.com/xog/Query", elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED)
package com.mycompany.service.objects;

$ cat TestConfig.xml
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
          "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
          "http://www.puppycrawl.com/dtds/configuration_1_3.dtd">

<module name="Checker">
    <property name="charset" value="UTF-8"/>

    <module name="TreeWalker">
<module name="SummaryJavadoc" />
    </module>
</module>

$ java -jar checkstyle-8.10-all.jar -c TestConfig.xml package-info.java
Starting audit...
Audit done.

JavadocUtils.isCorrectJavadocPosition returns false for this javadoc.
Stackoverflow and the JLS says this is a Javadoc and can be placed inside the HTML file generated for the Javadoc.

https://stackoverflow.com/questions/624422/how-do-i-document-packages-in-java
https://docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1

It is recommended that package-info.java, if it is present, take the place of package.html for javadoc and other similar documentation generation systems. If this file is present, the documentation generation tool should look for the package documentation comment immediately preceding the (possibly annotated) package declaration in package-info.java. In this way, package-info.java becomes the sole repository for package-level annotations and documentation. If, in future, it becomes desirable to add any other package-level information, this file should prove a convenient home for this information.

Example of package-info.java with javadoc
https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#JSWOR639

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions