The wrong data structure is being used to store the methods that use a given class.  We should be using HashSets, not ArrayLists.  That way, the methods are always sorted and we don't get this random ordering.  I will fix this within the next couple of days.
 xxxxx@xxxxx  2003-06-30

This bug fix is pending review and will be putback as soon as possible.

 xxxxx@xxxxx  2003-07-12

This bug has been fixed.
 xxxxx@xxxxx  2003-09-28The order of method descriptions can change from one javadoc run to the next
using the same version of javadoc, the same source files, and the same javadoc
call.  I used Java 2 SDK 1.4.2 build 26 for these tests.  Alan Sommerer 
has observed the same phenomenon in earlier versions.

I rely on the order being the same when running diffs between versions
for JCP reviews of the J2SE API spec.  

To re-state, I notice that when I run a full build of Java 2 SDK including 
docs, save those docs,then do another build, the method descriptions can
be in a different order.

For example,in the "Uses of java.awt.Color"page, here are two 
different orders of methods in the table.  Notice "getBorderColor()"
is the fourth method in the first list but the second method in the
second list.

-----------------------------------------------------
http://javapubs.sfbay/ws/mantis-docs-GA/build/solaris-sparc/doc/api/java/awt/class-use/Color.html

Methods in javax.swing.plaf.basic that return Color

  protected Color BasicTreeUI.getHashColor()

            Color BasicToolBarUI.getDockingColor()
            Gets the color displayed when over a docking area

            Color BasicToolBarUI.getFloatingColor()
            Gets the color displayed when over a floating area

            Color BasicToolBarUI.DragWindow.getBorderColor()

-----------------------------------------------------
http://swpubs.sfbay/javadoc/ws-mantis-promoted/doc/api/java/awt/class-use/Color.html

Methods in javax.swing.plaf.basic that return Color

  protected Color BasicTreeUI.getHashColor()

            Color BasicToolBarUI.DragWindow.getBorderColor()

            Color BasicToolBarUI.getDockingColor()
            Gets the color displayed when over a docking area

            Color BasicToolBarUI.getFloatingColor()
            Gets the color displayed when over a floating area
-----------------------------------------------------

The above is one example discovered by doing these diffs:

#!/bin/ksh -x
diff -r /java/re/jdk/1.4.2/promoted/rc/b26/doc/api /java/pubs/ws/mantis-docs-GA/build/solaris-sparc/doc/api > diff-keywords.log

The diffs from that file were distilled and then attached as 
diff-keywords-ESSENTIAL.log
I have deleted non-essential parts of the diffs from this file to show
only which files were being diffed and their differences.  In nearly all
cases, the only diffs are due to the order of members being different.

N/A

This is an easy fix.  Simply use HashSets to store the documented methods instead of ArrayLists.  I believe the main cause of this randomness is method RootDoc.classes().  That method seems to return the list of classes in random order.
 xxxxx@xxxxx  2003-06-30

This bug has been fixed.  I ended up using a TreeMap because methods can't be inserted into HashSets.  Javadoc incorrectly uses the name of the method as the comparable value.  This doesn't work because there are lots of overloaded methods that have equal names, but not equal signatures.  Instead, I store the members in a TreeMap with the signature as the key.  That way, the order of these methods in the class-use page is always the same, even though the order of classes returned by RootDoc.classes() is not always the same.  We should fix that because it is definitely unexpected behaviour.

This bug fix is pending review and will be putback as soon as possible.

 xxxxx@xxxxx  2003-07-12

This bug was fixed after refactoring.  It is no longer reproducible.  In the class use documentation, the members always appear in the same order that they appear int he source.