Skip to content

Commit 844a95b

Browse files
jgneffPavel Rappo
jgneff
authored and
Pavel Rappo
committedSep 21, 2022
8292892: Javadoc index descriptions are not deterministic
Reviewed-by: jjg
1 parent 8d1dd6a commit 844a95b

File tree

6 files changed

+320
-2
lines changed

6 files changed

+320
-2
lines changed
 

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ private void addContainingInfo(IndexItem item, boolean addModuleInfo) {
131131
case FIELD:
132132
case ENUM_CONSTANT:
133133
TypeElement containingType = item.getContainingTypeElement();
134-
item.setContainingPackage(utils.getPackageName(utils.containingPackage(element)));
134+
item.setContainingPackage(utils.getPackageName(utils.containingPackage(containingType)));
135135
item.setContainingClass(utils.getSimpleName(containingType));
136136
if (configuration.showModules && addModuleInfo) {
137137
item.setContainingModule(utils.getFullyQualifiedName(utils.containingModule(element)));

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

+14-1
Original file line numberDiff line numberDiff line change
@@ -327,7 +327,20 @@ private Comparator<IndexItem> makeIndexComparator(boolean classesOnly) {
327327
return (ii1, ii2) -> {
328328
// If both are element items, compare the elements
329329
if (ii1.isElementItem() && ii2.isElementItem()) {
330-
return elementComparator.compare(ii1.getElement(), ii2.getElement());
330+
int d = elementComparator.compare(ii1.getElement(), ii2.getElement());
331+
if (d == 0) {
332+
/*
333+
* Members inherited from classes with package access are
334+
* documented as though they were declared in the inheriting
335+
* subclass (see JDK-4780441).
336+
*/
337+
Element subclass1 = ii1.getContainingTypeElement();
338+
Element subclass2 = ii2.getContainingTypeElement();
339+
if (subclass1 != null && subclass2 != null) {
340+
d = elementComparator.compare(subclass1, subclass2);
341+
}
342+
}
343+
return d;
331344
}
332345

333346
// If one is an element item, compare labels; if equal, put element item last

‎test/langtools/jdk/javadoc/doclet/testIndexInherited/TestIndexInherited.java

+167
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
/*
2+
* Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
3+
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* This code is free software; you can redistribute it and/or modify it
6+
* under the terms of the GNU General Public License version 2 only, as
7+
* published by the Free Software Foundation.
8+
*
9+
* This code is distributed in the hope that it will be useful, but WITHOUT
10+
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11+
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12+
* version 2 for more details (a copy is included in the LICENSE file that
13+
* accompanied this code).
14+
*
15+
* You should have received a copy of the GNU General Public License version
16+
* 2 along with this work; if not, write to the Free Software Foundation,
17+
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18+
*
19+
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20+
* or visit www.oracle.com if you need additional information or have any
21+
* questions.
22+
*/
23+
24+
/*
25+
* @test
26+
* @bug 8292892
27+
* @summary Tests that members inherited from classes with package access are
28+
* documented in the index as though they were declared in the
29+
* inheriting class.
30+
* @library ../../lib
31+
* @modules jdk.javadoc/jdk.javadoc.internal.tool
32+
* @build javadoc.tester.*
33+
* @run main TestIndexInherited
34+
*/
35+
import java.nio.file.Path;
36+
import javadoc.tester.JavadocTester;
37+
38+
/**
39+
* Tests the index for members inherited from a class with package access.
40+
*/
41+
public class TestIndexInherited extends JavadocTester {
42+
43+
/**
44+
* Name of the HTML index file.
45+
*/
46+
private static final String INDEX_FILE = "index-all.html";
47+
48+
/**
49+
* Name of the JavaScript member search index file.
50+
*/
51+
private static final String SEARCH_FILE = "member-search-index.js";
52+
53+
/**
54+
* Index entries for members inherited by the subclasses.
55+
*/
56+
private static final String[] INDEX_INHERITED = {"""
57+
<dt><a href="pkg1/ClassB.html#methodA()" class="member-name-link">methodA()</a> \
58+
- Method in class pkg1.<a href="pkg1/ClassB.html" title="class in pkg1">ClassB</a></dt>
59+
""", """
60+
<dt><a href="pkg2/ClassC.html#methodA()" class="member-name-link">methodA()</a> \
61+
- Method in class pkg2.<a href="pkg2/ClassC.html" title="class in pkg2">ClassC</a></dt>
62+
""", """
63+
<dt><a href="pkg1/ClassB.html#STRING_A" class="member-name-link">STRING_A</a> \
64+
- Static variable in class pkg1.<a href="pkg1/ClassB.html" title="class in pkg1">ClassB</a></dt>
65+
""", """
66+
<dt><a href="pkg2/ClassC.html#STRING_A" class="member-name-link">STRING_A</a> \
67+
- Static variable in class pkg2.<a href="pkg2/ClassC.html" title="class in pkg2">ClassC</a></dt>
68+
"""};
69+
70+
/**
71+
* Search entries for members inherited by the subclasses.
72+
*/
73+
private static final String[] SEARCH_INHERITED = {"""
74+
{"p":"pkg1","c":"ClassB","l":"methodA()"}""", """
75+
{"p":"pkg2","c":"ClassC","l":"methodA()"}""", """
76+
{"p":"pkg1","c":"ClassB","l":"STRING_A"}""", """
77+
{"p":"pkg2","c":"ClassC","l":"STRING_A"}"""};
78+
79+
/**
80+
* Index entries for members declared by the superclass.
81+
*/
82+
private static final String[] INDEX_DECLARED = {"""
83+
<dt><a href="pkg1/ClassA.html#methodA()" class="member-name-link">methodA()</a> \
84+
- Method in interface pkg1.<a href="pkg1/ClassA.html" title="interface in pkg1">ClassA</a></dt>
85+
""", """
86+
<dt><a href="pkg1/ClassA.html#STRING_A" class="member-name-link">STRING_A</a> \
87+
- Static variable in interface pkg1.<a href="pkg1/ClassA.html" title="interface in pkg1">ClassA</a></dt>
88+
"""};
89+
90+
/**
91+
* Search entries for members declared by the superclass.
92+
*/
93+
private static final String[] SEARCH_DECLARED = {"""
94+
{"p":"pkg1","c":"ClassA","l":"methodA()"}""", """
95+
{"p":"pkg1","c":"ClassA","l":"STRING_A"}"""};
96+
97+
/**
98+
* Sole constructor.
99+
*/
100+
public TestIndexInherited() {
101+
}
102+
103+
/**
104+
* Runs the test methods.
105+
*
106+
* @param args the command-line arguments
107+
* @throws Exception if an errors occurs while executing a test method
108+
*/
109+
public static void main(String... args) throws Exception {
110+
var tester = new TestIndexInherited();
111+
tester.runTests();
112+
}
113+
114+
/**
115+
* Checks that the index includes the inherited members of both public
116+
* subclasses, loaded in alphabetical order, and that there is absolutely no
117+
* mention of the non-public superclass.
118+
*
119+
* @param base the base directory for this method's output
120+
*/
121+
@Test
122+
public void testForInherited1(Path base) {
123+
String dir = base.resolve("out").toString();
124+
javadoc("-d", dir, "-sourcepath", testSrc, "pkg1", "pkg2");
125+
checkExit(Exit.OK);
126+
checkOrder(INDEX_FILE, INDEX_INHERITED);
127+
checkOrder(SEARCH_FILE, SEARCH_INHERITED);
128+
checkOutput(INDEX_FILE, false, "ClassA");
129+
checkOutput(SEARCH_FILE, false, "ClassA");
130+
}
131+
132+
/**
133+
* Checks that the index includes the inherited members of both public
134+
* subclasses, loaded in reverse alphabetical order, and that there is
135+
* absolutely no mention of the non-public superclass.
136+
*
137+
* @param base the base directory for this method's output
138+
*/
139+
@Test
140+
public void testForInherited2(Path base) {
141+
String dir = base.resolve("out").toString();
142+
javadoc("-d", dir, "-sourcepath", testSrc, "pkg2", "pkg1");
143+
checkExit(Exit.OK);
144+
checkOrder(INDEX_FILE, INDEX_INHERITED);
145+
checkOrder(SEARCH_FILE, SEARCH_INHERITED);
146+
checkOutput(INDEX_FILE, false, "ClassA");
147+
checkOutput(SEARCH_FILE, false, "ClassA");
148+
}
149+
150+
/**
151+
* Checks that the index includes the declared members of the non-public
152+
* superclass when the Javadoc <i>private</i> option is specified, and that
153+
* it no longer includes the inherited members of either public subclass.
154+
*
155+
* @param base the base directory for this method's output
156+
*/
157+
@Test
158+
public void testForDeclared(Path base) {
159+
String dir = base.resolve("out").toString();
160+
javadoc("-d", dir, "-sourcepath", testSrc, "-private", "pkg1", "pkg2");
161+
checkExit(Exit.OK);
162+
checkOrder(INDEX_FILE, INDEX_DECLARED);
163+
checkOrder(SEARCH_FILE, SEARCH_DECLARED);
164+
checkOutput(INDEX_FILE, false, INDEX_INHERITED);
165+
checkOutput(SEARCH_FILE, false, SEARCH_INHERITED);
166+
}
167+
}

‎test/langtools/jdk/javadoc/doclet/testIndexInherited/pkg1/ClassA.java

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
/*
2+
* Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
3+
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* This code is free software; you can redistribute it and/or modify it
6+
* under the terms of the GNU General Public License version 2 only, as
7+
* published by the Free Software Foundation.
8+
*
9+
* This code is distributed in the hope that it will be useful, but WITHOUT
10+
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11+
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12+
* version 2 for more details (a copy is included in the LICENSE file that
13+
* accompanied this code).
14+
*
15+
* You should have received a copy of the GNU General Public License version
16+
* 2 along with this work; if not, write to the Free Software Foundation,
17+
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18+
*
19+
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20+
* or visit www.oracle.com if you need additional information or have any
21+
* questions.
22+
*/
23+
package pkg1;
24+
25+
/**
26+
* A class with package access, inaccessible to classes outside its package.
27+
*/
28+
interface ClassA {
29+
30+
/**
31+
* A string constant with package access.
32+
*/
33+
static final String STRING_A = "A string in pkg1 with package access.";
34+
35+
/**
36+
* A method with package access.
37+
*/
38+
default void methodA() {
39+
System.out.println(ClassA.class.getName() + ": " + STRING_A);
40+
}
41+
}

‎test/langtools/jdk/javadoc/doclet/testIndexInherited/pkg1/ClassB.java

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
/*
2+
* Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
3+
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* This code is free software; you can redistribute it and/or modify it
6+
* under the terms of the GNU General Public License version 2 only, as
7+
* published by the Free Software Foundation.
8+
*
9+
* This code is distributed in the hope that it will be useful, but WITHOUT
10+
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11+
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12+
* version 2 for more details (a copy is included in the LICENSE file that
13+
* accompanied this code).
14+
*
15+
* You should have received a copy of the GNU General Public License version
16+
* 2 along with this work; if not, write to the Free Software Foundation,
17+
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18+
*
19+
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20+
* or visit www.oracle.com if you need additional information or have any
21+
* questions.
22+
*/
23+
package pkg1;
24+
25+
/**
26+
* A public subclass in the same package as its superclass.
27+
*/
28+
public class ClassB implements ClassA {
29+
30+
/**
31+
* The sole constructor.
32+
*/
33+
public ClassB() {
34+
}
35+
36+
/**
37+
* A public method.
38+
*/
39+
public void methodB() {
40+
System.out.println(ClassB.class.getName() + ": " + STRING_A);
41+
}
42+
}

‎test/langtools/jdk/javadoc/doclet/testIndexInherited/pkg2/ClassC.java

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
/*
2+
* Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
3+
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* This code is free software; you can redistribute it and/or modify it
6+
* under the terms of the GNU General Public License version 2 only, as
7+
* published by the Free Software Foundation.
8+
*
9+
* This code is distributed in the hope that it will be useful, but WITHOUT
10+
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11+
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12+
* version 2 for more details (a copy is included in the LICENSE file that
13+
* accompanied this code).
14+
*
15+
* You should have received a copy of the GNU General Public License version
16+
* 2 along with this work; if not, write to the Free Software Foundation,
17+
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18+
*
19+
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20+
* or visit www.oracle.com if you need additional information or have any
21+
* questions.
22+
*/
23+
package pkg2;
24+
25+
import pkg1.ClassB;
26+
27+
/**
28+
* A public subclass in a different package than its superclass.
29+
*/
30+
public class ClassC extends ClassB {
31+
32+
/**
33+
* The sole constructor.
34+
*/
35+
public ClassC() {
36+
}
37+
38+
/**
39+
* A public method.
40+
*/
41+
public void methodC() {
42+
methodA();
43+
methodB();
44+
System.out.println(ClassC.class.getName() + ": " + STRING_A);
45+
}
46+
47+
/**
48+
* The main method.
49+
*
50+
* @param args the command-line arguments
51+
*/
52+
public static void main(String[] args) {
53+
new ClassC().methodC();
54+
}
55+
}

0 commit comments

Comments
 (0)