On Thu, 8 Jun 2023 10:33:17 GMT, Alan Bateman <al...@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
