[spec/hash-map] Improve Properties section (#4342)

Some tweaks following #4339.

Merge first 2 tables.
Add subheading for iteration operations.
Move rehash paragraph into table.
Add link to `object` docs for examples.
Don't hardcode HTML links.
Tweak wording.
Move byKeyValue paragraph into table.
Use BEST_PRACTICE for iteration.
Add subheading for key lookup operations.
Improve `update` description.

Author: ntrel

spec/hash-map.dd

@@ -432,93 +432,91 @@ $(SPEC_RUNNABLE_EXAMPLE_RUN
 
 $(H2 $(LNAME2 properties, Properties and Operations))
 
-    $(TABLE_2COLS Associative Array Properties,
-        $(THEAD Property name, Description)
+    $(TABLE
+        $(THEAD Name, Description)
         $(TROW $(D sizeof), $(ARGS The size of the reference to the associative
         array; it is 4 in 32-bit builds and 8 on 64-bit builds.))
         $(TROW $(D length), $(ARGS The number of values in the
         associative array. Unlike for dynamic arrays, it is read-only.))
-    )
-
-    $(P There is no built-in `empty` property.
-        Phobos provides an implementation of `empty` in `std.range.primitives`.)
-
-    $(TABLE_2COLS Associative Array Organizing Operations,
-        $(TROW $(D dup()), Returns `null` If the associative array is `null`;
+        $(TROW $(D dup()), Returns `null` if the associative array is `null`;
         otherwise returns a newly allocated associative array with copies of the keys and values of the associative array.)
         $(TROW $(D rehash()), $(ARGS Reorganizes the associative array in place so that lookups
-        are more efficient.))
+        are more efficient. Calling $(D rehash) is effective when, for example,
+        the program is done loading up a symbol table and now needs
+        fast lookups in it. Returns a reference to the reorganized array.))
         $(TROW $(D clear()), $(ARGS Removes all keys and values from an associative array.
         The array is not rehashed after removal to allow for the existing storage to be reused.
         This will affect all references to the same instance and is not equivalent to `destroy(aa)`
-        which only sets the current reference to `null`))
+        which only sets the current reference to `null`.))
     )
 
-    $(P Calling $(D rehash) is effective when, for example,
-        the program is done loading up a symbol table and now needs
-        fast lookups in it. Returns a reference to the reorganized array.)
+    $(NOTE There is no built-in `empty` property.
+        Phobos provides an implementation of `empty` in $(MREF std,range,primitives).)
+
+    $(P See $(MREF1 object) for examples.)
 
-    $(TABLE_2COLS Associative Array Iteration Operations,
+$(H3 $(LNAME2 iteration-ops, Iteration Operations))
+
+    $(TABLE
         $(THEAD Operation, Description)
         $(TROW $(D keys()), $(ARGS Returns a newly allocated dynamic array containing copies of the keys in
-        the associative array in an order that is consistent with `values()` but otherwise unspecified.))
-        $(TROW $(D values()), $(ARGS Returns a newly allocated dynamic arraycontaining copies of the values in
-        the associative array in an order that is consistent with `keys()` but otherwise unspecified.))
-        $(TROW $(D byKey()), $(ARGS Returns a forward range enumerating the keys by reference
-        in an order that is consistent with `byValue()` but otherwise unspecified.
+        the associative array. The order is consistent with `values()` but otherwise unspecified.))
+        $(TROW $(D values()), $(ARGS Returns a newly allocated dynamic array containing copies of the values in
+        the associative array. The order is consistent with `keys()` but otherwise unspecified.))
+        $(TROW $(D byKey()), $(ARGS Returns a forward range enumerating the keys by reference.
+        The order is consistent with `byValue()` but otherwise unspecified.$(BR)
         $(B Bug:) The keys are provided as mutable, but mutating them is undefined behavior.))
-        $(TROW $(D byValue()), $(ARGS Returns a forward range enumerating the values by reference
-        in an order that is consistent with `byKey()` but otherwise unspecified.))
+        $(TROW $(D byValue()), $(ARGS Returns a forward range enumerating the values by reference.
+        The order is consistent with `byKey()` but otherwise unspecified.))
         $(TROW $(D byKeyValue()), $(ARGS Returns a forward range enumerating opaque objects that provide a `key` and a `value` property
-        in an unspecified order. The two properties return their result by reference.
-        $(B Bug:) The keys are provided as mutable, but mutating them is undefined behavior.))
+        in an unspecified order. The two properties return their result by reference.$(BR)
+        $(B Bug:) The keys are provided as mutable, but mutating them is undefined behavior.$(BR)
+        **Note:** `byKeyValue()` is not compatible with the $(REF_SHORT Tuple, std,typecons)
+        type in Phobos. For compatibility with `Tuple`, use $(REF byPair, std,array) instead.)))
     )
 
     $(P The order of keys and values returned by
         `keys()` and `values()` as well as
         `byKey()`, `byValue()`, and `byKeyValue()` is unspecified,
-        but is guaranteed to be consistent to each other
-        as long as the associative array has not been reorganized,
+        but is guaranteed to be consistent as long as the associative array has not been reorganized,
         e.g. by adding or removing keys between the calls.
         Associating a new value to an existing key does not reorganize an associative array.
-        Reorganizing an associative array invalidates any present input ranges
+        Reorganizing an associative array invalidates any input ranges
         returned by `byKey()`, `byValue()`, and `byKeyValue()`.)
 
