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

[Sean Mullan]

On Thu, 6 Jul 2023 16:55:12 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 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

I think it may be one of those things that people won't realize the period should not be included and might miss as there are no errors and the rendered javadoc will include 2 periods, which is easy to miss. But now that I know about it, I will remember to check for it :)

I think I would be more in favor of starting the next sentence on a new line.

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

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