On Thu, 8 Jun 2023 09:55:27 GMT, Pavel Rappo <pra...@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
