search

mathieucarbou / license-maven-plugin

Manage license headers in your source files
https://mathieu.carbou.me/license-maven-plugin/
Apache License 2.0
244 stars 86 forks source link

license headers for java files #118

Closed jitsni closed 5 years ago

jitsni commented 8 years ago

The plugin uses /** ... */ instead of /* ... */ for license headers in java files. Some of the IDEs (like intellij) marks them as "Dangling javadoc comment" (rightly so).

jfallows commented 8 years ago

+1 👍

manoelcampos commented 7 years ago

You can change this behaviour easily, just by adding the following lines to the configuration tag of the plugin inside the pom.xml:

<mapping>
    <java>SLASHSTAR_STYLE</java>
</mapping>

The comment styles are documented at the README.md file.

buckett commented 7 years ago

An alternative way to mark these comments is with /*- ... */ which indicates that they shouldn't be reformatted which is normally the case for license headers:

http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141999.html#350

This is supported by another license plugin through a property:

http://www.mojohaus.org/license-maven-plugin/update-file-header-mojo.html#useJavaNoReformatCommentStartTag

would it make sense for this plugin to have a standard format for this style?

buckett commented 7 years ago

And there's already a PR for this (/*- .. */): #115

ctubbsii commented 5 years ago

SLASHSTAR_STYLE should be default for *.java

The current default /** for Java isn't just "not preferred". It is outright incorrect. Javadocs are HTML markup, so they should be subject to formatting as HTML by build tooling (for example, to remove redundant whitespace in HTML source). Obviously, we don't want licenses to be interpreted as HTML markup and to be reformatted accordingly.

Additionally, Javadocs are also supposed to document specific language elements which they precede. A javadoc comment prefacing a package statement is invalid javadoc, because it cannot be rendered in any meaningful way into the generated javadoc pages. As such, this can really mess with some IDEs and Java parsers, which expect valid syntax for javadoc comments and (like the OP said) report this as a dangling comment.

The default behavior can be overridden, yes, but there are at least two problems with this:

  1. Most people don't override the defaults, and don't realize the problems above, so this default encourages very bad style, and
  2. As far as I can tell, the mapping cannot be overridden when running the tool manually from the Maven command-line (e.g. outside a Maven project, or without a Maven pom.xml).
mathieucarbou commented 5 years ago

Fixed in https://github.com/mycila/license-maven-plugin/pull/109