RFR: 8285368: Overhaul doc-comment inheritance [v7]

[Pavel Rappo]

On Thu, 8 Jun 2023 09:55:27 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Please review this long-awaited change to documentation inheritance.
>> 
>> This change improves "methods comment algorithm" and introduces directed documentation inheritance. While "methods comment algorithm" -- automatic search for inheritable documentation -- has been improved, it still cannot read an author's mind so as to always find the documentation they intended. From now on, an author can state their intention, by providing an FQN of the superclass or superinterface from which to inherit documentation:
>> 
>> ​{@inheritDoc S}
>> 
>> Which is exactly what I did to counterbalance some of the JDK API Documentation changes caused by the change to "methods comment algorithm".
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   feedback: remove unduly restrictive warning

Note that the change to "method comments algorithm" uncovers and fixes some bugs to Object- or Object-like- methods. 

Using the provided [before][] and [after][] outputs, compare documentation for:

 * toString() in java.time.chrono.{Hijrah,Japanese,Minguo,ThaiBuddhist}Date
 * hashCode() in Hashtable, ConcurrentHashMap.KeySetView, java.util.jar.Attributes, com.sun.net.httpserver.Headers, com.sun.management.GcInfo
 * equals() in ConcurrentHashMap.KeySetView, com.sun.net.httpserver.Headers, com.sun.management.GcInfo
 * clone() in javax.management.ImmutableDescriptor, javax.management.modelmbean.DescriptorSupport, javax.naming.directory.BasicAttribute, javax.naming.directory.BasicAttributes
 
Perhaps some of those could be further refined using directed documentation inheritance. For example, ConcurrentHashMap.KeySetView is first and foremost a set and only then a collection. That suggests that the documentation for Object-like methods could be inherited from (some) set rather than a "generic" collection.

Also, the javax.management.ImmutableDescriptor and javax.management.modelmbean.DescriptorSupport clone methods require some attention from area experts. It's likely that those methods' doc comments need to fully inherit documentation from Descriptor.clone(), not just its `@return` tag.

[before]: https://cr.openjdk.org/~prappo/8285368/1/api
[after]: https://cr.openjdk.org/~prappo/8285368/2/api

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

PR Comment: https://git.openjdk.org/jdk/pull/14357#issuecomment-1582477351