RFR: 8177100: APIs duplicated in JavaDoc [v5]
Hannes Wallnöfer
hannesw at openjdk.org
Wed May 28 13:50:00 UTC 2025
On Mon, 12 May 2025 14:46:39 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:
>> Please review this patch to fix a bug where a method can be documented multiple times
>> Consider these 4 classes
>>
>> A (interface)
>> / \
>> / \
>> (abstract class) C B ( interface)
>> \ /
>> \ /
>> D (class)
>>
>>
>> Where `A` declares `testA()`, `C` implements it `public final void testA()`, `B` extends `A` but does *not* override it, `D` extends `C` and implements `B`
>>
>> In the generated javadoc, `testA()` is documented twice.
>>
>> 
>>
>> After the patch, `testA()` is only documented once:
>>
>> 
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
>
> rename test to be more accurate and simplify code
I have to apologize for my previous review. When I noticed that JDK documentation had changed, my knee-jerk reaction was that the fix was wrong. But it is indeed the current documentation that is wrong.
For example in [StringBuilder](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/lang/StringBuilder.html#methods-inherited-from-class-java.lang.Object), the methods overridden in the hidden `AbstractStringBuilder` class should not be shown as declared in `CharSequence` as they are documented is if they were local methods in `StringBuilder.
Similarly (but without the hidden superclass), the `equals` and `hashCode` methods in [HashMap](https://docs.oracle.com/en/java/javase/24/docs/api/java.base/java/util/HashMap.html#methods-inherited-from-class-java.util.AbstractMap) should not be documented as declared in interface `Map`, but only in `AbstractMap` where they override the default implementation.
So your first solution (in the simplified form) was actually correct after all.
-------------
PR Comment: https://git.openjdk.org/jdk/pull/25123#issuecomment-2916427310
More information about the javadoc-dev
mailing list