Turn dangling documentation comments into block comments

[jkschneider]

JDK 22 added -Xlint:dangling-doc-comments, which warns about a documentation comment that does not precede a declaration. A project building with -Werror therefore stops building purely because its Java version went up — its source is unchanged and was fine before.

Real shape, from a project that had documented a field and later commented the field out:

/** The field name. */
private String fieldName;

/** The request. */
// private transient ZestRequest request = null;

/** Instantiates a new zest field definition. */
public ZestFieldDefinition() {

warning: [dangling-doc-comments] documentation comment is not attached to any declaration
error: warnings found and -Werror specified

/** The request. */ documents nothing. Changing its opening delimiter to /* keeps the text and silences the warning, which is what a person would do.

Telling the two apart needs no heuristic

This is the part that makes the recipe safe. A documentation comment attached to a declaration is parsed into Javadoc.DocComment. One that is not stays in a prefix Space as a plain multiline TextComment whose text opens with the extra asterisk of /**. Confirmed against the parser across every position that matters:

source	parsed as
/** Doc. */ before a field	Javadoc.DocComment
/** Doc. */ before an annotated method	Javadoc.DocComment
/** Doc. */ before a commented-out field, with another doc comment following	TextComment
/** Doc. */ before an import	TextComment
/** Doc. */ between @Deprecated and the method	TextComment

So real API documentation cannot be caught by this recipe — it is a different node type entirely. That was the failure mode worth designing against, since silently stripping Javadoc would be far worse than the warning.

Note the parser attaches the nearest preceding documentation comment, which matches javac: an earlier one only becomes dangling when another documentation comment follows it. A test case with a single documentation comment will not reproduce the problem.

The comment leading a file is left alone, since that is conventionally the license header.

Tests

Seven cases: the shape above, before an import, after an annotation, multiline, and three negative cases covering attached documentation, the file header, and ordinary block comments.

Found by compiling the output of UpgradeToJava25 across a set of open source repositories.