On Thu, 8 Jun 2023 15:51:22 GMT, Pavel Rappo <pra...@openjdk.org> wrote:
>> 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.
Thank you, it helps.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/14357#discussion_r1228577519
