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