8345770: javadoc: API documentation builds are not always reproducible

hns · hns · commit 4fc43b0b49c3 · 2024-12-16T08:09:52.000Z
Reviewed-by: nbenalla, liach
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java
@@ -106,7 +106,6 @@ public ClassUseWriter(HtmlConfiguration configuration,
             pkgToPackageAnnotations = new TreeSet<>(comparators.classUseComparator());
             pkgToPackageAnnotations.addAll(mapper.classToPackageAnnotations.get(typeElement));
         }
-        configuration.currentTypeElement = typeElement;
         this.pkgSet = new TreeSet<>(comparators.packageComparator());
         this.pkgToClassTypeParameter = pkgDivide(mapper.classToClassTypeParam);
         this.pkgToSubclassTypeParameter = pkgDivide(mapper.classToSubclassTypeParam);
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java
@@ -94,7 +94,6 @@ public ClassWriter(HtmlConfiguration configuration, TypeElement typeElement,
                        ClassTree classTree) {
         super(configuration, configuration.docPaths.forClass(typeElement));
         this.typeElement = typeElement;
-        configuration.currentTypeElement = typeElement;
         this.classTree = classTree;
 
         pHelper = new PropertyUtils.PropertyHelper(configuration, typeElement);
@@ -506,7 +505,7 @@ protected Content getClassInfo(Content classInfo) {
     }
 
     @Override
-    public TypeElement getCurrentPageElement() {
+    public TypeElement getCurrentTypeElement() {
         return typeElement;
     }
 
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java
@@ -104,11 +104,6 @@ public class HtmlConfiguration extends BaseConfiguration {
      */
     public DocPath topFile = DocPath.empty;
 
-    /**
-     * The TypeElement for the class file getting generated.
-     */
-    public TypeElement currentTypeElement = null;  // Set this TypeElement in the ClassWriter.
-
     /**
      * The collections of items for the main index.
      * This field is only initialized if {@code options.createIndex()}
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
@@ -1024,11 +1024,10 @@ public String getEnclosingPackageName(TypeElement te) {
     }
 
     /**
-     * Return the main type element of the current page or null for pages that don't have one.
-     *
-     * @return the type element of the current page.
+     * {@return the type element documented by this writer if it is a {@code ClassWriter},
+     * or null for any other kind of writer}
      */
-    public TypeElement getCurrentPageElement() {
+    public TypeElement getCurrentTypeElement() {
         return null;
     }
 
@@ -1912,7 +1911,7 @@ private boolean shouldRedirectRelativeLinks(Element element) {
         // Retrieve the element of this writer if it is a "primary" writer for an element.
         // 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();
+        Element currentPageElement = getCurrentTypeElement();
         if (currentPageElement == null) {
             if (this instanceof PackageWriter packageWriter) {
                 currentPageElement = packageWriter.packageElement;
@@ -1951,7 +1950,7 @@ public Content invalidTagOutput(String summary, Optional<Content> detail) {
      */
     private boolean inSamePackage(Element element) {
         Element currentPageElement = (this instanceof PackageWriter packageWriter)
-                ? packageWriter.packageElement : getCurrentPageElement();
+                ? packageWriter.packageElement : getCurrentTypeElement();
         return currentPageElement != null && !utils.isModule(element)
                 && Objects.equals(utils.containingPackage(currentPageElement),
                 utils.containingPackage(element));
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java
@@ -270,7 +270,7 @@ protected Content getClassLink(HtmlLinkInfo linkInfo) {
             TypeElement enclosing = utils.getEnclosingTypeElement(linkInfo.getTargetMember());
             Set<ElementFlag> enclosingFlags = utils.elementFlags(enclosing);
             if (flags.contains(ElementFlag.PREVIEW) && enclosingFlags.contains(ElementFlag.PREVIEW)) {
-                if (enclosing.equals(m_writer.getCurrentPageElement())) {
+                if (enclosing.equals(m_writer.getCurrentTypeElement())) {
                     //skip the PREVIEW tag:
                     flags = EnumSet.copyOf(flags);
                     flags.remove(ElementFlag.PREVIEW);
@@ -294,7 +294,7 @@ protected Content getClassLink(HtmlLinkInfo linkInfo) {
         if (utils.isIncluded(typeElement)) {
             if (configuration.isGeneratedDoc(typeElement) && !utils.hasHiddenTag(typeElement)) {
                 DocPath fileName = getPath(linkInfo);
-                if (linkInfo.linkToSelf() || typeElement != m_writer.getCurrentPageElement()) {
+                if (linkInfo.linkToSelf() || typeElement != m_writer.getCurrentTypeElement()) {
                         link.add(m_writer.links.createLink(
                                 fileName.fragment(linkInfo.getFragment()),
                                 label, linkInfo.getStyle(), linkInfo.getTitle()));
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/InheritDocTaglet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/InheritDocTaglet.java
@@ -133,7 +133,7 @@ private Content retrieveInheritedDocumentation(TagletWriter writer,
                 }
             } catch (DocFinder.NoOverriddenMethodFound e) {
                 String signature = utils.getSimpleName(method)
-                        + utils.flatSignature(method, writer.getCurrentPageElement());
+                        + utils.flatSignature(method, writer.getCurrentTypeElement());
                 messages.warning(method, "doclet.noInheritedDoc", signature);
             }
             return replacement;
@@ -157,7 +157,7 @@ private Content retrieveInheritedDocumentation(TagletWriter writer,
             }
         } else {
             String signature = utils.getSimpleName(method)
-                    + utils.flatSignature(method, writer.getCurrentPageElement());
+                    + utils.flatSignature(method, writer.getCurrentTypeElement());
             messages.warning(method, "doclet.noInheritedDoc", signature);
         }
         return replacement;
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/LinkTaglet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/LinkTaglet.java
@@ -264,7 +264,7 @@ Content linkSeeReferenceOutput(Element holder,
                 }
             }
             String refMemName = refFragment;
-            if (config.currentTypeElement != containing) {
+            if (htmlWriter.getCurrentTypeElement() != containing) {
                 refMemName = (utils.isConstructor(refMem))
                         ? refMemName
                         : utils.getSimpleName(containing) + "." + refMemName;
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/ReturnTaglet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/ReturnTaglet.java
@@ -94,7 +94,7 @@ public Content getAllBlockTagOutput(Element holder, TagletWriter tagletWriter) {
         List<? extends ReturnTree> tags = utils.getReturnTrees(holder);
 
         // make sure we are not using @return on a method with the void return type
-        TypeMirror returnType = utils.getReturnType(tagletWriter.getCurrentPageElement(), method);
+        TypeMirror returnType = utils.getReturnType(tagletWriter.getCurrentTypeElement(), method);
         if (returnType != null && utils.isVoid(returnType)) {
             if (!tags.isEmpty() && !config.isDocLintReferenceGroupEnabled()) {
                 messages.warning(holder, "doclet.Return_tag_on_void_method");
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/TagletWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/TagletWriter.java
@@ -201,12 +201,10 @@ public Content invalidTagOutput(String summary, Optional<String> detail) {
     }
 
     /**
-     * Returns the main type element of the current page or null for pages that don't have one.
-     *
-     * @return the type element of the current page or null.
+     * {@return the type element documented by the current {@code HtmlDocletWriter} (may be null)}
      */
-    public TypeElement getCurrentPageElement() {
-        return htmlWriter.getCurrentPageElement();
+    public TypeElement getCurrentTypeElement() {
+        return htmlWriter.getCurrentTypeElement();
     }
 
     /**
@@ -411,7 +409,7 @@ public String visitType(TypeElement e, Void p) {
             public String visitExecutable(ExecutableElement e, Void p) {
                 return utils.getFullyQualifiedName(utils.getEnclosingTypeElement(e))
                         + "." + utils.getSimpleName(e)
-                        + utils.flatSignature(e, htmlWriter.getCurrentPageElement());
+                        + utils.flatSignature(e, htmlWriter.getCurrentTypeElement());
             }
 
             @Override
@@ -476,11 +474,11 @@ private boolean isLongOrHasComma(Content c) {
     // Test if element is the same as or belongs to the current page element
     private boolean isDifferentTypeElement(Element element) {
         if (element.getKind().isDeclaredType()) {
-            return element != getCurrentPageElement();
+            return element != getCurrentTypeElement();
         } else if (element.getKind() == ElementKind.OTHER) {
             return false;
         } else {
-            return utils.getEnclosingTypeElement(element) != getCurrentPageElement();
+            return utils.getEnclosingTypeElement(element) != getCurrentTypeElement();
         }
     }
 }
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/ThrowsTaglet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/ThrowsTaglet.java
@@ -211,7 +211,7 @@ public Content getAllBlockTagOutput(Element holder, TagletWriter tagletWriter) {
             // since {@inheritDoc} in @throws is processed by ThrowsTaglet (this taglet) rather than
             // InheritDocTaglet, we have to duplicate some of the behavior of the latter taglet
             String signature = utils.getSimpleName(holder)
-                    + utils.flatSignature((ExecutableElement) holder, tagletWriter.getCurrentPageElement());
+                    + utils.flatSignature((ExecutableElement) holder, tagletWriter.getCurrentTypeElement());
             messages.warning(holder, "doclet.noInheritedDoc", signature);
         }
         return tagletWriter.getOutputInstance(); // TODO: consider invalid rather than empty output
@@ -235,7 +235,7 @@ private Content getAllBlockTagOutput0(Element holder)
         }
         var executable = (ExecutableElement) holder;
         ExecutableType instantiatedType = utils.asInstantiatedMethodType(
-                tagletWriter.getCurrentPageElement(), executable);
+                tagletWriter.getCurrentTypeElement(), executable);
         List<? extends TypeMirror> substitutedExceptionTypes = instantiatedType.getThrownTypes();
         List<? extends TypeMirror> originalExceptionTypes = executable.getThrownTypes();
         Map<TypeMirror, TypeMirror> typeSubstitutions = getSubstitutedThrownTypes(
diff --git a/test/langtools/jdk/javadoc/doclet/testModules/TestModules.java b/test/langtools/jdk/javadoc/doclet/testModules/TestModules.java
@@ -621,7 +621,7 @@ void checkModuleTags() {
                     estpkgmdltags"><code>TestClassInModuleTags</code></a>.""",
                 """
                     Member Link: <a href="testpkgmdltags/TestClassInModuleTags.html#testMethod(java.\
-                    lang.String)"><code>testMethod(String)</code></a>.""",
+                    lang.String)"><code>TestClassInModuleTags.testMethod(String)</code></a>.""",
                 """
                     Package Link: <a href="testpkgmdltags/package-summary.html"><code>testpkgmdltags</code></a>.""",
                 """
@@ -892,7 +892,7 @@ void checkModuleModeCommon() {
                      Type Link: <a href="moduletags/testpkgmdltags/TestClassInModuleTags.html" title\
                     ="class in testpkgmdltags"><code>TestClassInModuleTags</code></a>.<br>
                      Member Link: <a href="moduletags/testpkgmdltags/TestClassInModuleTags.html#test\
-                    Method(java.lang.String)"><code>testMethod(String)</code></a>.<br>
+                    Method(java.lang.String)"><code>TestClassInModuleTags.testMethod(String)</code></a>.<br>
                      Package Link: <a href="moduletags/testpkgmdltags/package-summary.html"><code>testpkgmdltags</code></a>.<br></div>
                     </div>""");
         checkOutput("moduleA/module-summary.html", true,
diff --git a/test/langtools/jdk/javadoc/doclet/testUseOption/TestUseOption.java b/test/langtools/jdk/javadoc/doclet/testUseOption/TestUseOption.java
@@ -24,7 +24,7 @@
 /*
  * @test
  * @bug 4496290 4985072 7006178 7068595 8016328 8050031 8048351 8081854 8071982 8162363 8175200 8186332
- *      8182765 8196202 8202626 8261976 8323698
+ *      8182765 8196202 8202626 8261976 8323698 8345770
  * @summary A simple test to ensure class-use files are correct.
  * @library /tools/lib ../../lib
  * @modules jdk.javadoc/jdk.javadoc.internal.tool
@@ -107,7 +107,10 @@ public void test1() {
         );
         checkOutput("pkg1/class-use/UsedInterface.html", true,
            """
-               <a href="../AnAbstract.html" class="type-name-link" title="class in pkg1">AnAbstract</a>"""
+               <a href="../AnAbstract.html" class="type-name-link" title="class in pkg1">AnAbstract</a>""",
+           """
+               Link to interface method: <a href="../UsedInterface.html#doNothing()"><code>Use\
+               dInterface.doNothing()</code></a>."""
         );
         checkOutput("pkg1/class-use/UsedInterface.html", true,
             "../C10.html#withReturningTypeParameters()"
diff --git a/test/langtools/jdk/javadoc/doclet/testUseOption/pkg1/AnAbstract.java b/test/langtools/jdk/javadoc/doclet/testUseOption/pkg1/AnAbstract.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -22,4 +22,8 @@
  */
 
 package pkg1;
+
+/**
+ * Link to interface method: {@link #doNothing}.
+ */
 public abstract class AnAbstract implements UsedInterface {}

Original file line number	Diff line number	Diff line change
`@@ -106,7 +106,6 @@ public ClassUseWriter(HtmlConfiguration configuration,`
`106`	`106`	`pkgToPackageAnnotations = new TreeSet<>(comparators.classUseComparator());`
`107`	`107`	`pkgToPackageAnnotations.addAll(mapper.classToPackageAnnotations.get(typeElement));`
`108`	`108`	`}`
`109`		`- configuration.currentTypeElement = typeElement;`
`110`	`109`	`this.pkgSet = new TreeSet<>(comparators.packageComparator());`
`111`	`110`	`this.pkgToClassTypeParameter = pkgDivide(mapper.classToClassTypeParam);`
`112`	`111`	`this.pkgToSubclassTypeParameter = pkgDivide(mapper.classToSubclassTypeParam);`
Original file line number	Diff line number	Diff line change
`@@ -94,7 +94,6 @@ public ClassWriter(HtmlConfiguration configuration, TypeElement typeElement,`
`94`	`94`	`ClassTree classTree) {`
`95`	`95`	`super(configuration, configuration.docPaths.forClass(typeElement));`
`96`	`96`	`this.typeElement = typeElement;`
`97`		`- configuration.currentTypeElement = typeElement;`
`98`	`97`	`this.classTree = classTree;`
`99`	`98`
`100`	`99`	`pHelper = new PropertyUtils.PropertyHelper(configuration, typeElement);`
`@@ -506,7 +505,7 @@ protected Content getClassInfo(Content classInfo) {`
`506`	`505`	`}`
`507`	`506`
`508`	`507`	`@Override`
`509`		`- public TypeElement getCurrentPageElement() {`
	`508`	`+ public TypeElement getCurrentTypeElement() {`
`510`	`509`	`return typeElement;`
`511`	`510`	`}`
`512`	`511`
Original file line number	Diff line number	Diff line change
`@@ -133,7 +133,7 @@ private Content retrieveInheritedDocumentation(TagletWriter writer,`
`133`	`133`	`}`
`134`	`134`	`} catch (DocFinder.NoOverriddenMethodFound e) {`
`135`	`135`	`String signature = utils.getSimpleName(method)`
`136`		`- + utils.flatSignature(method, writer.getCurrentPageElement());`
	`136`	`+ + utils.flatSignature(method, writer.getCurrentTypeElement());`
`137`	`137`	`messages.warning(method, "doclet.noInheritedDoc", signature);`
`138`	`138`	`}`
`139`	`139`	`return replacement;`
`@@ -157,7 +157,7 @@ private Content retrieveInheritedDocumentation(TagletWriter writer,`
`157`	`157`	`}`
`158`	`158`	`} else {`
`159`	`159`	`String signature = utils.getSimpleName(method)`
`160`		`- + utils.flatSignature(method, writer.getCurrentPageElement());`
	`160`	`+ + utils.flatSignature(method, writer.getCurrentTypeElement());`
`161`	`161`	`messages.warning(method, "doclet.noInheritedDoc", signature);`
`162`	`162`	`}`
`163`	`163`	`return replacement;`
Original file line number	Diff line number	Diff line change
`@@ -264,7 +264,7 @@ Content linkSeeReferenceOutput(Element holder,`
`264`	`264`	`}`
`265`	`265`	`}`
`266`	`266`	`String refMemName = refFragment;`
`267`		`- if (config.currentTypeElement != containing) {`
	`267`	`+ if (htmlWriter.getCurrentTypeElement() != containing) {`
`268`	`268`	`refMemName = (utils.isConstructor(refMem))`
`269`	`269`	`? refMemName`
`270`	`270`	`: utils.getSimpleName(containing) + "." + refMemName;`
Original file line number	Diff line number	Diff line change
`@@ -201,12 +201,10 @@ public Content invalidTagOutput(String summary, Optional<String> detail) {`
`201`	`201`	`}`
`202`	`202`
`203`	`203`	`/**`
`204`		`- * Returns the main type element of the current page or null for pages that don't have one.`
`205`		`- *`
`206`		`- * @return the type element of the current page or null.`
	`204`	`+ * {@return the type element documented by the current {@code HtmlDocletWriter} (may be null)}`
`207`	`205`	`*/`
`208`		`- public TypeElement getCurrentPageElement() {`
`209`		`- return htmlWriter.getCurrentPageElement();`
	`206`	`+ public TypeElement getCurrentTypeElement() {`
	`207`	`+ return htmlWriter.getCurrentTypeElement();`
`210`	`208`	`}`
`211`	`209`
`212`	`210`	`/**`
`@@ -411,7 +409,7 @@ public String visitType(TypeElement e, Void p) {`
`411`	`409`	`public String visitExecutable(ExecutableElement e, Void p) {`
`412`	`410`	`return utils.getFullyQualifiedName(utils.getEnclosingTypeElement(e))`
`413`	`411`	`+ "." + utils.getSimpleName(e)`
`414`		`- + utils.flatSignature(e, htmlWriter.getCurrentPageElement());`
	`412`	`+ + utils.flatSignature(e, htmlWriter.getCurrentTypeElement());`
`415`	`413`	`}`
`416`	`414`
`417`	`415`	`@Override`
`@@ -476,11 +474,11 @@ private boolean isLongOrHasComma(Content c) {`
`476`	`474`	`// Test if element is the same as or belongs to the current page element`
`477`	`475`	`private boolean isDifferentTypeElement(Element element) {`
`478`	`476`	`if (element.getKind().isDeclaredType()) {`
`479`		`- return element != getCurrentPageElement();`
	`477`	`+ return element != getCurrentTypeElement();`
`480`	`478`	`} else if (element.getKind() == ElementKind.OTHER) {`
`481`	`479`	`return false;`
`482`	`480`	`} else {`
`483`		`- return utils.getEnclosingTypeElement(element) != getCurrentPageElement();`
	`481`	`+ return utils.getEnclosingTypeElement(element) != getCurrentTypeElement();`
`484`	`482`	`}`
`485`	`483`	`}`
`486`	`484`	`}`