[spec/expression] Improve EqualExpression docs for classes (#4218)

Fixes #4217.
Add summary with correct info for class references.
Add subheading for structs.
Tweak `is` docs for comparing class reference to null.
Add `operatoroverloading.dd` link to struct equality best practices.

Author: ntrel

spec/expression.dd

@@ -662,17 +662,37 @@ $(GNAME EqualExpression):
 
     $(H4 $(LNAME2 class_struct_equality, Class & Struct Equality))
 
+    $(P For class references, `a == b` is rewritten to `.object.opEquals(a, b)`,
+        which handles `null`.
+        This is intended to compare the contents of two objects, however an
+        appropriate $(D opEquals) method override must be defined for this to work.
+        The default $(D opEquals) provided by the root $(D Object) class is
+        equivalent to the $(RELATIVE_LINK2 identity_expressions, $(D is) operator).)
+
+    $(P For struct objects, the expression $(D (a == b))
+        is rewritten as $(D a.opEquals(b)), or failing that, $(D b.opEquals(a)).)
+
+    $(P For both class references and struct objects, $(D (a != b)) is rewritten as
+        $(D !(a == b)).)
+
+    $(P See $(DDSUBLINK spec/operatoroverloading, equals, `opEquals`) for details.)
+
+    $(H5 $(LNAME2 struct_equality, Struct Equality))
+
     $(P For struct objects, equality means the result of the
         $(LINK2 https://dlang.org/spec/operatoroverloading.html#equals, `opEquals()` member function).
         If an `opEquals()` is not provided, equality is defined as
         the logical product of all equality
         results of the corresponding object fields.
     )
 
-        $(IMPLEMENTATION_DEFINED The contents of any alignment gaps in the struct object.)
+        $(IMPLEMENTATION_DEFINED The contents of any $(DDSUBLINK spec/struct, struct_layout,
+        alignment gaps) in the struct object.)
+
+        $(P If there are overlapping fields, which happens with unions, the default
+        equality will compare each of the overlapping fields.)
 
-        $(BEST_PRACTICE If there are overlapping fields, which happens with unions, the default
-        equality will compare each of the overlapping fields.
+        $(BEST_PRACTICE
         An `opEquals()` can account for which of the overlapping fields contains valid data.
         An `opEquals()` can override the default behavior of floating point NaN values
         always comparing as unequal.
@@ -684,29 +704,6 @@ $(GNAME EqualExpression):
         $(LI there are any floating point fields that may contain NaN or `-0` values)
         )
 
-    $(P For class and struct objects, the expression $(D (a == b))
-        is rewritten as
-        $(D a.opEquals(b)), and $(D (a != b)) is rewritten as
-        $(D !a.opEquals(b)).
-    )
-
-    $(P For class objects, the $(D ==) and $(D !=)
-        operators are intended to compare the contents of the objects,
-        however an appropriate $(D opEquals) override must be defined for this to work.
-        The default $(D opEquals) provided by the root $(D Object) class is
-        equivalent to the $(D is) operator (see below).
-        Comparing against $(D null) is invalid, as $(D null) has no contents.
-        Use the $(D is) and $(D !is) operators instead.)
-
-        ---
-        class C;
-        C c;
-        if (c == null)  // error
-            ...
-        if (c is null)  // ok
-            ...
-        ---
-
 $(H3 $(LNAME2 identity_expressions, Identity Expressions))
 
 $(GRAMMAR
@@ -723,7 +720,7 @@ $(GNAME IdentityExpression):
     )
 
     $(P For class / interface objects, identity is defined as the object references being identical.
-        Null class objects can be compared with `is`.
+        Class references can be efficiently compared against `null` using `is`.
         Note that interface objects need not have the same reference of the class they were cast from.
         To test whether an `interface` shares a class instance with another `interface` / `class` value, cast both operands to `Object` before comparing with `is`.
     )

spec/operatoroverloading.dd

@@ -411,7 +411,7 @@ $(OL
     ---
     .object.opEquals(a, b)
     ---
-        $(P and that function is implemented as:)
+        $(P and that function is similar to:)
     ---
     bool opEquals(Object a, Object b)
     {
@@ -464,6 +464,8 @@ $(OL
         bool opEquals()(auto ref const S s) const { ... }
     }
     ---
+        $(NOTE See $(DDSUBLINK spec/expression, struct_equality, Struct Equality)
+        for best practices on implementing `opEquals` for structs.)
 
 
 $(H3 $(LNAME2 compare, Overloading $(D <), $(D <)$(D =), $(D >), and $(D >)$(D =)))