On Sat, 6 Mar 2021 07:31:09 GMT, Bradford Wetmore <wetm...@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