-    $(P Calling `keys()` and `values()` incurs an allocation unless the associative array is `null` or empty.
+    $(P Calling `keys()` and `values()` incurs an allocation (unless the associative array is `null` or empty).
         Use them if you need an independent copy of the keys and/or values;
         otherwise consider `byKey()` and `byValue()`.)
 
-    $(P Note that `byKeyValue()` is not compatible
-        with the $(LINK2 $(ROOT_DIR)phobos/std_typecons.html#.Tuple,`Tuple`)
-        type in Phobos. For compatibility with `Tuple`, use
-        $(LINK2 $(ROOT_DIR)phobos/std_array.html#.byPair,std.array.byPair) instead.)
-
-    $(P Associative arrays support $(LINK2 $(ROOT_DIR)spec/statement.html#foreach_over_associative_arrays, `foreach`)
+    $(BEST_PRACTICE Associative arrays support
+        $(DDSUBLINK spec/statement, foreach_over_associative_arrays, `foreach`)
         directly for value iteration and key-value iteration.
-        It is recommended to use `ref` on the key and value variables to avoid unnecessary copies.
+        Use `ref` on the key and value variables when necessary to avoid unnecessary copies.
         For iterating the keys only, use key-value iteration and ignore the value.
-        Use `byKey()`, `byValue()`, or `byKeyValue()` for more elaborate cases such as range algorithms.)
+        Use `byKey()`, `byValue()`, or `byKeyValue()` for more elaborate cases such as
+        $(MREF_ALTTEXT range algorithms, std,algorithm).)
 
-    $(TABLE_2COLS Associative Array Elaborate Lookup Operations,
+$(H3 $(LNAME2 lookup-ops, Key Lookup Operations))
+
+    $(TABLE
+        $(THEAD Operation, Description)
         $(TROW $(D Value get(Key key, lazy Value defVal)),
-        $(ARGS Looks up $(D key);
-        if it exists, returns corresponding value;
+        $(ARGS If the key exists, returns corresponding value;
         otherwise evaluates and returns $(D defVal) without associating it with $(D key).))
         $(TROW $(D ref Value require(Key key, lazy Value value)),
-        $(ARGS Looks up $(D key);
-        if it exists, returns corresponding value by reference;
+        $(ARGS If the key exists, returns corresponding value by reference;
         otherwise evaluates $(D value) and associates it with $(D key) in the associative array,
         then returns the newly stored value by reference.))
         $(TROW $(D void update(Key key, Creator creator, Updater updater)),
-        $(ARGS Looks up $(D key);
-        if it exists, invokes the `updater(value)` on the value (passed by reference if possible)
-        and then, unless `updater(value)` is `void`, associates the result with the key;
-        otherwise invokes `creator()` and associates the result with `key` in the associative array.))
+        $(ARGS If the key exists, it calls `updater` with the corresponding value;
+        if it returns a value, it associates the value with the key.
+        If the key was not found, it invokes `creator()` and associates the result with the key.))
     )
 
     $(P The `update` operation works with any `creator` and `updater` that is invokable as specified.
-        An updater can modify the value in-place if it binds its argument by reference.
-        A `void` returning updater with by-reference parameter is recommended to avoid unnecessary copies.)
+        `updater` can modify the value in-place if it binds its argument by reference.)
+
+    $(BEST_PRACTICE A `void` returning `updater` with a `ref` parameter avoids unnecessary copies.)
 
 $(H2 $(LNAME2 examples, Examples))