add JAVAPKG_STYLE to supplant JAVADOC_STYLE, don’t bind by default

[mirabilos]

Closes: #38

[mathieucarbou]

Hi,

Would it be possible to rebase your PR and include a little update to the README.txt file (next to the JAVADOC_STYLE), plus a test against a java file with a package name ?

If a remember correctly, we have a test somewhere with every file extension type with / without header to take the input, format it and compare to the expected output.

Thanks :-)

[mirabilos]

OK, will have a look at that

[mathieucarbou]

I just see the dash and your comment (#109 (comment)).

My concern is that in Java it is really not common to have this.

Why the dash ? Which IDE reformat a header based on this "hook" ?

I wonder if we shouldn't have instead 2 different header styles because /*- is not really common amongst Java devs and I am pretty sure people would like the standard one, which is just /*

/*- 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)

[mirabilos]

On Tue, 16 Aug 2016, Mathieu Carbou wrote:

/*- is not really common amongst Java devs and I am pretty sure
people would like the standard one, which is just /*

Really?

I don’t insist on it, it’s just best practice and to avoid some
tools complaning, but I’ll drop the hyphen-minus from the format.

bye,

//mirabilos

tarent solutions GmbH
Rochusstraße 2-4, D-53123 Bonn • http://www.tarent.de/
Tel: +49 228 54881-393 • Fax: +49 228 54881-235
HRB 5168 (AG Bonn) • USt-ID (VAT): DE122264941
Geschäftsführer: Dr. Stefan Barth, Kai Ebenrett, Boris Esser, Alexander Steeg

[buckett]

The /*- .. */ is supposed to indicate that it shouldn't be reformatted:

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

[mirabilos]

I have a rough idea wrt. the testcases, but it’s a bit complicated; will look at it later, got to go now.

[mirabilos]

Hi Matthew,

+/*- The `/*- .. */` is supposed to indicate that it shouldn't be reformatted: http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141999.html#350

thanks **a lot** for this reference. I only knew it from C indent(1), and people in the Java™ world have been telling me all the time it does not apply to them — now I have a reference I can throw at them that it indeed does apply, from a very high-up place even. In C, indent works like this: - `/* … */` (inline and blocks) are reformatted - Blocks with `/*-` and `/**` are _not_ reformatted, but we tend towards `/*-` for licence information. In other languages, blocks with `/**` or (.NET) `/***` are used for in-code documentation, so these varied practices mix very well.

[mirabilos]

Christopher Tubbs dixit:

`SLASHSTAR_STYLE` should be default for `*.java`

/* will be auto-reformatted, which is not desired for licence headers, so /*- should be used for them.

The current default `/**` for Java isn't just "not preferred". It is outright incorrect.

Agreed.

[ctubbsii]

/* will be auto-reformatted, which is not desired for licence headers, so /*- should be used for them.

Like indent's use of *INDENT-OFF*, the trailing dash (-) there seems to be very tool-specific, and not part of the Java language itself.

It seems Oracle provided a helpful example of a valid Java comment block which also matches syntax for affecting the behavior of the indent tool (although, I don't know how much I would trust poorly written docs which weren't even reviewed to the point where somebody noticed that the <blockquote> html tag was left inside the <pre> tag, thus rendering incorrectly in the browser). It would be a mistake to interpret this example as an intentional part of the Java language itself. Java has no such special tooling built-in for formatting, and thus has no special syntax for indicating to format or not.

However, other formatting tools use other conventions for restricting reformatting, and don't respect the dash. Oracle could also have provided an example of how to do it with Eclipse instead (although, Eclipse, more helpfully also has a flag to avoid formatting the "header comment"):

// @formatter:off
/*
 * Here is a block comment with some very special
 * formatting that I want indent(1) to ignore.
 *
 *    one
 *        two
 *            three
 */
// @formatter:on

[mathieucarbou]

I'll merge the PR.
Even if I am not convinced about the usefulness of that because it is really tool-dependant behaviour, I am willing to ease some people's life if I can.

[astubbs]

How about adding an option or another style to have the copyright BEFORE the package? Docs say it should be after, but provides no reference as to why. An existing project that I'm cleaning up has it before. As I've seen in many others, and in the Oracle source files. Also see reference:
https://www.oracle.com/java/technologies/javase/codeconventions-codeexamples.html#182

I'll try with adding my own style, but seems this should be configurable?

[mathieucarbou]

How about adding an option or another style to have the copyright BEFORE the package? Docs say it should be after, but provides no reference as to why. An existing project that I'm cleaning up has it before. As I've seen in many others, and in the Oracle source files. Also see reference: https://www.oracle.com/java/technologies/javase/codeconventions-codeexamples.html#182

I'll try with adding my own style, but seems this should be configurable?

Hello,
These 2 styles should work: they place the header BEFORE the package.
Example: https://github.com/mathieucarbou/license-maven-plugin/blob/master/license-maven-plugin/src/main/java/com/mycila/maven/plugin/license/AbstractLicenseMojo.java

[astubbs]

These 2 styles should work: they place the header BEFORE the package

Thanks for responding!

Which two? JAVADOC_STYLE and JAVAPKG_STYLE? Oh that's confusing - and yes i see the linked example you provide is what I'm after.

But I wasn't getting that result by default with JAVAPKG_STYLE.

Is it due to the inline definition of the license used in the project?

I need JAVAPKG_STYLE and not JAVADOC_STYLE, but JAVAPKG_STYLE has the skip line directive:

    "^package [a-z_]+(\\.[a-z_][a-z0-9_]*)*;$",

I used this custom template and have the result I'm after:

<?xml version="1.0" encoding="UTF-8"?>
<additionalHeaders>
    <!-- Customisation to get copyright before package-->
    <!-- https://github.com/mathieucarbou/license-maven-plugin/pull/115#issuecomment-965097523-->
    <JAVAPKG_STYLE_BEFORE>
        <!-- Don't insert blank line first -->
        <firstLine><![CDATA[/*-]]></firstLine>
        <beforeEachLine><![CDATA[ * ]]></beforeEachLine>
        <endLine><![CDATA[ */EOL]]></endLine>
        <!-- don't skip any lines -->
        <!-- <skipLine><![CDATA[^package [a-z]+(\.[a-z][a-z0-9]*)*;$]]></skipLine>-->
        <firstLineDetectionPattern><![CDATA[(EOL)*(\s|\t)*/\*.*$]]></firstLineDetectionPattern>
        <lastLineDetectionPattern><![CDATA[.*\*/(\s|\t)*$]]></lastLineDetectionPattern>
        <allowBlankLines>false</allowBlankLines>
        <isMultiline>true</isMultiline>
        <padLines>false</padLines>
    </JAVAPKG_STYLE_BEFORE>
</additionalHeaders>

[mirabilos]

Antony Stubbs dixit:

How about adding an option or another style to have the copyright BEFORE the package?

No, that will cause errors or at least unnecessary warnings elsewhere. The package line has to come first. bye, //mirabilos -- Infrastrukturexperte • tarent solutions GmbH Am Dickobskreuz 10, D-53121 Bonn • http://www.tarent.de/ Telephon +49 228 54881-393 • Fax: +49 228 54881-235 HRB AG Bonn 5168 • USt-ID (VAT): DE122264941 Geschäftsführer: Dr. Stefan Barth, Kai Ebenrett, Boris Esser, Alexander Steeg

[ctubbsii]

@astubbs You probably just want SLASHSTAR_STYLE. That's what we use on https://github.com/apache/accumulo and it works great.

[astubbs]

No, that will cause errors or at least unnecessary warnings elsewhere. The package line has to come first.

That's odd because that's the style Oracle among many others use. Do you have any reference for that? (as per my Oracle linked example above, to show one example).

You probably just want SLASHSTAR_STYLE

Ah I see. Yeah that looks like it. The only other thing is I like the /*- style...