Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Javadoc for package-info file is not validated #5769

Closed
rnveach opened this issue May 2, 2018 · 1 comment

Comments

Projects
None yet
2 participants
@rnveach
Copy link
Member

commented May 2, 2018

$ 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

@checkstyle checkstyle deleted a comment from rnveach May 3, 2018

@romani romani changed the title `JavadocUtils.isCorrectJavadocPosition` returns false on Javadoc for package-info file. Javadoc for package-info file is not validated May 3, 2018

rnveach added a commit to rnveach/checkstyle that referenced this issue Mar 4, 2019

rnveach added a commit that referenced this issue Mar 4, 2019

@rnveach

This comment has been minimized.

Copy link
Member Author

commented Mar 4, 2019

Fix was merged

@rnveach rnveach closed this Mar 4, 2019

@rnveach rnveach added this to the 8.19 milestone Mar 4, 2019

@romani romani added the bug label Mar 6, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.