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

[Jonathan Gibbons]

On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons <jjg 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.

> It is somewhat off-topic. Yet I noticed javadoc comments in some files are followed a blank line, and others aren't. Out of my curiosity, is there a convention about the blank line between the javadoc comment and the class or interface declaration? Should there be one?
> 
> ```java
> /**
>  * This is a class.
>  */
> public class A {}
> ```
> 
> or
> 
> ```java
> /**
>  * This is a class.
>  */
> 
> public class A {}
> ```
> 
> Which is the most common? Which is preferred?

We do not have an overall style guide.   The conventional wisdom for editing any existing file is to follow the style in that file, if such a style can be discerned.

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

PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2067156407