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

[Martin Buchholz]

On Wed, 14 Jun 2023 10:07:05 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> 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.
>
>> * we never want to inherit AbstractFoo @implNotes
> 
> `@implNote`, `@apiNote` and `@implSpec` can only be inherited via explicit `{@inheritDoc}`:
> 
>     @implSpec {@inheritDoc}
> 
>> * 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.
> 
> That state of affairs predates this PR and is merely highlighted by it. Sadly, I'm not sure how JavaDoc can help here. Annotations, contracts, inspections, and doc tests come to mind; but none of these are supported by JavaDoc at the moment.

(There's nothing wrong with this PR)

Back in the 1980s there was a lot of optimism that OOP would be a big leap forward in software engineering.
But especially the "inheritance" part of OOP has been disappointing - unexpectedly brittle!
javadoc inheritance in collection classes was particularly interesting to me from this perspective.
Especially with the multiple inheritance that java was mostly reluctant to adopt.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1231765877