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

[Alexey Ivanov]

On Thu, 8 Jun 2023 15:51:22 GMT, Pavel Rappo <prappo at 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