JDK-8262886: javadoc generates broken links with {@inheritDoc} #17

hns · 2021-06-11T07:14:42Z

(This jdk17 PR is the continuation of PR openjdk/jdk#4459 in the mainline jdk repo, commits are identical at the point of transition.)

This change fixes a whole slew of shortcomings in the redirection of relative links in doc comments. The basic idea is that relative links are authored to work in their "native primary" environment (e.g. the package summary page for a package or the class page for a class and its members), and have to be rewritten when used in other contexts such as "use" or index pages.

A list of omissions that are fixed in this change:

Relative links in class or member comments were not redirected when inherited by other classes
Relative links in package comments were not rewritten when displayed in other package summaries as "related packages"
Fragment links used in foreign contexts were not completed with the file name
Relative links in module comments were not redirected at all

While fixing above issues I also made sure link rewriting is kept to a minimum, avoiding it as much as possible for elements that live in the same package.

Furthermore, the test for redirected relative links was a bit out of order. The javadoc command issued by the test returned ERROR because one of the source files contained non-valid HTML (an anchor with a name attribute to test whether that attribute would be modified). Because of this, the checkLinks() method was never invoked, which is a problem for a test that is supposed to make sure generated links are valid. I changed the test to use the valid id attribute instead of name and made sure checkLinks() is executed again.

I also added checks for the newly supported cases. I added a whole new test for modules since retrofitting the existing test to cover modules would not have been practical.

Progress

Change must not contain extraneous whitespace
Commit message must refer to an issue
Change must be properly reviewed

Issue

JDK-8262886: javadoc generates broken links with {@inheritdoc}

Reviewers

Jonathan Gibbons (@jonathan-gibbons - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk17 pull/17/head:pull/17
$ git checkout pull/17

Update a local copy of the PR:
$ git checkout pull/17
$ git pull https://git.openjdk.java.net/jdk17 pull/17/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 17

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

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk17/pull/17.diff

bridgekeeper · 2021-06-11T07:15:43Z

👋 Welcome back hannesw! 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 · 2021-06-11T07:17:35Z

@hns 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 · 2021-06-11T07:22:24Z

Webrevs

00: Full (0a597560)

jonathan-gibbons

Nice. Approved, but (as is often the case) there is potential for additional cleanup downstream.

jonathan-gibbons · 2021-06-30T16:03:02Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java

+        // Note: It would be nice to have getCurrentPageElement() return package and module elements
+        // in their respective writers, but other uses of the method are only interested in TypeElements.
+        Element currentPageElement = getCurrentPageElement();
+        if (currentPageElement == null) {
+            if (this instanceof PackageWriterImpl packageWriter) {
+                currentPageElement = packageWriter.packageElement;
+            } else if (this instanceof ModuleWriterImpl moduleWriter) {
+                currentPageElement = moduleWriter.mdle;
+            }
+        }


File an RFE?

I actually considered changing it as part of this change, but decided it wasn't worth changing several unrelated usages of the methods. In the end it's not a problem, except that the method name suggest it would also return package and module elements. Maybe we should just rename the method to getCurrentTypeElement to better represent its behaviour.

jonathan-gibbons · 2021-06-30T16:06:36Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java

        String text = tt.getBody();
-        if (element == null || utils.isOverviewElement(element) || shouldNotRedirectRelativeLinks()) {
+        if (!shouldRedirectRelativeLinks(element)) {
            return text;
        }
-
-        DocPath redirectPathFromRoot = new SimpleElementVisitor14<DocPath, Void>() {
-            @Override
-            public DocPath visitType(TypeElement e, Void p) {
-                return docPaths.forPackage(utils.containingPackage(e));
+        String lower = Utils.toLowerCase(text);
+        if (lower.startsWith("mailto:")
+                || lower.startsWith("http:")
+                || lower.startsWith("https:")
+                || lower.startsWith("file:")) {
+            return text;
+        }
+        if (text.startsWith("#")) {
+            // Redirected fragment link: prepend HTML file name to make it work
+            if (utils.isModule(element)) {
+                text = "module-summary.html" + text;
+            } else if (utils.isPackage(element)) {
+                text = DocPaths.PACKAGE_SUMMARY.getPath() + text;
+            } else {
+                TypeElement typeElement = element instanceof TypeElement
+                        ? (TypeElement) element : utils.getEnclosingTypeElement(element);
+                text = docPaths.forName(typeElement).getPath() + text;
            }
+        }


This is OK, but would it be better to try and create a URI from the text, and then use URI methods to check or manipulate the URI? Maybe an RFE...?

jonathan-gibbons · 2021-06-30T16:07:34Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java

-        }.visit(element);
-        if (redirectPathFromRoot == null) {
-            return text;
-        }
-        String lower = Utils.toLowerCase(text);
-        if (!(lower.startsWith("mailto:")
-                || lower.startsWith("http:")
-                || lower.startsWith("https:")
-                || lower.startsWith("file:"))) {
-            text = "{@" + (new DocRootTaglet()).getName() + "}/"
-                    + redirectPathFromRoot.resolve(text).getPath();
-            text = replaceDocRootDir(text);


ah OK, I see you were just moving stuff around ;-)

jonathan-gibbons · 2021-06-30T16:10:15Z

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java

+                text = "{@" + (new DocRootTaglet()).getName() + "}/"
+                        + redirectPathFromRoot.resolve(text).getPath();


OK, but icky code ...

icky to create an object to just get its name

icky to create a comment fragment to get the docRoot behavior

I accept this is old code moved around. Maybe file an RFE for cleanup

Thanks, Jon. I agree this change keeps alive too much old/obsolete code. I will file an RFE for cleanup.

jonathan-gibbons · 2021-06-30T16:11:17Z

test/langtools/jdk/javadoc/doclet/testRelativeLinks/TestRelativeLinks.java

        // This is not a relative path and should not be redirected.
        checkOutput("index-all.html", true,
            """
-                <div class="block"><a name="masters"></a>""");


jonathan-gibbons · 2021-06-30T16:12:25Z

test/langtools/jdk/javadoc/doclet/testRelativeLinks/TestRelativeLinks.java

+        // since the test uses explicit links to non-existent files,
+        // we create those files to avoid false positive errors from checkLinks


openjdk · 2021-06-30T16:14:27Z

@hns 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:

8262886: javadoc generates broken links with {@inheritDoc}

Reviewed-by: jjg

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 381 new commits pushed to the master branch:

be0ac92: 8269614: [s390] Interpreter checks wrong bit for slow path instance allocation
4b4bef4: 8269594: assert(_handle_mark_nesting > 1) failed: memory leak: allocating handle outside HandleMark
4ee400a: 8268320: Better error recovery for broken patterns in switch
ca283c3: 8265907: JVM crashes when matching VectorMaskCmp Node
c3c9189: 8269141: Switch statement containing pattern case label element gets in the loop during execution
6b64a79: 8268350: Remove assert that ensures thread identifier remains the same
90eb118: 8269528: VectorAPI Long512VectorTest fails on X86 KNL target
a661686: 8269065: [REDO] vmTestbase/vm/mlvm/anonloader/stress/oome/metaspace/Test.java failed with OutOfMemoryError
0d745ae: 8269034: AccessControlException for SunPKCS11 daemon threads
d042029: 8269529: javax/swing/reliability/HangDuringStaticInitialization.java fails in Windows debug build
... and 371 more: https://git.openjdk.java.net/jdk17/compare/1d2c7ac3f7492b335757bf0fd3f6ca3941c5fc72...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.

jonathan-gibbons · 2021-06-30T16:16:51Z

(general wishful thinking)
It would be nice to move the "relative links" code out of HtmlDocletWriter into another class more focussed on link handling. HtmlDocletWriter (and its historical supertypes, now eliminated) has always been a bit of a utils or misc dumping ground and it would be good to continue improving the abstractions in this area.

hns · 2021-07-01T07:24:37Z

/integrate

openjdk · 2021-07-01T07:25:45Z

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

f7ffd58: 8267602: [macos] [lanai] java/awt/PrintJob/Text/stringwidth.sh doesn't exit on cancelling print dialog
4930ae9: 8268592: JDK-8262891 causes an NPE in Lint.augment
9ac63a6: 8262841: Clarify the behavior of PhantomReference::refersTo
aba6c55: 8269703: ProblemList vmTestbase/nsk/jvmti/scenarios/sampling/SP07/sp07t002/TestDescription.java on Windows-X64 with -Xcomp
3e02224: 8269513: Clarify the spec wrt useOldISOCodes system property
0dc65d3: 8268897: [TESTBUG] compiler/compilercontrol/mixed/RandomCommandsTest.java must not fail on Command.quiet
3826012: 8268557: Module page uses unstyled table class
2b17e95: 8269691: ProblemList sun/management/jdp/JdpDefaultsTest.java on Linux-aarch64
1da5d4b: 8269486: CallerAccessTest fails for non server variant
be0ac92: 8269614: [s390] Interpreter checks wrong bit for slow path instance allocation
... and 380 more: https://git.openjdk.java.net/jdk17/compare/1d2c7ac3f7492b335757bf0fd3f6ca3941c5fc72...master

Your commit was automatically rebased without conflicts.

openjdk · 2021-07-01T07:26:02Z

@hns Pushed as commit 962f1c1.

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

hns added 5 commits June 10, 2021 10:48

JDK-8262886: javadoc generates broken links with {@inheritdoc}

b44cf6f

JDK-8262886: Further improvements

07f218b

JDK-8262886: Fix whitespace

3c110bd

JDK-8262886: Minor test change

89945cc

JDK-8262886: Fix copyright headers

0a59756

openjdk bot added the javadoc javadoc-dev@openjdk.java.net label Jun 11, 2021

hns mentioned this pull request Jun 11, 2021

JDK-8262886: javadoc generates broken links with {@inheritDoc} openjdk/jdk#4459

Closed

3 tasks

hns marked this pull request as ready for review June 11, 2021 07:18

openjdk bot added the rfr Pull request is ready for review label Jun 11, 2021

jonathan-gibbons approved these changes Jun 30, 2021

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Jun 30, 2021

openjdk bot closed this Jul 1, 2021

openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jul 1, 2021

		text = "{@" + (new DocRootTaglet()).getName() + "}/"
		+ redirectPathFromRoot.resolve(text).getPath();

		// since the test uses explicit links to non-existent files,
		// we create those files to avoid false positive errors from checkLinks

JDK-8262886: javadoc generates broken links with {@inheritDoc} #17

JDK-8262886: javadoc generates broken links with {@inheritDoc} #17

Uh oh!

Conversation

hns commented Jun 11, 2021 • 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 Jun 11, 2021

Uh oh!

openjdk bot commented Jun 11, 2021

Uh oh!

mlbridge bot commented Jun 11, 2021

Webrevs

Uh oh!

jonathan-gibbons left a comment • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openjdk bot commented Jun 30, 2021

Uh oh!

jonathan-gibbons commented Jun 30, 2021

Uh oh!

hns commented Jul 1, 2021

Uh oh!

openjdk bot commented Jul 1, 2021

Uh oh!

openjdk bot commented Jul 1, 2021

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

hns commented Jun 11, 2021 •

edited by openjdk bot

Loading

jonathan-gibbons left a comment •

edited

Loading