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

[Pavel Rappo]

On Thu, 8 Jun 2023 15:16:09 GMT, Alexey Ivanov <aivanov at openjdk.org> wrote:

>> 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`?

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?

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

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