RFR: 8311170: Simplify and modernize equals and hashCode in security area [v4]

[Jonathan Gibbons]

On Thu, 6 Jul 2023 16:41:37 GMT, Sean Mullan <mullan at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains six additional commits since the last revision:
>> 
>>  - Merge branch 'master' into 8311170
>>  - Be consistent with the rest of the change
>>  - Fix reported bugs
>>  - Add even more cases and tidy up
>>  - More cases
>>  - Initial commit
>
> src/java.base/share/classes/java/security/cert/CertPath.java line 191:
> 
>> 189: 
>> 190:     /**
>> 191:      * {@return the hashcode value for this certification path} The hash code
> 
> This looks a bit odd w/o a period at the end of the `}`. Is it optional? [The javadoc spec](https://docs.oracle.com/en/java/javase/20/docs/specs/javadoc/doc-comment-spec.html#return) isn't very clear on that - perhaps you could clarify that in the spec.
> 
> If it is optional, my general preference would be to include the period, as it makes the code more readable.
> 
> Or maybe if you started "The hash code ..." on a new line it would look more reasonable.

While I agree it looks "a bit odd", the problem is having to address the two ways in which the tag is rendered:

1. As the first sentence. In this case, the text in the braces is preceded by `Returns` and followed by a period.
2. As the equivalent for an `@return` tag, where `Returns:` is a bold heading, and the content is a phrase, and (generally) not followed by a period.

The current guideline is that the period should not be present. Elsewhere, the "oddness" is reduced by putting
a newline after the tag, so that the `{@return}` tag stands on a line by itself.  To forestall any possible suggestion,
I would not be in favor of looking outside the tag to see if there is a period following the tag.

We can clarify the spec.

If you are uncomfortable with the usage here, it is always possible to avoid using the short inline form, and to "duplicate" the text and use an old-fashioned plain first sentence, and an old-fashioned `@return` "block" tag

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14738#discussion_r1254696669