minor Javadoc and userguide updates

changelog.md

@@ -9,6 +9,7 @@
 > * [Traverser](userguide.md#traverser) updated to support passing all fields to visitor, uses lambda for visitor.
 > * Should be API compatible with 2.x.x versions.
 > * Complete Javadoc upgrade throughout the project.
+> * New [User Guide](userguide.md#compactset) added.
 #### 2.18.0
 > * Fix issue with field access `ClassUtilities.getClassLoader()` when in OSGi environment.  Thank you @ozhelezniak-talend.
 > * Added `ClassUtilities.getClassLoader(Class<?> c)` so that class loading was not confined to java-util classloader bundle. Thank you @ozhelezniak-talend.

src/main/java/com/cedarsoftware/util/DeepEquals.java

@@ -67,7 +67,15 @@
  * <p>The options {@code Map} acts as both input and output. When objects differ, the difference
  * description is placed in the options {@code Map} under the "diff" key
  * (see {@link DeepEquals#deepEquals(Object, Object, Map) deepEquals}).</p>
- *
+ * <p><strong>"diff" output notes:</strong></p>
+ * <ul>
+ *  <li>Empty lists, maps, and arrays are shown with (∅) or [∅]</li>
+ *  <li>A Map of size 1 is shown as Map(0..0), an int[] of size 2 is shown as int[0..1], an empty list is List(∅)</li>
+ *  <li>Sub-object fields on non-difference path shown as {..}</li>
+ *  <li>Map entry shown with 《key ⇨ value》 and may be nested</li>
+ *  <li>General pattern is [difference type] ▶ root context ▶ shorthand path starting at a root context element (Object field, array/collection element, Map key-value)</li>
+ *  <li>If the root is not a container (Collection, Map, Array, or Object), no shorthand description is displayed</li>
+ *  </ul>
  * <p><strong>Example usage:</strong></p>
  * <pre><code>
  * Map&lt;String, Object&gt; options = new HashMap&lt;&gt;();
@@ -77,7 +85,23 @@
  * if (!DeepEquals.deepEquals(obj1, obj2, options)) {
  *     String diff = (String) options.get(DeepEquals.DIFF);  // Get difference description
  *     // Handle or log 'diff'
- * }
+ *
+ * Example output:
+ * // Simple object difference
+ * [field value mismatch] ▶ Person {name: "Jim Bob", age: 27} ▶ .age
+ *   Expected: 27
+ *   Found: 34
+ *   
+ * // Array element mismatch within an object that has an array
+ * [array element mismatch] ▶ Person {id: 173679590720000287, first: "John", last: "Smith", favoritePet: {..}, pets: Pet[0..1]} ▶ .pets[0].nickNames[0]
+ *   Expected: "Edward"
+ *   Found: "Eddie"
+ *
+ * // Map with a different value associated to a key (Map size = 1 noted as 0..0)
+ * [map value mismatch] ▶ LinkedHashMap(0..0) ▶ 《"key" ⇨ "value1"》
+ *   Expected: "value1"
+ *   Found: "value2"
+ *   
  * </code></pre>
  *
  * @see #deepEquals(Object, Object)

src/main/java/com/cedarsoftware/util/ReflectionUtils.java

@@ -831,7 +831,7 @@ public static Map<String, Field> getAllDeclaredFieldsMap(Class<?> c) {
     }
 
     /**
-     * @deprecated As of 2.0.19, replaced by {@link #getAllDeclaredFields(Class)}.
+     * @deprecated As of 3.0.0, replaced by {@link #getAllDeclaredFields(Class)}.
      * Note that getAllDeclaredFields() includes transient fields and synthetic fields
      * (like "this$"). If you need the old behavior, filter the additional fields:
      * <pre>{@code
@@ -842,7 +842,7 @@ public static Map<String, Field> getAllDeclaredFieldsMap(Class<?> c) {
      *     !field.isSynthetic()
      * );
      * }</pre>
-     * This method will may be removed in 3.0.0.
+     * This method may be removed in 3.0.0.
      */
     @Deprecated
     public static Collection<Field> getDeepDeclaredFields(Class<?> c) {
@@ -859,7 +859,7 @@ public static Collection<Field> getDeepDeclaredFields(Class<?> c) {
     }
 
     /**
-     * @deprecated As of 2.0.19, replaced by {@link #getAllDeclaredFieldsMap(Class)}.
+     * @deprecated As of 3.0.0, replaced by {@link #getAllDeclaredFieldsMap(Class)}.
      * Note that getAllDeclaredFieldsMap() includes transient fields and synthetic fields
      * (like "this$"). If you need the old behavior, filter the additional fields:
      * <pre>{@code
@@ -870,7 +870,7 @@ public static Collection<Field> getDeepDeclaredFields(Class<?> c) {
      *     !field.isSynthetic()
      * );
      * }</pre>
-     * This method will may be removed in 3.0.0.
+     * This method may be removed in 3.0.0.
      */
     @Deprecated
     public static Map<String, Field> getDeepDeclaredFieldMap(Class<?> c) {
@@ -886,7 +886,7 @@ public static Map<String, Field> getDeepDeclaredFieldMap(Class<?> c) {
     }
 
     /**
-     * @deprecated As of 2.0.19, replaced by {@link #getAllDeclaredFields(Class)}.
+     * @deprecated As of 3.0.0, replaced by {@link #getAllDeclaredFields(Class)}.
      * Note that getAllDeclaredFields() includes transient fields and synthetic fields
      * (like "this$"). If you need the old behavior, filter the additional fields:
      * <pre>{@code