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

[Pavel Rappo]

On Thu, 8 Jun 2023 10:33:17 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   feedback: remove unduly restrictive warning
>
> src/java.base/share/classes/java/util/TreeMap.java line 1199:
> 
>> 1197:      * {@code add} or {@code addAll} operations.
>> 1198:      *
>> 1199:      * @return {@inheritDoc SortedMap}
> 
> An alternative here might be  add `{@return ...}` to the first sentence of the method description so that the return description exactly matches.

If we were to (re-)structure doc comments in the way you propose, I'd suggest we do it in a separate, non-jdk.javadoc  PR. I was simply trying to keep JDK API documentation unchanged.

One thing with the `@return` documentation inherited from SortedMap is that compared to the first sentence of TreeMap, it provides one extra bit of information: a set view of the mappings contained in this map, **sorted in ascending key order**. In order to keep that bit, the suggested inline `{@return ...}` should include more than just the first sentence.

> 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.

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

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