8042829: [javadoc] index-file output is not sorted correctly

8043062: JDK 9 platform and compiler upgrade failed on Solaris-sparcv9 with Javadoc.gmk:360: recipe for target docs/api/index.html

Reviewed-by: erikj, jjg
This commit is contained in:
Kumar Srinivasan 2014-05-22 12:16:53 -07:00
parent e380f5fa69
commit b18841ffa0
5 changed files with 332 additions and 247 deletions

View file

@ -31,6 +31,7 @@ import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
import java.text.Collator;
import java.util.*;
import javax.tools.StandardLocation;
import com.sun.javadoc.*;
@ -783,9 +784,8 @@ public class Util {
}
/**
* A general purpose String comparator, which compares two Strings using a Collator
* strength of "SECONDARY", thus providing optimum case insensitive comparisons in
* most Locales.
* A general purpose case insensitive String comparator, which compares two Strings using a Collator
* strength of "TERTIARY".
*
* @param s1 first String to compare.
* @param s2 second String to compare.
@ -793,14 +793,32 @@ public class Util {
* argument is less than, equal to, or greater than the second.
*/
public static int compareStrings(String s1, String s2) {
return compareStrings(true, s1, s2);
}
/**
* A general purpose case sensitive String comparator, which compares two Strings using a Collator
* strength of "SECONDARY".
*
* @param s1 first String to compare.
* @param s2 second String to compare.
* @return a negative integer, zero, or a positive integer as the first
* argument is less than, equal to, or greater than the second.
*/
public static int compareCaseCompare(String s1, String s2) {
return compareStrings(false, s1, s2);
}
private static int compareStrings(boolean caseSensitive, String s1, String s2) {
Collator collator = Collator.getInstance();
collator.setStrength(Collator.SECONDARY);
collator.setStrength(caseSensitive ? Collator.TERTIARY : Collator.SECONDARY);
return collator.compare(s1, s2);
}
/**
* A comparator for index file uses, this sorts first on names, then on
* parameter types and finally on the fully qualified name.
* A comparator for index file uses,
* 1. this sorts first on simple names
* 2. if equal, case insensitive comparison of Parameter types
* 3. if equal, case sensitive comparison of Parameter types
* 4. if equal, compare the FQNs of the entities
* 5. if equal, then compare the DocKinds ex: Package, Interface etc.
* @return a comparator for index file use
*/
public static Comparator<Doc> makeComparatorForIndexUse() {
@ -816,29 +834,35 @@ public class Util {
* argument is less than, equal to, or greater than the second.
*/
public int compare(Doc d1, Doc d2) {
int result = compareStrings(d1.name(), d2.name());
int result = compareNames(d1, d2);
if (result != 0) {
return result;
}
if (d1 instanceof ExecutableMemberDoc && d2 instanceof ExecutableMemberDoc) {
result = compareExecutableMembers(
(ExecutableMemberDoc) d1,
(ExecutableMemberDoc) d2);
Parameter[] param1 = ((ExecutableMemberDoc) d1).parameters();
Parameter[] param2 = ((ExecutableMemberDoc) d2).parameters();
result = compareParameters(false, param1, param2);
if (result != 0) {
return result;
}
result = compareParameters(true, param1, param2);
}
if (d1 instanceof ProgramElementDoc && d2 instanceof ProgramElementDoc) {
return compareProgramElementDoc((ProgramElementDoc)d1, (ProgramElementDoc)d2);
if (result != 0) {
return result;
}
return 0;
result = compareFullyQualifiedNames(d1, d2);
if (result != 0) {
return result;
}
return compareDocKinds(d1, d2);
}
};
}
/**
* Comparator for ClassUse representations, this sorts on member names,
* fully qualified member names and then the parameter types if applicable.
* fully qualified member names and then the parameter types if applicable,
* and finally the Doc kinds ie. package, class, interface etc.
* @return a comparator to sort classes and members for class use
*/
public static Comparator<Doc> makeComparatorForClassUse() {
@ -853,46 +877,88 @@ public class Util {
* argument is less than, equal to, or greater than the second.
*/
public int compare(Doc d1, Doc d2) {
int result = compareStrings(d1.name(), d2.name());
int result = compareNames(d1, d2);
if (result != 0) {
return result;
}
if (d1 instanceof ProgramElementDoc && d2 instanceof ProgramElementDoc) {
result = compareProgramElementDoc((ProgramElementDoc) d1, (ProgramElementDoc) d2);
result = compareFullyQualifiedNames(d1, d2);
if (result != 0) {
return result;
}
if (d1 instanceof ExecutableMemberDoc && d2 instanceof ExecutableMemberDoc) {
Parameter[] param1 = ((ExecutableMemberDoc) d1).parameters();
Parameter[] param2 = ((ExecutableMemberDoc) d2).parameters();
result = compareParameters(false, param1, param2);
if (result != 0) {
return result;
}
return compareParameters(true, param1, param2);
}
if (d1 instanceof ExecutableMemberDoc && d2 instanceof ExecutableMemberDoc) {
return compareExecutableMembers((ExecutableMemberDoc)d1, (ExecutableMemberDoc)d2);
}
return 0;
return compareDocKinds(d1, d2);
}
};
}
/**
* A general purpose comparator to sort Doc entities, basically provides the building blocks
* for creating specific comparators for an use-case.
* @param <T> a Doc entity
*/
static abstract class DocComparator<T extends Doc> implements Comparator<Doc> {
static enum DocKinds {
PACKAGE,
FIELD,
ENUM,
ANNOTATION,
INTERFACE,
CLASS,
CONSTRUCTOR,
METHOD
};
private DocKinds getValue(Doc d) {
if (d.isAnnotationType() || d.isAnnotationTypeElement()) {
return DocKinds.ANNOTATION;
} else if (d.isEnum() || d.isEnumConstant()) {
return DocKinds.ENUM;
} else if (d.isField()) {
return DocKinds.FIELD;
} else if (d.isInterface()) {
return DocKinds.INTERFACE;
} else if (d.isClass()) {
return DocKinds.CLASS;
} else if (d.isConstructor()) {
return DocKinds.CONSTRUCTOR;
} else if (d.isMethod()) {
return DocKinds.METHOD;
} else {
return DocKinds.PACKAGE;
}
}
/**
* compares two parameter arrays by comparing each Type of the parameter in the array,
* as possible, if the matched strings are identical, and have mismatched array lengths
* then compare the lengths.
* Compares two Doc entities' kinds, and these are ordered as defined in
* the DocKinds enumeration.
* @param d1 the first Doc object
* @param d2 the second Doc object
* @return a negative integer, zero, or a positive integer as the first
* argument is less than, equal to, or greater than the second.
*/
protected int compareDocKinds(Doc d1, Doc d2) {
return getValue(d1).compareTo(getValue(d2));
}
/**
* Compares two parameter arrays by comparing each Type of the parameter in the array,
* and as many as possible, otherwise compare their lengths.
* @param ignoreCase specifies case sensitive or insensitive comparison.
* @param params1 the first parameter array.
* @param params2 the first parameter array.
* @return a negative integer, zero, or a positive integer as the first
* argument is less than, equal to, or greater than the second.
*/
protected int compareParameters(Parameter[] params1, Parameter[] params2) {
if (params1.length == 0 && params2.length == 0) {
return 0;
}
protected int compareParameters(boolean ignoreCase, Parameter[] params1, Parameter[] params2) {
// try to compare as many as possible
for (int i = 0; i < params1.length && i < params2.length; i++) {
int result = compareStrings(params1[i].typeName(), params2[i].typeName());
int result = compareStrings(ignoreCase, params1[i].typeName(), params2[i].typeName());
if (result != 0) {
return result;
}
@ -901,41 +967,32 @@ public class Util {
}
/**
* Compares two MemberDocs, typically the name of a method,
* field or constructor.
* @param e1 the first MemberDoc.
* @param e2 the second MemberDoc.
* Compares two Doc entities typically the simple name of a method,
* field, constructor etc.
* @param d1 the first Doc.
* @param d2 the second Doc.
* @return a negative integer, zero, or a positive integer as the first
* argument is less than, equal to, or greater than the second.
*/
protected int compareMembers(MemberDoc e1, MemberDoc e2) {
return compareStrings(e1.name(), e2.name());
}
/**
* Compares two ExecutableMemberDocs such as methods and constructors,
* as well as the parameters the entity might take.
* @param m1 the first ExecutableMemberDoc.
* @param m2 the second ExecutableMemberDoc.
* @return a negative integer, zero, or a positive integer as the first
* argument is less than, equal to, or greater than the second.
*/
protected int compareExecutableMembers(ExecutableMemberDoc m1, ExecutableMemberDoc m2) {
int result = compareMembers(m1, m2);
if (result == 0)
result = compareParameters(m1.parameters(), m2.parameters());
return result;
protected int compareNames(Doc d1, Doc d2) {
return compareStrings(d1.name(), d2.name());
}
/**
* Compares the fully qualified names of the entities
* @param p1 the first ProgramElementDoc.
* @param p2 the first ProgramElementDoc.
* @param d1 the first entity
* @param d2 the second entity
* @return a negative integer, zero, or a positive integer as the first
* argument is less than, equal to, or greater than the second.
*/
protected int compareProgramElementDoc(ProgramElementDoc p1, ProgramElementDoc p2) {
return compareStrings(p1.qualifiedName(), p2.qualifiedName());
protected int compareFullyQualifiedNames(Doc d1, Doc d2) {
String name1 = (d1 instanceof ProgramElementDoc)
? ((ProgramElementDoc)d1).qualifiedName()
: d1.name();
String name2 = (d2 instanceof ProgramElementDoc)
? ((ProgramElementDoc)d2).qualifiedName()
: d2.name();
return compareStrings(name1, name2);
}
}
}

View file

@ -451,8 +451,12 @@ public abstract class JavadocTester {
for (String s : strings) {
int currentIndex = fileString.indexOf(s);
checking(s + " at index " + currentIndex);
if (currentIndex >= prevIndex) {
passed(s + "is in the correct order");
if (currentIndex == -1) {
failed(s + " not found.");
continue;
}
if (currentIndex > prevIndex) {
passed(s + " is in the correct order");
} else {
failed(s + " is in the wrong order.");
}

View file

@ -23,7 +23,7 @@
/*
* @test
* @bug 8039410 8042601
* @bug 8039410 8042601 8042829
* @summary test to determine if members are ordered correctly
* @author ksrini
* @library ../lib/
@ -31,6 +31,16 @@
* @run main TestOrdering
*/
import java.io.File;
import java.io.IOException;
import java.nio.file.Files;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import static java.nio.file.StandardOpenOption.*;
public class TestOrdering extends JavadocTester {
public static void main(String[] args) throws Exception {
@ -39,7 +49,7 @@ public class TestOrdering extends JavadocTester {
}
@Test
void testUnnamedPackages() {
void testUnnamedPackagesForClassUse() {
javadoc("-d", "out",
"-sourcepath", testSrc,
"-use",
@ -49,16 +59,94 @@ public class TestOrdering extends JavadocTester {
}
@Test
void testNamedPackages() {
void testNamedPackagesForClassUse() {
javadoc("-d", "out-1",
"-sourcepath", testSrc,
"-use",
"pkg1");
checkExit(Exit.OK);
checkClassUseOrdering("pkg1/class-use/UsedClass.html");
checkIndexPathOrdering("index-all.html");
}
enum ListOrder { NONE, REVERSE, SHUFFLE };
/*
* By default we do not shuffle the input list, in order to keep the list deterministic,
* and the test predictable. However, we can turn on the stress mode, by setting the following
* property if required.
*/
static final ListOrder STRESS_MODE = Boolean.getBoolean("TestOrder.STRESS")
? ListOrder.SHUFFLE
: ListOrder.REVERSE;
/*
* Controls the number of sibling packages, pkg0, pkg1, pkg2, .....
*/
static final int MAX_PACKAGES = 4;
/*
* Controls the number of children packages, pkg0, pkg0.pkg, pkg0.pkg.pkg, .....
* Note: having too long a depth (> 256 chars on Windows), will likely lead to
* cause problems with automated build and test systems.
*/
static final int MAX_SUBPACKAGES_DEPTH = 4;
@Test
void testIndexOrdering() throws IOException {
final String clsname = "Add";
List<String> cmdArgs = new ArrayList();
cmdArgs.add("-d");
cmdArgs.add("out-2");
cmdArgs.add("-sourcepath");
cmdArgs.add("src");
cmdArgs.add("-package");
System.out.println("STRESS_MODE: " + STRESS_MODE);
emitFile(null, clsname, STRESS_MODE);
for (int width = 0 ; width < MAX_PACKAGES ; width++) {
String wpkgname = "add" + width;
String dpkgname = wpkgname;
emitFile(wpkgname, clsname, ListOrder.NONE); // list as-is
cmdArgs.add(wpkgname);
for (int depth = 1 ; depth < MAX_SUBPACKAGES_DEPTH ; depth++) {
dpkgname = dpkgname + ".add";
emitFile(dpkgname, clsname, STRESS_MODE);
cmdArgs.add(dpkgname);
}
}
File srcDir = new File(new File("."), "src");
cmdArgs.add(new File(srcDir, clsname + ".java").getPath());
javadoc(cmdArgs.toArray(new String[cmdArgs.size()]));
checkExit(Exit.OK);
checkOrder("index-all.html", composeTestVectors());
}
String[] composeTestVectors() {
List<String> testList = new ArrayList<>();
for (String x : expectedMethodOrdering) {
testList.add(x);
for (int i = 0; i < MAX_PACKAGES; i++) {
String wpkg = "add" + i;
testList.add(wpkg + "/" + x);
String dpkg = wpkg;
for (int j = 1; j < MAX_SUBPACKAGES_DEPTH; j++) {
dpkg = dpkg + "/" + "add";
testList.add(dpkg + "/" + x);
}
}
}
for (String x : expectedEnumOrdering) {
testList.add(x.replace("REPLACE_ME", "&lt;Unnamed&gt;"));
for (int i = 0; i < MAX_PACKAGES; i++) {
String wpkg = "add" + i;
testList.add(wpkg + "/" + x.replace("REPLACE_ME", wpkg));
String dpkg = wpkg;
for (int j = 1; j < MAX_SUBPACKAGES_DEPTH; j++) {
dpkg = dpkg + "/" + "add";
testList.add(dpkg + "/" + x.replace("REPLACE_ME", pathToPackage(dpkg)));
}
}
}
testList.addAll(Arrays.asList(expectedFieldOrdering));
return testList.toArray(new String[testList.size()]);
}
void checkExecutableMemberOrdering(String usePage) {
String contents = readFile(usePage);
// check constructors
@ -109,29 +197,125 @@ public class TestOrdering extends JavadocTester {
}
}
void checkIndexPathOrdering(String indexPage) {
checkOrder(indexPage,
"pkg1/UsedClass.html#add--",
"pkg1/ZZTop.html#add--",
"pkg1/UsedClass.html#add-double-",
"pkg1/UsedClass.html#add-java.lang.Double-",
"pkg1/ZZTop.html#add-double-",
"pkg1/ZZTop.html#add-java.lang.Double-",
"pkg1/UsedClass.html#add-double-byte-",
"pkg1/ZZTop.html#add-double-byte-",
"pkg1/UsedClass.html#add-double-double-",
"pkg1/UsedClass.html#add-double-java.lang.Double-",
"pkg1/ZZTop.html#add-double-double-",
"pkg1/ZZTop.html#add-double-java.lang.Double-",
"pkg1/UsedClass.html#add-float-",
"pkg1/ZZTop.html#add-float-",
"pkg1/UsedClass.html#add-float-int-",
"pkg1/ZZTop.html#add-float-int-",
"pkg1/UsedClass.html#add-int-",
"pkg1/ZZTop.html#add-int-",
"pkg1/UsedClass.html#add-int-float-",
"pkg1/ZZTop.html#add-int-float-",
"pkg1/UsedClass.html#add-java.lang.Integer-",
"pkg1/ZZTop.html#add-java.lang.Integer-");
static String[] contents = {
"public add ADDADD;",
"public add AddAdd;",
"public add addadd;",
"public enum add {add, ADD, addd, ADDD};",
"public enum ADD {ADD, add, addd, ADDD};",
"public void add(){}",
"public void add(double d){}",
"public void add(int i, float f){}",
"public void add(float f, int i){}",
"public void add(double d, byte b){}",
"public Double add(Double d) {return (double) 22/7;}",
"public double add(double d1, double d2) {return d1 + d2;}",
"public double add(double d1, Double d2) {return d1 + d2;}",
"public Float add(float f) {return (float) 22/7;}",
"public void add(int i){}",
"public int add(Integer i) {return 0;}"
};
void emitFile(String pkgname, String clsname, ListOrder order) throws IOException {
File srcDir = new File("src");
File outDir = pkgname == null
? srcDir
: new File(srcDir, pkgname.replace(".", File.separator));
File outFile = new File(outDir, clsname + ".java");
outDir.mkdirs();
List<String> scratch = new ArrayList<>(Arrays.asList(contents));
switch (order) {
case SHUFFLE:
Collections.shuffle(scratch);
break;
case REVERSE:
Collections.reverse(scratch);
break;
default:
// leave list as-is
}
// insert the header
scratch.add(0, "public class " + clsname + " {");
if (pkgname != null) {
scratch.add(0, "package " + pkgname + ";");
}
// append the footer
scratch.add("}");
Files.write(outFile.toPath(), scratch, CREATE, TRUNCATE_EXISTING);
}
String pathToPackage(String in) {
return in.replace("/", ".");
}
final String expectedMethodOrdering[] = {
"Add.html#add--",
"Add.html#add-double-",
"Add.html#add-java.lang.Double-",
"Add.html#add-double-byte-",
"Add.html#add-double-double-",
"Add.html#add-double-java.lang.Double-",
"Add.html#add-float-",
"Add.html#add-float-int-",
"Add.html#add-int-",
"Add.html#add-int-float-",
"Add.html#add-java.lang.Integer-"
};
final String expectedEnumOrdering[] = {
"Add.add.html\" title=\"enum in REPLACE_ME\"",
"Add.ADD.html\" title=\"enum in REPLACE_ME\""
};
final String expectedFieldOrdering[] = {
"Add.html#addadd\"",
"add0/add/add/add/Add.html#addadd\"",
"add0/add/add/Add.html#addadd\"",
"add0/add/Add.html#addadd\"",
"add0/Add.html#addadd\"",
"add1/add/add/add/Add.html#addadd\"",
"add1/add/add/Add.html#addadd\"",
"add1/add/Add.html#addadd\"",
"add1/Add.html#addadd\"",
"add2/add/add/add/Add.html#addadd\"",
"add2/add/add/Add.html#addadd\"",
"add2/add/Add.html#addadd\"",
"add2/Add.html#addadd\"",
"add3/add/add/add/Add.html#addadd\"",
"add3/add/add/Add.html#addadd\"",
"add3/add/Add.html#addadd\"",
"add3/Add.html#addadd\"",
"Add.html#AddAdd\"",
"add0/add/add/add/Add.html#AddAdd\"",
"add0/add/add/Add.html#AddAdd\"",
"add0/add/Add.html#AddAdd\"",
"add0/Add.html#AddAdd\"",
"add1/add/add/add/Add.html#AddAdd\"",
"add1/add/add/Add.html#AddAdd\"",
"add1/add/Add.html#AddAdd\"",
"add1/Add.html#AddAdd\"",
"add2/add/add/add/Add.html#AddAdd\"",
"add2/add/add/Add.html#AddAdd\"",
"add2/add/Add.html#AddAdd\"",
"add2/Add.html#AddAdd\"",
"add3/add/add/add/Add.html#AddAdd\"",
"add3/add/add/Add.html#AddAdd\"",
"add3/add/Add.html#AddAdd\"",
"add3/Add.html#AddAdd\"",
"Add.html#ADDADD\"",
"add0/add/add/add/Add.html#ADDADD\"",
"add0/add/add/Add.html#ADDADD\"",
"add0/add/Add.html#ADDADD\"",
"add0/Add.html#ADDADD\"",
"add1/add/add/add/Add.html#ADDADD\"",
"add1/add/add/Add.html#ADDADD\"",
"add1/add/Add.html#ADDADD\"",
"add1/Add.html#ADDADD\"",
"add2/add/add/add/Add.html#ADDADD\"",
"add2/add/add/Add.html#ADDADD\"",
"add2/add/Add.html#ADDADD\"",
"add2/Add.html#ADDADD\"",
"add3/add/add/add/Add.html#ADDADD\"",
"add3/add/add/Add.html#ADDADD\"",
"add3/add/Add.html#ADDADD\"",
"add3/Add.html#ADDADD\""
};
}

View file

@ -23,72 +23,6 @@
package pkg1;
/**
* For index and class-use testing
* For class-use testing
*/
public class UsedClass {
/**
* just an empty param method.
*/
public void add(){}
/**
* @param d param
*/
public void add(double d){}
/**
* @param i param
* @param f param
*/
public void add(int i, float f){}
/**
* @param f param
* @param i param
*/
public void add(float f, int i){}
/**
* @param d param
* @param b param
*/
public void add(double d, byte b){}
/**
* @param d param
* @return Double
*/
public Double add(Double d) {return (double) 22/7;}
/**
* @param d1 param
* @param d2 param
* @return double
*/
public double add(double d1, double d2) {return d1 + d2;}
/**
* @param d1 param
* @param d2 param
* @return double
*/
public double add(double d1, Double d2) {return d1 + d2;}
/**
* @param f param
* @return Float
*/
public Float add(float f) {return (float) 22/7;}
/**
* @param i param
*/
public void add(int i){}
/**
* @param i param
* @return double
*/
public int add(Integer i) {return 0;}
}
public class UsedClass {}

View file

@ -1,94 +0,0 @@
/*
* Copyright (c) 2014, 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
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package pkg1;
/**
* For index testing only
*/
public class ZZTop {
/**
* just an empty param method.
*/
public void add(){}
/**
* @param d param
*/
public void add(double d){}
/**
* @param i param
* @param f param
*/
public void add(int i, float f){}
/**
* @param f param
* @param i param
*/
public void add(float f, int i){}
/**
* @param d param
* @param b param
*/
public void add(double d, byte b){}
/**
* @param d param
* @return Double
*/
public Double add(Double d) {return (double) 22/7;}
/**
* @param d1 param
* @param d2 param
* @return double
*/
public double add(double d1, double d2) {return d1 + d2;}
/**
* @param d1 param
* @param d2 param
* @return double
*/
public double add(double d1, Double d2) {return d1 + d2;}
/**
* @param f param
* @return Float
*/
public Float add(float f) {return (float) 22/7;}
/**
* @param i param
*/
public void add(int i){}
/**
* @param i param
* @return double
*/
public int add(Integer i) {return 0;}
}