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

[Jonathan Gibbons]

On Fri, 19 Apr 2024 10:53:11 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/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

Maybe, but only maybe, and if so, it would be out of scope for this work. That would be up to the relevant component team.

That being said, neither comment is part of any public API, and this comment is effectively already present in the first sentence of the actual doc comment.

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

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