Use SLASHSTAR instead of JAVADOC for Java

[jdhoek]

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 blocks 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 before in #43 'License headers shouldn't be in Javadoc style') a sensible default seems preferable.

[jdhoek]

@mathieucarbou What is the motivation for keeping Javadoc-style as the default?

[mathieucarbou]

I completely agree with you.
Now that IDE automatically reformat javadoc, using javadoc style as headers is really a pain and the slash style is more appropriate.

This plugin as a lot of history and at the time we created it, we look after a lot of projects and there were no convention at all: some were using one style, some the others.
So we just chose one randomly: we chose the javadoc style to be the default because java dev are used to it.

So since it breaks backward compatibility, it would be for another major release.

In the meantime, you can set this in the plugin config:

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

This is also what we do at work currently...

[jdhoek]

So since it breaks backward compatibility, it would be for another major release.

No problem, there is a workaround as you mention.

[mirabilos]

Note: in my #115 I’m deliberately not using a simple /* but /*- which, for some tools, has a special meaning.

These tools reformat the source code, and they also reformat all “simple” (“slash star”) comments, but not those starting with either /** or /*-, and as the former is JavaDoc, the latter is a “non-special” preformatted comment.

But I don’t see why we can’t have both.

[mathieucarbou]

/*- is not really common amongst java devs, as I explain in PR #115. If you really want this style perhaps I would suggest 2 styles: one standard without the dash (JAVAPKG_STYLE), and another one with the dash (JAVAPKG_DASH_STYLE). Let's keep this conv. in the PR ;-)

[mathieucarbou]

I am preparing version 4 of the plugin in which I'll allow breaking changes :-)

[friederbluemle]

Thanks @mathieucarbou - Any rough estimate when we can expect the release of version 4 with the fixed Java file header format?

[mathieucarbou]

No sorry. Had issues with both laptop and appartement besides taking care of the new baby so I wasn't even able to do it as planned this spring. I need to setup everything again to be a able to release. I wanted to work on a couple of issues first initially but now I will focus on 4.0 release and I'll do a 4.1 after.
I'll try to so it this weekend or the next one.

[friederbluemle]

Sure thing, no rush! Hope all is well now, and congrats on the baby! 👶🙂👍