Comments starting with /// should not be reformatted as // /

[vorburger]

I'm toying (more "for fun") with https://openjdk.org/jeps/330 something in enola-dev/enola#971:

I am using https://www.jbang.dev, but Im not sure if this issue specific to that tool or really could be considered more generically:

As per https://www.jbang.dev/documentation/guide/latest/faq.html, and (apparently) partly inspired by https://golangcookbook.com/chapters/running/shebang/ in Go, given that JEP 330 "shebang" headers are still a bit of a PITA (see also related #1214), I'm starting a Java file with ///usr/bin/env jbang "$0" "$@" ; exit $?

google-java-format reformats ///usr/bin/env jbang "$0" "$@" ; exit $? to /// usr/bin/env jbang "$0" "$@" ; exit $? (note the added space), which breaks the magic.

Unfortunately, as per https://github.com/google/google-java-format/wiki/FAQ#why-cant-i-use-magic-comments-to-disable-formatting-for-certain-sections-of-code, it does not seem to be easily possible to suppress formatting that first line.

The only choice seems to be not to use google-java-format for such "script" like Java files (shame), or not to use that header in them.

[vorburger]

Oh, I just noticed #1193 and realized that this probably needs to be considered in the context of possible future JEP 467 (JDK 23) Markdown JavaDoc comments... so perhaps this needs to be smart and... do it only on the first line? (But beware of the "first line" coming after license header comment blocks.) Or perhaps it just leave any line starting with (?) ///[a-z] alone, and only format anything with /// which already has at least one space?

[vorburger]

FTR This is on v1.25.1, which is the 2nd most recent release today; looking at the 1.25.2 Release Notes, I have no reason to believe that this (just) got fixed.

[vorburger]

this needs to be smart and... do it only on the first line?

Issue #1218 (dupe?) also suggests using "in first lines" as the "rule" (heuristic?) for this.

That issue also points to https://bugs.openjdk.org/browse/JDK-8341907 about a similar problem in the javadoc linter which had this issue too, and apparently that got fixed in the JDK, using "on the first non-whitespace line of the program" as "rule". (But I wonder how that handles the "first line" coming after license header comment blocks.)