8039410: [javadoc] fix class-use items to be deterministic and index ordering

Reviewed-by: jjg

langtools/src/share/classes/com/sun/tools/doclets/formats/html/ClassUseWriter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 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
@@ -180,7 +180,7 @@ public class ClassUseWriter extends SubWriterHolderWriter {
         Map<String,List<ProgramElementDoc>> map = new HashMap<>();
         List<? extends ProgramElementDoc> list= classMap.get(classdoc.qualifiedName());
         if (list != null) {
-            Collections.sort(list);
+            list.sort(Util.makeComparatorForClassUse());
             for (ProgramElementDoc doc : list) {
                 PackageDoc pkg = doc.containingPackage();
                 pkgSet.add(pkg);

langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/IndexBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 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
@@ -71,27 +71,6 @@ public class IndexBuilder {
     // make ProgramElementDoc[] when new toArray is available
     protected final Object[] elements;
 
-    /**
-     * A comparator used to sort classes and members.
-     * Note:  Maybe this compare code belongs in the tool?
-     */
-    private class DocComparator implements Comparator<Doc> {
-        public int compare(Doc d1, Doc d2) {
-            String doc1 = d1.name();
-            String doc2 = d2.name();
-            int compareResult;
-            if ((compareResult = doc1.compareToIgnoreCase(doc2)) != 0) {
-                return compareResult;
-            } else if (d1 instanceof ProgramElementDoc && d2 instanceof ProgramElementDoc) {
-                 doc1 = (((ProgramElementDoc) d1).qualifiedName());
-                 doc2 = (((ProgramElementDoc) d2).qualifiedName());
-                 return doc1.compareToIgnoreCase(doc2);
-            } else {
-                return 0;
-            }
-        }
-    }
-
     /**
      * Constructor. Build the index map.
      *
@@ -133,7 +112,7 @@ public class IndexBuilder {
      */
     protected void sortIndexMap() {
         for (List<Doc> docs : indexmap.values()) {
-            Collections.sort(docs, new DocComparator());
+            docs.sort(Util.makeComparatorForIndexUse());
         }
     }
 

langtools/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/Util.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 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
@@ -29,6 +29,7 @@ import java.io.*;
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Target;
+import java.text.Collator;
 import java.util.*;
 import javax.tools.StandardLocation;
 
@@ -49,7 +50,6 @@ import com.sun.tools.javac.util.StringUtils;
  * @author Jamie Ho
  */
 public class Util {
-
     /**
      * Return array of class members whose documentation is to be generated.
      * If the member is deprecated do not include such a member in the
@@ -781,4 +781,163 @@ public class Util {
                 elt.name().contentEquals(ElementType.PARAMETER.name()) ||
                 elt.name().contentEquals(ElementType.TYPE.name());
     }
+
+    /**
+     * A general purpose String comparator, which compares two Strings using a Collator
+     * strength of "SECONDARY", thus providing  optimum case insensitive comparisons in
+     * most Locales.
+     *
+     * @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 compareStrings(String s1, String s2) {
+        Collator collator = Collator.getInstance();
+        collator.setStrength(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.
+     * @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.
+             *
+             * @param d1 - a Doc element.
+             * @param d2 - a Doc element.
+             * @return a negative integer, zero, or a positive integer as the first
+             *         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());
+                if (result != 0) {
+                    return result;
+                }
+                if (d1 instanceof ExecutableMemberDoc && d2 instanceof ExecutableMemberDoc) {
+                    result = compareExecutableMembers(
+                            (ExecutableMemberDoc) d1,
+                            (ExecutableMemberDoc) d2);
+                    if (result != 0) {
+                        return result;
+                    }
+                }
+                if (d1 instanceof ProgramElementDoc && d2 instanceof ProgramElementDoc) {
+                    return compareProgramElementDoc((ProgramElementDoc)d1, (ProgramElementDoc)d2);
+                }
+                return 0;
+            }
+        };
+    }
+
+    /**
+     * Comparator for ClassUse representations, this sorts on member names,
+     * fully qualified member names and then the parameter types if applicable.
+     * @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.
+             * @param d1 - a Doc element.
+             * @param d2 - a Doc element.
+             * @return a negative integer, zero, or a positive integer as the first
+             *         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());
+                if (result != 0) {
+                    return result;
+                }
+                if (d1 instanceof ProgramElementDoc && d2 instanceof ProgramElementDoc) {
+                    result = compareProgramElementDoc((ProgramElementDoc) d1, (ProgramElementDoc) d2);
+                    if (result != 0) {
+                        return result;
+                    }
+                }
+                if (d1 instanceof ExecutableMemberDoc && d2 instanceof ExecutableMemberDoc) {
+                    return compareExecutableMembers((ExecutableMemberDoc)d1, (ExecutableMemberDoc)d2);
+                }
+                return 0;
+            }
+        };
+    }
+
+    /**
+     * 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> {
+        /**
+         * compares two parameter arrays by first comparing the length of the arrays, and
+         * then each Type of the parameter in the array.
+         * @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;
+            }
+            int result = Integer.compare(params1.length, params2.length);
+            if (result != 0) {
+                return result;
+            }
+            for (int i = 0; i < params1.length; i++) {
+                result = compareStrings(params1[i].typeName(), params2[i].typeName());
+                if (result != 0) {
+                    return result;
+                }
+            }
+            return 0;
+        }
+
+        /**
+         * Compares two MemberDocs, typically the name of a method,
+         * field or constructor.
+         * @param e1 the first MemberDoc.
+         * @param e2 the second MemberDoc.
+         * @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;
+        }
+
+        /**
+         * Compares the fully qualified names of the entities
+         * @param p1 the first ProgramElementDoc.
+         * @param p2 the first ProgramElementDoc.
+         * @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());
+        }
+    }
 }

langtools/test/com/sun/javadoc/testOrdering/C.java

@@ -0,0 +1,74 @@
+/*
+ * 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.
+ */
+
+/**
+ * Class in an unnamed package.
+ */
+
+public class C {
+    /**
+     * A ctor
+     * @param c a param
+     */
+    public C(UsedInC c){}
+
+    /**
+     * another ctor
+     * @param c  a param
+     * @param s  a param
+     */
+    public C(UsedInC c, String s) {}
+
+    /**
+     * yet another ctor
+     * @param c  a param
+     * @param i  a param
+     */
+    public C(UsedInC c, int i) {}
+
+    /**
+     * Field in C.
+     */
+    public UsedInC fieldInC;
+
+    /**
+     * Method in C.
+     * @param p  a param
+     * @return UsedInC
+     */
+    public UsedInC methodInC(UsedInC p) { return p;}
+
+    /**
+     * A static method
+     * @param s  a param
+     * @return UsedInC
+     */
+    public static UsedInC ymethod(String s) {return null;}
+
+    /**
+     * Another static method variant
+     * @param value  a param
+     * @return UsedInC
+     */
+    public static UsedInC ymethod(int value) {return -1;}
+}

langtools/test/com/sun/javadoc/testOrdering/TestOrdering.java

@@ -0,0 +1,135 @@
+/*
+ * 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.
+ */
+
+/*
+ * @test
+ * @bug 8039410
+ * @summary test to determine if members are ordered correctly
+ * @author ksrini
+ * @library ../lib/
+ * @build JavadocTester
+ * @build TestOrdering
+ * @run main TestOrdering
+ */
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+public class TestOrdering extends JavadocTester {
+    /**
+     * The entry point of the test.
+     * @param args the array of command line arguments.
+     */
+    public static void main(String[] args) throws Exception {
+        TestOrdering tester = new TestOrdering();
+        // test unnamed packages
+        String[] ARGS = {
+            "-d", OUTPUT_DIR, "-sourcepath", SRC_DIR, "-use",
+             SRC_DIR + "/C.java", SRC_DIR + "/UsedInC.java"
+        };
+        tester.runJavadoc(ARGS);
+        checkExecutableMemberOrdering(tester.readFileToString("class-use/UsedInC.html"));
+
+        // next test using packages
+        String[] ARGS1 = {
+            "-d", OUTPUT_DIR + "-1", "-sourcepath", SRC_DIR, "-use",
+            "pkg1"
+        };
+        tester.runJavadoc(ARGS1);
+        checkClassUseOrdering(tester.readFileToString("pkg1/class-use/UsedClass.html"));
+        checkIndexPathOrdering(tester.readFileToString("index-all.html"));
+    }
+
+    static void checkExecutableMemberOrdering(String usePage) {
+        // check constructors
+        int idx1 = usePage.indexOf("C.html#C-UsedInC");
+        int idx2 = usePage.indexOf("C.html#C-UsedInC-int");
+        int idx3 = usePage.indexOf("C.html#C-UsedInC-java.lang.String");
+        if (idx1 == -1 || idx2 == -1 || idx3 == -1) {
+            throw new Error("ctor strings not found");
+        }
+        if (idx1 > idx2 || idx2 > idx3 || idx1 > idx3) {
+            throw new Error("ctor strings are out of order");
+        }
+
+        // check methods
+        idx1 = usePage.indexOf("C.html#ymethod-int");
+        idx2 = usePage.indexOf("C.html#ymethod-java.lang.String");
+        if (idx1 == -1 || idx2 == -1) {
+            throw new Error("#ymethod strings not found");
+        }
+        if (idx1 > idx2) {
+            throw new Error("#ymethod strings are out of order");
+        }
+        System.out.println("Executable Member Ordering: OK");
+    }
+
+    static void checkClassUseOrdering(String usePage) {
+        checkClassUseOrdering(usePage, "pkg1/C#ITERATION#.html#zfield");
+        checkClassUseOrdering(usePage, "pkg1/C#ITERATION#.html#fieldInC#ITERATION#");
+        checkClassUseOrdering(usePage, "pkg1/C#ITERATION#.html#zmethod-pkg1.UsedClass");
+        checkClassUseOrdering(usePage, "pkg1/C#ITERATION#.html#methodInC#ITERATION#");
+    }
+
+    static void checkClassUseOrdering(String usePage, String searchString) {
+        int lastidx = 0;
+        System.out.println("testing for " + searchString);
+        for (int i = 1; i < 5; i++) {
+            String s = searchString.replaceAll("#ITERATION#", Integer.toString(i));
+            System.out.println(s);
+            int idx = usePage.indexOf(s);
+            if (idx < lastidx) {
+                throw new Error(s + ", member ordering error, last:" + lastidx + ", got:" + idx);
+            }
+            System.out.println("\tlast: " + lastidx + " got:" + idx);
+            lastidx = idx;
+        }
+    }
+
+    static void checkIndexPathOrdering(String indexPage) {
+        String[] OrderedExpectedStrings = {
+            "pkg1/UsedClass.html#add-java.lang.Double",
+            "pkg1/ZZTop.html#add-double",
+            "pkg1/ZZTop.html#add-java.lang.Double",
+            "pkg1/UsedClass.html#add-float",
+            "pkg1/ZZTop.html#add-float",
+            "pkg1/UsedClass.html#add-int",
+            "pkg1/ZZTop.html#add-int",
+            "pkg1/UsedClass.html#add-java.lang.Integer",
+            "pkg1/ZZTop.html#add-java.lang.Integer",
+            "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"
+        };
+        int lastidx = 0;
+        for (String x : OrderedExpectedStrings) {
+            int idx = indexPage.indexOf(x);
+            if (idx < lastidx) {
+                throw new Error(x + ", index is out of order, last:" + lastidx + ", got:" + idx);
+            }
+            System.out.println(x + ": OK");
+            lastidx = idx;
+        }
+    }
+}

langtools/test/com/sun/javadoc/testOrdering/UsedInC.java

@@ -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.
+ */
+
+/**
+ * An empty class
+ */
+public class UsedInC {}

langtools/test/com/sun/javadoc/testOrdering/pkg1/C1.java

@@ -0,0 +1,55 @@
+/*
+ * 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;
+
+/**
+ * C1
+ */
+
+public class C1 {
+
+    /**
+     * Field in C1.
+     */
+    public UsedClass fieldInC1;
+
+    /**
+     * A duplicated field
+     */
+    public UsedClass zfield;
+
+    /**
+     * Method in C1.
+     * @param p a param
+     * @return UsedClass
+     */
+    public UsedClass methodInC1(UsedClass p) {return p;}
+
+    /**
+     * A duplicated method to test ordering
+     * @param p a param
+     * @return UsedClass
+     */
+    public UsedClass zmethod(UsedClass p) {return p;}
+}

langtools/test/com/sun/javadoc/testOrdering/pkg1/C2.java

@@ -0,0 +1,69 @@
+/*
+ * 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;
+
+public class C2 {
+
+    /**
+     * Field in C2.
+     */
+    public UsedClass fieldInC2;
+
+    /**
+     * another field
+     */
+    public C1 field = null;
+
+    /**
+     * A duplicated field
+     */
+    public UsedClass zfield;
+
+    /**
+     * Method in C2.
+     * @return C1
+     */
+    public C1 methodInC2() {return null;}
+
+    /**
+     * @param c1 a param
+     */
+    public void method(pkg1.C1 c1) {}
+
+    /**
+     * Method in C2.
+     * @param p a param
+     * @return UsedClass
+     */
+    public UsedClass methodInC2(UsedClass p) {return p;}
+
+    /**
+     * A duplicated method to test ordering
+     * @param p a param
+     * @return UsedClass
+     */
+    public UsedClass zmethod(UsedClass p) {
+        return p;
+    }
+}

langtools/test/com/sun/javadoc/testOrdering/pkg1/C3.java

@@ -0,0 +1,50 @@
+/*
+ * 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;
+
+public class C3 {
+    /**
+     * Field in C3.
+     */
+    public UsedClass fieldInC3;
+
+    /**
+     * A duplicated field
+     */
+    public UsedClass zfield;
+
+    /**
+     * Method in C3.
+     * @param p a param
+     * @return UsedClass
+     */
+    public UsedClass methodInC3(UsedClass p) {return p;}
+
+    /**
+     * A duplicated method to test ordering
+     * @param p a param
+     * @return UsedClass
+     */
+    public UsedClass zmethod(UsedClass p) {return p;}
+}

langtools/test/com/sun/javadoc/testOrdering/pkg1/C4.java

@@ -0,0 +1,50 @@
+/*
+ * 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;
+
+public class C4 {
+    /**
+     * Field in C4.
+     */
+    public UsedClass fieldInC4;
+
+    /**
+     * A duplicated field
+     */
+    public UsedClass zfield;
+
+    /**
+     * Method in C4.
+     * @param p a param
+     * @return UsedClass
+     */
+    public UsedClass methodInC4(UsedClass p) {return p;}
+
+    /**
+     * A duplicated method to test ordering
+     * @param p a param
+     * @return UsedClass
+     */
+    public UsedClass zmethod(UsedClass p) {return p;}
+}

langtools/test/com/sun/javadoc/testOrdering/pkg1/UsedClass.java

@@ -0,0 +1,72 @@
+/*
+ * 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 and class-use testing
+ */
+public class UsedClass {
+    // This is the exact order we expect to see
+
+    /**
+     * @param i param
+     */
+    public void   add(int i){}
+
+    /**
+     * @param i param
+     * @return double
+     */
+    public int    add(Integer i) {return 0;}
+
+    /**
+     * @param d param
+     */
+    public void   add(double d){}
+
+    /**
+     * @param d param
+     * @return Double
+     */
+    public Double add(Double d) {return (double) 22/7;}
+
+    /**
+     * @param f param
+     * @return Float
+     */
+    public Float  add(float f) {return (float) 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;}
+}

langtools/test/com/sun/javadoc/testOrdering/pkg1/ZZTop.java

@@ -0,0 +1,71 @@
+/*
+ * 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 {
+    // This is the exact order we expect to see
+
+    /**
+     * @param i param
+     */
+    public void   add(int i){}
+
+    /**
+     * @param i param
+     * @return double
+     */
+    public int    add(Integer i) {return 0;}
+
+    /**
+     * @param d param
+     */
+    public void   add(double d){}
+
+    /**
+     * @param d param
+     * @return Double
+     */
+    public Double add(Double d) {return (double) 22/7;}
+
+    /**
+     * @param f param
+     * @return Float
+     */
+    public Float  add(float f) {return (float) 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;}
+}