RFR: JDK-8310453: Update javadoc of java.lang.Object

[Pavel Rappo]

On Wed, 21 Jun 2023 11:39:43 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> I had occasion to read over the javadoc sources in java.lang.Object recently and noticed a few items that could be updated.
>> 
>> There are some new or expanded API notes referring to methods in java.util.Objects. I added these references as apiNote items rather than, say, `@see` tags since  `@see` tag changes would propagate into classes that overrode the methods in questions.
>> 
>> Changing toString to use an inline `@return` tag has the consequence of omitting a trailing period, "." in the "Returns" section of its javadoc. This also omits  a trailing period in subclasses that use the `@return` statement of Object.toString in their own toString method. Likewise for hashCode.
>
> src/java.base/share/classes/java/lang/Object.java line 260:
> 
>> 258:      * }
>> 259:      * The {@link java.util.Objects#toIdentityString(Object)
>> 260:      * Objects.toIdentityString} method returns the string for an
> 
> That last sentence doesn't feel like it needs to be part of `@implSpec`, although there's definitely a connection.

That is, a clear connection to what's being described by that `@implSpec`.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14567#discussion_r1236873033