RFR: 8285368: Overhaul doc-comment inheritance [v7]
Pavel Rappo
prappo at openjdk.org
Thu Jun 8 11:34:52 UTC 2023
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
More information about the javadoc-dev
mailing list