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

[Alexey Ivanov]

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.

src/java.base/macosx/classes/apple/security/AppleProvider.java line 33:

> 31: /*
> 32:  * The Apple Security Provider.
> 33:  */

Does it make sense to incorporate this comment into the following javadoc comment?


/**
 * Defines the (an) Apple security provider.
 * ...
 */
@SuppressWarnings("serial") // JDK implementation class

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.

src/java.base/share/classes/sun/net/www/protocol/file/FileURLConnection.java line 38:

> 36: 
> 37: /**
> 38:  * Open an file input stream given a URL.

Suggestion:

 * Open a file input stream given a URL.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18846#discussion_r1572192780
PR Review Comment: https://git.openjdk.org/jdk/pull/18846#discussion_r1572184441
PR Review Comment: https://git.openjdk.org/jdk/pull/18846#discussion_r1572189001