On Thu, 8 Jun 2023 15:47:26 GMT, Pavel Rappo <pra...@openjdk.org> wrote:
>> 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`?
>
> Copying an individual doc element using `{@inheritDoc}` never adds meta
> information on the generated HTML page to indicate where that doc element was
> copied from. It so happens in this particular case that the doc element's
> contents are the same in both possible supertypes (BlockingDeque and Queue)
> and look like this:
>
> @param e the element to add
>
> If the end result _on the HTML page_ will look identical no mater if I add
> `@param e {@inheritDoc BlockingDeque}` or not, I will not add it in _this_
> PR. This PR's goal is not restructuring the doc comment; in fact, such
> restructuring would be an anti-goal. It might be a goal for subsequent,
> area-specific PRs.
>
> Above I said that "`{@inheritDoc}` never adds meta information on the
> generated HTML page". You might have immediately thought about cases where
> you saw the "Description copied from interface/class" headings. However,
> those do not come from `{@inheritDoc}`; those come from empty comments (which
> inherit their content by omission, if you wish). So those headings DO
> indicate the source of the complete doc comment.
>
> Now about FileCacheImageOutputStream.java. If I hand't added directed
> inheritance there, the updated algorithm would've picked a different comment,
> which wouldn't have been identical to what was picked before:
>
> - javax.imageio.stream.ImageInputStream#flushBefore
> ```
> * @param pos a {@code long} containing the length of the
> * stream prefix that may be flushed.
> ```
>
> - javax.imageio.stream.ImageOutputStream#flushBefore:
> ```
> * @param pos a {@code long} containing the length of the
> * stream prefix that may be flushed to the destination.
> ```
> Hence, the correction. Does it clarify the matter?
Also, for better or worse, a lone `{@inheritDoc}` never inherits "everything"
from a supertype:
/** {@inheritDoc} */
It merely inherits the main description of a method. Other elements such as
parameter, exception or return information are inherited individually.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1223241132
