7903830: apidiff: Review glyphs used to indicate same/difference

Reviewed-by: iris

Author: jonathan-gibbons

src/share/classes/jdk/codetools/apidiff/Main.java

@@ -170,6 +170,8 @@ private Result run(List<String> args, Log log) {
         Selector s = new Selector(options.includes, options.excludes);
         AccessKind ak = options.getAccessKind();
 
+        // TODO: when APIDiff moves to JDK 21, thia can trivially become SequencedSet,
+        //       which would be useful in varoius places, such as PageReporter.getResultGlyph
         Set<API> apis = options.allAPIOptions.values().stream()
                 .map(a -> API.of(a, s, ak, log))
                 .collect(Collectors.toCollection(LinkedHashSet::new));

src/share/classes/jdk/codetools/apidiff/html/Entity.java

@@ -45,10 +45,14 @@ public class Entity extends Content {
     public static final Entity CROSS = new Entity("cross", 0x2717);
     /** Unicode EQUALS SIGN. */
     public static final Entity EQUALS = new Entity("equals", 0x3d);
-    /** Unicode NOT EQUAL TO. */
-    public static final Entity NE = new Entity("ne", 0x2260);
+    /** Unicode MINUS. */
+    public static final Entity MINUS = new Entity("minus", 0x2212);
     /** Unicode NO-BREAK SPACE. */
     public static final Entity NBSP = new Entity("nbsp", 0xa0);
+    /** Unicode NOT EQUAL TO. */
+    public static final Entity NE = new Entity("ne", 0x2260);
+    /** Unicode PLUS. */
+    public static final Entity PLUS = new Entity("plus", 0x2b);
 
     private static final boolean useNumericEntities = Boolean.getBoolean("useNumericEntities");
 

src/share/classes/jdk/codetools/apidiff/report/html/PageReporter.java

@@ -36,6 +36,7 @@
 import java.util.Collections;
 import java.util.Comparator;
 import java.util.HashMap;
+import java.util.Iterator;
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
@@ -862,9 +863,35 @@ protected Content buildResultTable() {
         return section;
     }
 
-    private static final Content CHECK = HtmlTree.SPAN(Entity.CHECK).setClass("same");
-    private static final Content CROSS = HtmlTree.SPAN(Entity.CROSS).setClass("diff");
-    private static final Content SINGLE = HtmlTree.SPAN(Entity.CIRCLED_DIGIT_ONE).setClass("single");
+    // The following names are intended to be "semantic" or "abstract" names,
+    // distinct from the concrete representations used in the generated documentation.
+    // The names are intentionally different from any corresponding entity names.
+
+    /**
+     * Used when two elements compare as equal.
+     */
+    // possible alternatives: Entity.CHECK
+    private static final Content SAME = HtmlTree.SPAN(Entity.EQUALS).setClass("same");
+    /**
+     * Used when two elements compare as not equal.
+     */
+    // possible alternatives: Entity.CROSS
+    private static final Content DIFFERENT = HtmlTree.SPAN(Entity.NE).setClass("diff");
+    /**
+     * Used when an element does not appear in all instances of the APIs being compared.
+     * See also {@link #ADDED}, {@link #REMOVED}.
+     */
+    private static final Content PARTIAL = HtmlTree.SPAN(Entity.CIRCLED_DIGIT_ONE).setClass("partial");
+    /**
+     * Used in a 2-way comparison when it is determined that an element has been added.
+     */
+    // possible alternatives: '>' (for example, as used in text diff tools) or other right-pointing arrows
+    private static final Content ADDED = HtmlTree.SPAN(Entity.PLUS).setClass("partial");
+    /**
+     * Used in a 2-way comparison when it is determined that an element has been removed.
+     */
+    // possible alternatives: '<' (for example, as used in text diff tools) or other left-pointing arrows
+    private static final Content REMOVED = HtmlTree.SPAN(Entity.MINUS).setClass("partial");
 
 
     protected Content getResultGlyph(ElementKey eKey) {
@@ -882,19 +909,36 @@ protected Content getResultGlyph(Position pos, APIMap<?> map) {
             return Text.of("?");
         }
         if (map.size() == 1) {
-            return SINGLE;
+            API api = map.keySet().iterator().next();
+            Set<API> apis = parent.apis;
+            if (apis.size() == 2) {
+                // The following assumes an ordering on the order in which the
+                // APIs were defined on the command line: older first, newer second
+                Iterator<API> iter = apis.iterator();
+                API oldAPI = iter.next();
+                API newAPI = iter.next();
+                if (api == oldAPI) { // and not in new API
+                    return REMOVED;
+                } else if (api == newAPI) { // and not in old API
+                    return ADDED;
+                } else {
+                    // should not happen?
+                    return PARTIAL;
+                }
+            }
+            return PARTIAL;
         }
         Boolean eq = results.get(pos);
-        return (eq == null) ? SINGLE : eq ? CHECK : CROSS;
+        return (eq == null) ? PARTIAL : eq ? SAME : DIFFERENT;
     }
 
     // TODO: improve abstraction; these args are typically reversed
     protected Content getResultGlyph(APIMap<?> map, Position pos) {
         if (map.size() == 1) {
-            return SINGLE;
+            return PARTIAL;
         }
         Boolean eq = results.get(pos);
-        return (eq == null) ? SINGLE : eq ? CHECK : CROSS;
+        return (eq == null) ? PARTIAL : eq ? SAME : DIFFERENT;
     }
 
     protected APIMap<? extends Element> getElementMap(ElementKey eKey) {

src/share/classes/jdk/codetools/apidiff/report/html/resources/apidiff.css

@@ -179,7 +179,7 @@ div.signature {
 
 .doc-files span.diff,   .element span.diff,   .enclosed span.diff,   .serial-form span.diff,
 .doc-files span.same,   .element span.same,   .enclosed span.same,   .serial-form span.same,
-.doc-files span.single, .element span.single, .enclosed span.single, .serial-form span.single {
+.doc-files span.partial, .element span.partial, .enclosed span.partial, .serial-form span.partial {
     display: inline-block;
     width: 2em;
     margin-right: 0.5ex;
@@ -197,7 +197,7 @@ div.signature {
     color: #080;
 }
 
-.doc-files span.single, .element span.single, .enclosed span.single, .serial-form span.single {
+.doc-files span.partial, .element span.partial, .enclosed span.partial, .serial-form span.partial {
     background: #ddf;
     color: #008;
 }