[spec] Tweak enum & type docs (#3683)

* [spec] Tweak enum & type docs

Move *Enum Default Initializer* section into *Enum Properties*.
Add link to enum operations.
Add Enum Operations subheading and example.
Add *Preserving Bit Patterns* subheading, use list.

* Extend example to show errors

* Add *Enum Variables* subheading

Link to final switch.

* Preserve default initializer anchor

* Use list for items about named enums and types

Author: ntrel

spec/enum.dd

@@ -70,18 +70,15 @@ $(H2 $(LNAME2 named_enums, Named Enums))
         ---
 
 
-        $(P If the $(I EnumBaseType) is not explicitly set, and the first
+        $(P If the $(GLINK EnumBaseType) is not explicitly set, and the first
         $(I EnumMember) has an *AssignExpression*, it is set to the type of that
         *AssignExpression*. Otherwise, it defaults to
         type $(CODE int).)
 
-        $(P Named enum members may not have individual $(I Type)s.
-        )
-
-        $(P A named enum member can be implicitly cast to its $(GLINK EnumBaseType),
-        but $(I EnumBaseType) types
-        cannot be implicitly cast to an enum type.
-        )
+        * A named enum member can be
+          $(DDSUBLINK spec/type, implicit-conversions, implicitly cast to its $(I EnumBaseType)).
+        * An $(I EnumBaseType) instance cannot be implicitly cast to a named enum type.
+        * A named enum member does not have an individual $(I Type).
 
         $(P The value of an $(GLINK EnumMember) is given by its *AssignExpression* if present.
         If there is no *AssignExpression* and it is the first $(I EnumMember),
@@ -129,17 +126,26 @@ enum E : C
         writeln(X.init); // error: enum X is opaque and has no default initializer
         ---
 
-$(H3 $(LNAME2 enum_default_initializer, Enum Default Initializer))
+$(H3 $(LEGACY_LNAME2 enum_default_initializer, enum_variables, Enum Variables))
 
-        $(P The $(CODE .init) property of an enum type is the value
-        of the first member of that enum.
-        This is also the default initializer for the enum type.
+        $(P A variable can be of named enum type.
+        The default initializer is the first member defined for the enum type.
         )
 
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ------
 enum X { A=3, B, C }
-X x;      // x is initialized to 3
+X x;
+assert(x == X.A);
+x |= X.B;
+assert(x & X.A);
 ------
+)
+
+        $(P The result type of a binary operation performed when the operands have
+        different types is defined $(DDSUBLINK spec/type, enum-ops, here).)
+
+        $(P See also: $(DDSUBLINK spec/statement, final-switch-statement, `final switch`).)
 
 $(H3 $(LNAME2 enum_properties, Enum Properties))
 

spec/type.dd

@@ -432,8 +432,10 @@ $(H3 $(LEGACY_LNAME2 Usual Arithmetic Conversions, usual-arithmetic-conversions,
     ---
     )
 
-    $(P If one or both of the operand types is an enum  after
-    undergoing the above conversions, the result type is:)
+$(H4 $(LNAME2 enum-ops, Enum Operations))
+
+    $(P If one or both of the operand types is an $(DDLINK spec/enum, Enums, enum) after
+    undergoing the above conversions, the result type is determined as follows:)
 
     $(OL
     $(LI If the operands are the same type, the result will be of
@@ -446,6 +448,32 @@ $(H3 $(LEGACY_LNAME2 Usual Arithmetic Conversions, usual-arithmetic-conversions,
     original type.)
     )
 
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+---
+enum E { a, b, c }
+enum F { x, y }
+
+void test()
+{
+    E e = E.a;
+    e = e | E.c;
+    //e = e + 4; // error, can't assign int to E
+    int i = e + 4;
+    e += 4; // OK, see below
+
+    F f;
+    //f = e | f; // error, can't assign int to F
+    i = e | f;
+}
+---
+)
+
+    $(NOTE Above, `e += 4` compiles because the
+    $(DDSUBLINK spec/expression, assignment_operator_expressions, operator assignment)
+    is equivalent to `e = cast(E)(e + 4)`.)
+
+$(H3 $(LNAME2 disallowed-conversions, Preserving Bit Patterns))
+
     $(P Integer values cannot be implicitly converted to another
     type that cannot represent the integer bit pattern after integral
     promotion. For example:)
@@ -459,12 +487,12 @@ ulong  u4 = long(-1); // ok, -1 can be represented in a long, which can be conve
 ---
 )
 
-    $(P Floating point types cannot be implicitly converted to
-    integral types. Complex or imaginary floating point types cannot be implicitly converted
-    to non-complex floating point types. Non-complex floating point types
-    cannot be implicitly converted to imaginary floating
-    point types.
-    )
+    * Floating point types cannot be implicitly converted to
+      integral types.
+    * Complex or imaginary floating point types cannot be implicitly converted
+      to non-complex floating point types.
+    * Non-complex floating point types cannot be implicitly converted to imaginary floating
+      point types.
 
 $(H3 $(LNAME2 vrp, Value Range Propagation))