On Wed, 14 Jun 2023 01:15:51 GMT, Martin Buchholz <mar...@openjdk.org> wrote:
> * 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.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1229354100
