-
-
Notifications
You must be signed in to change notification settings - Fork 3.8k
Description
$ 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