RFR: 8263105: security-libs doclint cleanup

[Jonathan Gibbons]

On Sat, 6 Mar 2021 07:31:09 GMT, Bradford Wetmore <wetmore at openjdk.org> wrote:

> Fix various things pointed out by the most recent doclint run in the security-libs area.
> 
> This is docs only:  I will be checking doccheck/doclint, and will be running tier1/tier2 tests.  Minor spot checks on generated files.

I've read the first 10 files. The edits are definitely in the right direction, and will address the "missing comments" issues.

I'll leave it up to you and the others in your team to decide what level of stylistic consistency you would like for the new comments, but just having a relevant comment at all is a great start.

src/java.base/share/classes/java/security/BasicPermission.java line 497:

> 495:     /**
> 496:      * @serialData Default fields.
> 497:      */

FWIW, this doc comment will be ignored, because it will be superseded by the new comment on line 499.  At some point doen the road, you may get a warning from javac about an ignored doc comment.

src/java.base/share/classes/java/security/GuardedObject.java line 64:

> 62: 
> 63:     /**
> 64:      * The guard object

add a period?

src/java.base/share/classes/java/security/PermissionCollection.java line 105:

> 103:      * Whether this permission collection is read-only.
> 104:      * <p>
> 105:      * If set, add() will throw an exception.

maybe use `{@code}` or `{@link}` on add?

src/java.base/share/classes/java/security/Permissions.java line 581:

> 579:     /**
> 580:      * @serialData Default fields.
> 581:      */

Another ignored comment. I suggest just changing these to `/*` comments.

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

PR: https://git.openjdk.java.net/jdk/pull/2856