On Wed, 14 Jun 2023 10:07:05 GMT, Pavel Rappo <pra...@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
