langtools/javadoc: Random order in package-tree.html

[Jonathan Gibbons]

Emmanuel,

Thanks for this report.

As outlined in JEP 221 [1] we are currently working on rewriting
substantial parts of javadoc. The work is being done in the
javadoc.next project [2]. As part of this work, we have encountered
and fixed a number of issues such as you describe, and so it may
be the case that we have already fixed this one in JDK 9.

Comparing the source trees for JDK 8 and JDK 9, I see the following
changes in ClassTree.java:

JDK 8:
     private List<ClassDoc> baseEnums = new ArrayList<ClassDoc>();
     private Map<ClassDoc,List<ClassDoc>> subEnums = new 
HashMap<ClassDoc,List<ClassDoc>>();

JDK 9:
     final private SortedSet<ClassDoc> baseEnums;
     final private Map<ClassDoc, SortedSet<ClassDoc>> subEnums = new 
HashMap<>();

So it looks like the collections are now organized as sorted sets
instead of lists, so in JDK 9 at least, I believe we are OK.  In general,
the changes happening in 9 are too big to backport to 8u, which
leaves the question of whether we should patch a fix in the jdk8u
forest.  The concept of your patch looks reasonable, but since
it cannot be applied to 9, we cannot follow the usual practice of
"fix in 9, backport to 8u".  Also, although we have better testing
support in JDK 9 that was written to address problems like this,
that support is not available in JDK 8, making it harder (but not
impossible, of course) to write tests for any patch to 8u.

-- Jon

[1] http://openjdk.java.net/jeps/221
[2] http://openjdk.java.net/projects/javadoc-next/


On 05/19/2015 02:53 PM, Emmanuel Bourg wrote:
> Hi Jonathan,
>
> The Debian Reproducible Builds Team has noticed that the
> package-tree.html files generated by javadoc contains unsorted entries
> (see for example the diff from mockito [1] and easymock [2]). It seems
> to affect only the Enums and the annotations type.
>
> I investigated this a bit and I think it comes from the
> ClassTree.buildTree() method [3] where the interfaces and the classes
> are sorted, but not the enums nor the annotations types.
>
> I wanted to check with you if applying the same sort loop on
> enums/annotations would be appropriate, something like:
>
>      Collections.sort(baseEnums);
>      for (Iterator<List<ClassDoc>> it = subEnums.values().iterator();
> it.hasNext(); ) {
>          Collections.sort(it.next());
>      }
>
>      Collections.sort(baseAnnotationTypes);
>      for (Iterator<List<ClassDoc>> it =
> subAnnotationTypes.values().iterator(); it.hasNext(); ) {
>          Collections.sort(it.next());
>      }
>
> If it's ok I'll patch the openjdk package in Debian. Do you think this
> could also be fixed in OpenJDK upstream?
>
> Thank you,
>
> Emmanuel Bourg
>
> [1] https://reproducible.debian.net/rb-pkg/unstable/amd64/mockito.html
> [2] https://reproducible.debian.net/rb-pkg/unstable/amd64/easymock.html
> [3]
> http://hg.openjdk.java.net/jdk8u/jdk8u/langtools/file/ecb7e46b820f/src/share/classes/com/sun/tools/doclets/internal/toolkit/util/ClassTree.java#l116