# HG changeset patch # User ksrini # Date 1403916894 25200 # Node ID 3b8a5067fe295e498fd17b45256a1efa1082a02f # Parent b4a7dcd657f5eb3febb68e920ba963105e5ebad5 8047162: [javadoc] index files are non deterministic Reviewed-by: jjg diff -r b4a7dcd657f5 -r 3b8a5067fe29 langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Util.java --- a/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Util.java Tue Jun 17 14:01:27 2014 +0200 +++ b/langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Util.java Fri Jun 27 17:54:54 2014 -0700 @@ -812,21 +812,24 @@ collator.setStrength(caseSensitive ? Collator.TERTIARY : Collator.SECONDARY); return collator.compare(s1, s2); } + /** - * A comparator for index file uses, + * A comparator for index file presentations, * 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. + * 2. if equal, then compare the DocKind ex: Package, Interface etc. + * 3a. if equal and if the type is of ExecutableMemberDoc(Constructor, Fields), + * a case insensitive comparison of parameter types + * 3b. if equal, a case sensitive comparison of parameter types + * 4. finally, if equal, compare the FQNs of the entities * @return a comparator for index file use */ public static Comparator makeComparatorForIndexUse() { return new Util.DocComparator() { /** - * compare two given Doc entities, first sort on name, if - * applicable on the method's parameter types, and finally on the - * fully qualified name of the entity. + * Compare two given Doc entities, first sort on name, then on the kinds, + * then on the parameters only if the type is an instance of ExecutableMemberDocs, + * the parameters are compared ignoring the case first, then a case sensitive comparison, + * and finally the fully qualified names. * * @param d1 - a Doc element. * @param d2 - a Doc element. @@ -838,7 +841,11 @@ if (result != 0) { return result; } - if (d1 instanceof ExecutableMemberDoc && d2 instanceof ExecutableMemberDoc) { + result = compareDocKinds(d1, d2); + if (result != 0) { + return result; + } + if (hasParameters(d1)) { Parameter[] param1 = ((ExecutableMemberDoc) d1).parameters(); Parameter[] param2 = ((ExecutableMemberDoc) d2).parameters(); result = compareParameters(false, param1, param2); @@ -846,31 +853,28 @@ return result; } result = compareParameters(true, param1, param2); - } - if (result != 0) { - return result; + if (result != 0) { + return result; + } } - result = compareFullyQualifiedNames(d1, d2); - if (result != 0) { - return result; - } - return compareDocKinds(d1, d2); + return compareFullyQualifiedNames(d1, d2); } }; } - /** - * Comparator for ClassUse representations, this sorts on member names, - * fully qualified member names and then the parameter types if applicable, - * and finally the Doc kinds ie. package, class, interface etc. + * Comparator for ClassUse presentations, and sorts as follows: + * 1. member names + * 2. then fully qualified member names + * 3. then parameter types if applicable + * 4. finally the Doc kinds ie. package, class, interface etc. * @return a comparator to sort classes and members for class use */ public static Comparator makeComparatorForClassUse() { return new Util.DocComparator() { /** - * compare two given Doc entities, first sort on name, and if - * applicable on the fully qualified name, and finally if applicable - * on the parameter types. + * Compare two given Doc entities, first sort on name, and if + * applicable on the fully qualified name, and if applicable + * on the parameter types, and finally the DocKind. * @param d1 - a Doc element. * @param d2 - a Doc element. * @return a negative integer, zero, or a positive integer as the first @@ -885,7 +889,7 @@ if (result != 0) { return result; } - if (d1 instanceof ExecutableMemberDoc && d2 instanceof ExecutableMemberDoc) { + if (hasParameters(d1) && hasParameters(d2)) { Parameter[] param1 = ((ExecutableMemberDoc) d1).parameters(); Parameter[] param2 = ((ExecutableMemberDoc) d2).parameters(); result = compareParameters(false, param1, param2); @@ -898,53 +902,54 @@ } }; } - - /** * A general purpose comparator to sort Doc entities, basically provides the building blocks * for creating specific comparators for an use-case. * @param a Doc entity */ static abstract class DocComparator implements Comparator { - static enum DocKinds { + static enum DocKind { PACKAGE, - FIELD, + CLASS, ENUM, + INTERFACE, ANNOTATION, - INTERFACE, - CLASS, + FIELD, CONSTRUCTOR, METHOD }; - private DocKinds getValue(Doc d) { + boolean hasParameters(Doc d) { + return d instanceof ExecutableMemberDoc; + } + DocKind getDocKind(Doc d) { if (d.isAnnotationType() || d.isAnnotationTypeElement()) { - return DocKinds.ANNOTATION; + return DocKind.ANNOTATION; } else if (d.isEnum() || d.isEnumConstant()) { - return DocKinds.ENUM; + return DocKind.ENUM; } else if (d.isField()) { - return DocKinds.FIELD; + return DocKind.FIELD; } else if (d.isInterface()) { - return DocKinds.INTERFACE; + return DocKind.INTERFACE; } else if (d.isClass()) { - return DocKinds.CLASS; + return DocKind.CLASS; } else if (d.isConstructor()) { - return DocKinds.CONSTRUCTOR; + return DocKind.CONSTRUCTOR; } else if (d.isMethod()) { - return DocKinds.METHOD; + return DocKind.METHOD; } else { - return DocKinds.PACKAGE; + return DocKind.PACKAGE; } } /** * Compares two Doc entities' kinds, and these are ordered as defined in - * the DocKinds enumeration. + * the DocKind 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)); + return getDocKind(d1).compareTo(getDocKind(d2)); } /** * Compares two parameter arrays by comparing each Type of the parameter in the array, diff -r b4a7dcd657f5 -r 3b8a5067fe29 langtools/test/com/sun/javadoc/testOrdering/TestOrdering.java --- a/langtools/test/com/sun/javadoc/testOrdering/TestOrdering.java Tue Jun 17 14:01:27 2014 +0200 +++ b/langtools/test/com/sun/javadoc/testOrdering/TestOrdering.java Fri Jun 27 17:54:54 2014 -0700 @@ -117,6 +117,31 @@ checkExit(Exit.OK); checkOrder("index-all.html", composeTestVectors()); } + + @Test + void testIndexTypeClustering() { + javadoc("-d", "out-3", + "-sourcepath", testSrc("src-2"), + "-use", + "a", + "b", + "e", + "something"); + checkOrder("index-all.html", typeTestVectors); + checkExit(Exit.OK); + } + String[] typeTestVectors = { + "something - package something", + "something - Class in", + "something - Enum in", + "something - Interface in", + "something - Annotation Type in", + "something - Variable in class", + "something() - Constructor", + "something() - Method in class a. - Method in class a. - Method in class something. testList = new ArrayList<>(); diff -r b4a7dcd657f5 -r 3b8a5067fe29 langtools/test/com/sun/javadoc/testOrdering/src-2/a/A.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/test/com/sun/javadoc/testOrdering/src-2/a/A.java Fri Jun 27 17:54:54 2014 -0700 @@ -0,0 +1,32 @@ +/* + * 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 a; +/** + * A class + */ +public class A { + /** + * a method + */ + public void something() {} +} diff -r b4a7dcd657f5 -r 3b8a5067fe29 langtools/test/com/sun/javadoc/testOrdering/src-2/a/something.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/test/com/sun/javadoc/testOrdering/src-2/a/something.java Fri Jun 27 17:54:54 2014 -0700 @@ -0,0 +1,36 @@ +/* + * 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 a; +/** + * A class + */ +public class something { + /** + * A constructor + */ + public something() {} + /** + * a method + */ + public void something() {} +} diff -r b4a7dcd657f5 -r 3b8a5067fe29 langtools/test/com/sun/javadoc/testOrdering/src-2/b/B.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/test/com/sun/javadoc/testOrdering/src-2/b/B.java Fri Jun 27 17:54:54 2014 -0700 @@ -0,0 +1,32 @@ +/* + * 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 b; +/** + * Another class + */ +public class B { + /** + * a field + */ + public Object something; +} diff -r b4a7dcd657f5 -r 3b8a5067fe29 langtools/test/com/sun/javadoc/testOrdering/src-2/b/something.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/test/com/sun/javadoc/testOrdering/src-2/b/something.java Fri Jun 27 17:54:54 2014 -0700 @@ -0,0 +1,27 @@ +/* + * 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 b; +/** + * an annotation + */ +public @interface something{} diff -r b4a7dcd657f5 -r 3b8a5067fe29 langtools/test/com/sun/javadoc/testOrdering/src-2/e/something.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/test/com/sun/javadoc/testOrdering/src-2/e/something.java Fri Jun 27 17:54:54 2014 -0700 @@ -0,0 +1,27 @@ +/* + * 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 e; +/** + * An enum + */ +public enum something {} diff -r b4a7dcd657f5 -r 3b8a5067fe29 langtools/test/com/sun/javadoc/testOrdering/src-2/something/J.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/test/com/sun/javadoc/testOrdering/src-2/something/J.java Fri Jun 27 17:54:54 2014 -0700 @@ -0,0 +1,29 @@ +/* + * 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 something; +public class J { + /** + * a method + */ + public void something(){} +} diff -r b4a7dcd657f5 -r 3b8a5067fe29 langtools/test/com/sun/javadoc/testOrdering/src-2/something/package-info.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/test/com/sun/javadoc/testOrdering/src-2/something/package-info.java Fri Jun 27 17:54:54 2014 -0700 @@ -0,0 +1,26 @@ +/* + * 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. + */ +/** + * A package + */ +package something; diff -r b4a7dcd657f5 -r 3b8a5067fe29 langtools/test/com/sun/javadoc/testOrdering/src-2/something/something.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/test/com/sun/javadoc/testOrdering/src-2/something/something.java Fri Jun 27 17:54:54 2014 -0700 @@ -0,0 +1,27 @@ +/* + * 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 something; +/** + * An interface + */ +public interface something {}