RFR: 8330178: Clean up non-standard use of /** comments in `java.base`

[Jonathan Gibbons]

On Fri, 19 Apr 2024 10:44:27 GMT, Alexey Ivanov <aivanov at openjdk.org> wrote:

>> Please review a set of updates to clean up use of `/**` comments in the vicinity of declarations.
>> 
>> There are various categories of update:
>> 
>> * "Box comments" beginning with `/**`
>> * Misplaced doc comments before package or import statements
>> * Misplaced doc comments after the annotations for a declaration
>> * Dangling `/**` comments relating to a group of declarations, separate from the doc comments for each of those declarations
>> * Use of `/**` for the legal header at or near the top of the file
>> 
>> In one case, two doc comments before a declaration were merged, which fixes a bug/omission in the documented serialized form.
>
> src/java.base/share/classes/com/sun/crypto/provider/SunJCE.java line 37:
> 
>> 35: import static sun.security.util.SecurityProviderConstants.*;
>> 36: 
>> 37: /*
> 
> Should this be included in the main javadoc comment? The `@author` tags belong in the javadoc comment.
> 
> The javadoc itself is likely unreadable, when processed the entire comment becomes one very long paragraph.

That would be up to the relevant component to decide how to improve these comments. The goal here is proactively fix any warnings that may be generated about multiple doc comments on a declaration.

I note that neither comment contributes to the public API, and that `@author` tags are generally obsolete these days. The VCS metadata is a more accurate reflection of individual contributions.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/18846#discussion_r1572818078