Move method comments so JavaDoc will pick them up.

Util.java

@@ -6,12 +6,16 @@ import java.util.*;
 
 import org.json.*;
 
+/**
+ * These are helpful utility methods that perform basic comparisons
+ * between various objects. In most cases, the comparisons are not
+ * order-dependent, or else the order is known.
+ */
 public class Util {
 
-    
-    
     /**
-     * Compares two json arrays for equality
+     * Compares two JSONArrays for equality.
+     * The arrays need not be in the same order.
      * @param jsonArray created by the code to be tested
      * @param expectedJsonArray created specifically for comparing
      */
@@ -27,7 +31,8 @@ public class Util {
     }
 
     /**
-     * Compares two json objects for equality
+     * Compares two JSONObjects for equality. The objects need not be
+     * in the same order 
      * @param jsonObject created by the code to be tested
      * @param expectedJsonObject created specifically for comparing
      */
@@ -68,6 +73,8 @@ public class Util {
              * Certain helper classes (e.g. XML) may create Long instead of
              * Integer for small int values. As long as both are Numbers,
              * just compare the toString() values.
+             * TODO: this may not work in the case where the underlying types
+             * do not have the same precision.
              */
             if (!(value instanceof Number && expectedValue instanceof Number)) {
                 assertTrue("object types should be equal for actual: "+
@@ -78,12 +85,31 @@ public class Util {
                     value.getClass().toString().equals(
                             expectedValue.getClass().toString()));
             }
+            /**
+             * When in doubt, compare by string
+             * TODO: should not this be an else to the previous condition?
+             */
             assertTrue("string values should be equal for actual: "+
                 value.toString()+" expected: "+expectedValue.toString(),
                 value.toString().equals(expectedValue.toString()));
         }
     }
 
+    /**
+     * Sometimes test completion requires comparison of JSONArray objects that
+     * were produced from a JSONObject, and so unordered. This method is 
+     * imperfect since it only compares the array elements and won't catch
+     * JSON syntax errors but at least it does not rely on ordering
+     * <p>
+     * It is expected that the arrays to be compared come from JSONArray
+     * instances which have been rendered by toString(), and whose syntax
+     * chars have been removed.
+     * <p>
+     * TODO: why are we not simply comparing the JSONArrays?
+     * <p>
+     * @param names an array of strings for comparison
+     * @param expectedNames the other array of strings for comparison
+     */
     public static void compareActualVsExpectedStringArrays(String[] names,
             String [] expectedNames) {
         assertTrue("Array lengths should be equal",
@@ -97,6 +123,13 @@ public class Util {
         }
     }
 
+    /**
+     * This is stopgap test utility. It is meant to compare strings
+     * of XML, but it does not take ordering into account and should
+     * not be expected to work correctly with complex XML.
+     * @param aXmlStr an XML doc to be compared
+     * @param bXmlStr the other XML doc to be compared
+     */
     public static void compareXML(String aXmlStr, String bXmlStr) {
         // TODO For simple tests this may be adequate, but it won't work for
         // elements with multiple attributes and possibly other cases as well.