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

[Martin Buchholz]

On Tue, 13 Jun 2023 10:11:28 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 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 14 additional commits since the last revision:
> 
>  - fix failing SourceDocTreeScannerTest
>  - Merge branch 'master' into 8285368
>  - feedback: use JavadocTester.out
>    
>    Also, trivially fixes grammar (word order) in a comment.
>  - feedback: remove unduly restrictive warning
>  - suggestion: vocabulary
>  - feedback: DocLint terminology
>  - feedback: use utils directly
>  - Merge branch 'master' into 8285368
>  - feedback: make warning less scary
>  - Disable problematic check
>    
>    This check is well-intended but problematic for JDK API Documentation
>    build, which errors on warnings.
>  - ... and 4 more: https://git.openjdk.org/jdk/compare/0db0007a...563a8761

We don't currently have a way to diff rendered javadoc, like my ancient BlenderRev hack?

src/java.base/share/classes/java/util/concurrent/ConcurrentHashMap.java line 1534:

> 1532: 
> 1533:     /**
> 1534:      * {@inheritDoc ConcurrentMap}

This clarifies the authors' intent, so is clear progress. 

Semantic difficulties remain:
- it would be nice to somehow declare that we never ever want to inherit doc from AbstractMap (or even at the module level, declare that AbstractFoo classes are specified only for subclass writers, not users).  Private inheritance?
- we never want to inherit AbstractFoo @implNotes
- ConcurrentMap does *not* have the same spec as ConcurrentHashMap, e.g. the latter does not permit null values.  Therefore one can argue that javadoc should *not* be inherited here.  Right now the main method spec from ConcurrentMap is perfectly suitable for ConcurrentHashMap, but one can imagine a future change to ConcurrentMap::putIfAbsent's spec that changes that, perhaps due to the null value handling difference.  We have a distasteful choice - brittle inheritance or copy-pasta.  In practice not so bad here, since these classes are maintained together.

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

Marked as reviewed by martin (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/14357#pullrequestreview-1478285774
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1228861243