8177100: APIs duplicated in JavaDoc #25123

nizarbenalla · 2025-05-08T14:53:41Z

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:

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed (2 reviews required, with at least 1 Reviewer, 1 Committer)

Issue

JDK-8177100: APIs duplicated in JavaDoc (Bug - P4)

Reviewers

Chen Liang (@liach - Reviewer)
Hannes Wallnöfer (@hns - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/25123/head:pull/25123
$ git checkout pull/25123

Update a local copy of the PR:
$ git checkout pull/25123
$ git pull https://git.openjdk.org/jdk.git pull/25123/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 25123

View PR using the GUI difftool:
$ git pr show -t 25123

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/25123.diff

Using Webrev

Link to Webrev Comment

bridgekeeper · 2025-05-08T14:54:50Z

👋 Welcome back nbenalla! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2025-05-08T14:56:15Z

@nizarbenalla This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8177100: APIs duplicated in JavaDoc

Reviewed-by: liach, hannesw

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 29 new commits pushed to the master branch:

fba74f7: 8361306: jdk.compiler-gendata needs to depend on java.base-launchers
56ebb8c: 8359110: Log accumulated GC and process CPU time upon VM exit
5cf349c: 8361355: Negative cases of Annotated.getAnnotationData implementations are broken
... and 26 more: https://git.openjdk.org/jdk/compare/c460f842bf768995b271cd6362940877a4a79665...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

openjdk · 2025-05-08T14:59:26Z

@nizarbenalla The following label will be automatically applied to this pull request:

javadoc

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2025-05-08T15:02:34Z

Webrevs

liach · 2025-05-08T15:07:15Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/VisibleMemberTable.java

@@ -689,10 +689,15 @@ private boolean allowInheritedMethod(ExecutableElement inheritedMethod,
        if (inInterface) {
            List<ExecutableElement> list = overriddenByTable.get(inheritedMethod);
            if (list != null) {


Can't we change this to if (list != null && !list.isEmpty) return false;?

Comments can be to update the overall block comment to indicate that there is no contention - when a method overrides multiple superinterfaces' methods, including when it is final from superclasses, the superclass method always prevails due to method resolution rules in Java. All interface methods have low resolution priority.

I think this simplification works just fine.

liach

Looks good, thanks!

hns · 2025-05-09T12:43:27Z

I'm not sure about this. @nizarbenalla have you tested whether this changes the output for JDK docs?

hns · 2025-05-09T12:49:11Z

There's a problem with character encoding in this patch, please do not integrate:

 /Users/runner/work/jdk/jdk/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/VisibleMemberTable.java:681: error: unmappable character (0x80) for encoding ascii
        // Multiple-Inheritance: No Contention. In Java???s method resolution,

liach · 2025-05-09T13:03:23Z

/reviewers 2 committer

openjdk · 2025-05-09T13:04:36Z

@liach
The total number of required reviews for this PR (including the jcheck configuration and the last /reviewers command) is now set to 2 (with at least 1 Reviewer, 1 Committer).

hns · 2025-05-09T13:20:44Z

As I suspected, this removes methods from the "Methods declared in interface XY" sections. For example, in the java.lang.StringBuilder doc page section for methods declared in java.lang.CharSequence it removes all methods except isEmpty(). So this is not the right place to fix this. I think we should only eliminate these overridden methods when they are to be documented in the subclass (when the declaring class is undocumented).

nizarbenalla · 2025-05-12T12:57:17Z

Hannes suggested in offline discussion where the check can be instead of the old approach.
I have checked that there is no change in the current JDK doc build after applying this patch.

Thanks for catching this oversight during the review.

nizarbenalla · 2025-05-12T13:33:27Z

Please don't review this yet, I plan on pushing an other update.

nizarbenalla · 2025-05-12T15:40:37Z

I've updated the test as the name was not accurate, and simplified the code in VisibleMemberTable

hns · 2025-05-28T13:46:50Z

I have to apologize for my previous review. When I noticed that JDK documentation had changed, my knee-jerk reaction was to assume that the change was wrong. But it is indeed the current documentation that is wrong.

For example in StringBuilder, the methods overridden in the hidden AbstractStringBuilder class should not be shown as declared in CharSequence as they are documented as local methods in StringBuilder (even though they are implemented in a hidden superclass).

Similarly (but without the hidden superclass), the equals and hashCode methods in HashMap 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.

liach

Looks identical to the initial version.

hns · 2025-06-10T14:08:15Z

Looks identical to the initial version.

@liach I realized the first version was right after all (see my comment above). We should not document a method as inherited from some interface when it is implemented in the local class or some superclass. So this gets rid of duplicate inherited methods, such as equals(Object) in HashMap appearing as inherited both from class AbstractMap and interface Map.

hns · 2025-06-10T14:20:19Z

test/langtools/jdk/javadoc/doclet/testDuplicateMethodsWarn/TestDuplicateMethods.java

+                "sb");
+        checkExit(Exit.OK);
+
+        checkOutput("sb/U.html", false,


Could you add a positive check to this test and testHashMapInheritance that the method is documented as expected (as local method in this test, and as inherited from the public abstract class in testHashMapInheritance), and that the method details has a "Specified by: ..." entry pointing to the interface method?

Updated the test to add a positive check. Tests are currently running in CI.
If the update look trivial enough, could you set the reviewer count back to 1?

nizarbenalla · 2025-06-24T16:18:33Z

Passes tier 1-3.

hns · 2025-07-01T15:14:05Z

test/langtools/jdk/javadoc/doclet/testDuplicateMethodsWarn/TestDuplicateMethods.java

+                <div class="horizontal-scroll">
+                <div class="member-signature"><span class="modifiers">public</span>&nbsp;<span class="element-name">V</span>()</div>
+                </div>
+                """);


That's the doc for the constructor. I was looking for method testJ inherited from abstract class PubJ.

I believe testJ does not have it's own doc in V.html. It only appears in the "methods inherited from class J" section

Yes, that's what should be tested.

Fixed in a34c4d5.

hns

Thanks, looks good.

And sorry for being nit-picky about the tests, but it's better to have all details covered.

nizarbenalla · 2025-07-04T12:17:55Z

Thank you for the reviews Hannes and Chen.

I will integrate once CI jobs are completed on all platforms. Better to be careful.

liach

The test update looks good.

nizarbenalla · 2025-07-04T15:09:24Z

/integrate

openjdk · 2025-07-04T15:10:26Z

Going to push as commit f2d2eef.
Since your change was applied there have been 31 commits pushed to the master branch:

1c56072: 8360775: Fix Shenandoah GC test failures when APX is enabled
f153e41: 8361253: CommandLineOptionTest library should report observed values on failure
fba74f7: 8361306: jdk.compiler-gendata needs to depend on java.base-launchers
... and 28 more: https://git.openjdk.org/jdk/compare/c460f842bf768995b271cd6362940877a4a79665...master

Your commit was automatically rebased without conflicts.

openjdk · 2025-07-04T15:10:37Z

@nizarbenalla Pushed as commit f2d2eef.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

merge methods from invisible supetypes

4a55b00

openjdk bot added the rfr Pull request is ready for review label May 8, 2025

openjdk bot added the javadoc [email protected] label May 8, 2025

liach reviewed May 8, 2025

View reviewed changes

simplify check

41578ad

liach approved these changes May 9, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label May 9, 2025

openjdk bot removed the ready Pull request is ready to be integrated label May 9, 2025

nizarbenalla added 5 commits May 9, 2025 14:24

fix comment

8d30046

revert VisibleMemberTable back to master

d630e6a

new approach - make sure there is no negative effect on JDK doc output

d9ef182

Merge branch 'master' into duplicate-APIs

fccec4c

update javadoc

c7b6269

rename test to be more accurate and simplify code

4c645c7

nizarbenalla requested a review from liach May 15, 2025 13:00

Merge branch 'master' into duplicate-APIs

684a880

Merge branch 'master' into duplicate-APIs

315922f

nizarbenalla added 4 commits June 2, 2025 13:19

revert back to master

23ce62f

revert back to simple earlier fix

b53817d

Merge branch 'master' into duplicate-APIs

071fcf3

Feedback from @hns - Expand test with new test cases

caeb20a

liach approved these changes Jun 10, 2025

View reviewed changes

hns reviewed Jun 10, 2025

View reviewed changes

nizarbenalla added 3 commits June 16, 2025 14:21

Merge branch 'master' into duplicate-APIs

55e29d3

Merge branch 'master' into duplicate-APIs

79a1aa0

review feedback: add positive test

00e7adc

liach approved these changes Jun 24, 2025

View reviewed changes

nizarbenalla requested a review from hns June 26, 2025 09:11

hns reviewed Jul 1, 2025

View reviewed changes

nizarbenalla added 2 commits July 2, 2025 17:17

Merge branch 'master' into duplicate-APIs

cd67eac

Fix test based on feedback

a34c4d5

hns approved these changes Jul 4, 2025

View reviewed changes

liach approved these changes Jul 4, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Jul 4, 2025

openjdk bot added the integrated Pull request has been integrated label Jul 4, 2025

openjdk bot closed this Jul 4, 2025

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jul 4, 2025

nizarbenalla deleted the duplicate-APIs branch July 4, 2025 15:28

8177100: APIs duplicated in JavaDoc #25123

8177100: APIs duplicated in JavaDoc #25123

Uh oh!

Conversation

nizarbenalla commented May 8, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented May 8, 2025

Uh oh!

openjdk bot commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented May 8, 2025

Uh oh!

mlbridge bot commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

liach May 8, 2025

Choose a reason for hiding this comment

Uh oh!

nizarbenalla May 8, 2025

Choose a reason for hiding this comment

Uh oh!

liach left a comment

Choose a reason for hiding this comment

Uh oh!

hns commented May 9, 2025

Uh oh!

hns commented May 9, 2025

Uh oh!

liach commented May 9, 2025

Uh oh!

openjdk bot commented May 9, 2025

Uh oh!

hns commented May 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nizarbenalla commented May 12, 2025

Uh oh!

nizarbenalla commented May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nizarbenalla commented May 12, 2025

Uh oh!

hns commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

liach left a comment

Choose a reason for hiding this comment

Uh oh!

hns commented Jun 10, 2025

Uh oh!

hns Jun 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nizarbenalla Jun 24, 2025

Choose a reason for hiding this comment

Uh oh!

nizarbenalla commented Jun 24, 2025

Uh oh!

hns Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

nizarbenalla Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

hns Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

nizarbenalla Jul 4, 2025

Choose a reason for hiding this comment

Uh oh!

hns left a comment

Choose a reason for hiding this comment

nizarbenalla commented May 8, 2025 •

edited by openjdk bot

Loading

openjdk bot commented May 8, 2025 •

edited

Loading

mlbridge bot commented May 8, 2025 •

edited

Loading

hns commented May 9, 2025 •

edited

Loading

nizarbenalla commented May 12, 2025 •

edited

Loading

hns commented May 28, 2025 •

edited

Loading

hns Jun 10, 2025 •

edited

Loading

nizarbenalla commented Jul 4, 2025 •

edited

Loading