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

[Pavel Rappo]

On Wed, 14 Jun 2023 01:15:51 GMT, Martin Buchholz <martin at 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