8047162: [javadoc] index files are non deterministic
authorksrini
Fri, 27 Jun 2014 17:54:54 -0700
changeset 25300 3b8a5067fe29
parent 25299 b4a7dcd657f5
child 25301 e5da086c7d43
8047162: [javadoc] index files are non deterministic Reviewed-by: jjg
langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Util.java
langtools/test/com/sun/javadoc/testOrdering/TestOrdering.java
langtools/test/com/sun/javadoc/testOrdering/src-2/a/A.java
langtools/test/com/sun/javadoc/testOrdering/src-2/a/something.java
langtools/test/com/sun/javadoc/testOrdering/src-2/b/B.java
langtools/test/com/sun/javadoc/testOrdering/src-2/b/something.java
langtools/test/com/sun/javadoc/testOrdering/src-2/e/something.java
langtools/test/com/sun/javadoc/testOrdering/src-2/something/J.java
langtools/test/com/sun/javadoc/testOrdering/src-2/something/package-info.java
langtools/test/com/sun/javadoc/testOrdering/src-2/something/something.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<Doc> makeComparatorForIndexUse() {
         return new Util.DocComparator<Doc>() {
             /**
-             * 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<Doc> makeComparatorForClassUse() {
         return new Util.DocComparator<Doc>() {
             /**
-             * 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 <T> a Doc entity
      */
     static abstract class DocComparator<T extends Doc> implements Comparator<Doc> {
-        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,
--- 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</a> - package something</dt>",
+        "something</span></a> - Class in",
+        "something</span></a> - Enum in",
+        "something</span></a> - Interface in",
+        "something</span></a> - Annotation Type in",
+        "something</a></span> - Variable in class",
+        "something()</a></span> - Constructor",
+        "something()</a></span> - Method in class a.<a href=\"a/A.html\"",
+        "something()</a></span> - Method in class a.<a href=\"a/something.html\"",
+        "something()</a></span> - Method in class something.<a href=\"something/J.html\""
+    };
     String[] composeTestVectors() {
         List<String> testList = new ArrayList<>();
 
--- /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() {}
+}
--- /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() {}
+}
--- /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;
+}
--- /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{}
--- /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 {}
--- /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(){}
+}
--- /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;
--- /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 {}