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

[Alexey Ivanov]

On Thu, 8 Jun 2023 11:29:44 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/java.base/share/classes/java/util/concurrent/LinkedBlockingDeque.java line 635:
>> 
>>> 633:      * @return {@inheritDoc BlockingDeque}
>>> 634:      */
>>> 635:     public boolean offer(E e) {
>> 
>> Does this work for @param tags too? Just curious.
>
> The directed `{@inheritDoc <FQN>}` works for the main description, `@throws`, `@param` and `@return` tags. If your question is about why that particular doc comment does not use this:
> 
>     @param e {@inheritDoc BlockingDeque}
> 
> then the answer is that it's not necessary for keeping the API documentation unchanged.

I admit I can't parse this sentence:

> then the answer is that it's not necessary for keeping the API documentation unchanged.

Do you mean that you didn't add `@param e {@inheritDoc BlockingDeque}` here to keep the documentation unchanged?

You added `@inheritDoc` for `@param` tags in [FileCacheImageOutputStream.java](https://github.com/openjdk/jdk/pull/14357/files#diff-bc1e47b4c5c405826e7a062cabea04349ef72d5823b67e8616a680dcfcb5d4be) and others but not here.

So, do we need to add `@param` tags if the entire javadoc is inherited with `@inheritDoc`?

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

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