License headers shouldn't be in Javadoc style #43
Comments
|
You are able to redefine the comment styles used. See the documentation for it. If it does not work, please reopen with more details to be helped. |
jdhoek
added a commit
to LableOrg/license-maven-plugin
that referenced
this issue
Aug 12, 2016
In Java JAVADOC-style comment blocks are intended for comments interpreted by documentation building tools such as `javadoc`. Strictly speaking, the license header block should not be interpreted by these tools. The common approach in Java is to use the uninterpreted SLASHSTAR-style of comments for the license header. Recent iterations of the JDK have been getting stricter with its parsing of Javadoc comment blocks; floating comment block not applied to any Java element (type, method, or field) may well result in warnings in future versions of the compiler. In JetBrain's IntelliJ Java IDE, Javadoc-style license headers already cause a syntax warning. While the style of comments can be configured (as mentioned in mathieucarbou#43 'License headers shouldn't be in Javadoc style') a sensible default seems preferable.
it will be nice to paste a link to that section in documentation :) thanks |
mathieucarbou
pushed a commit
that referenced
this issue
Feb 1, 2019
In Java JAVADOC-style comment blocks are intended for comments interpreted by documentation building tools such as `javadoc`. Strictly speaking, the license header block should not be interpreted by these tools. The common approach in Java is to use the uninterpreted SLASHSTAR-style of comments for the license header. Recent iterations of the JDK have been getting stricter with its parsing of Javadoc comment blocks; floating comment block not applied to any Java element (type, method, or field) may well result in warnings in future versions of the compiler. In JetBrain's IntelliJ Java IDE, Javadoc-style license headers already cause a syntax warning. While the style of comments can be configured (as mentioned in #43 'License headers shouldn't be in Javadoc style') a sensible default seems preferable.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
In most open source java libraries the header looks like:
This plugin uses a javadoc style:
This becomes a problem when generating javadocs, because the license header content gets into all your documentation.
The text was updated successfully, but these errors were encountered: