add ref-return-scope table

Author: WalterBright

spec/function.dd

@@ -1905,9 +1905,32 @@ $(H3 $(LNAME2 ref-return-scope-parameters, Ref Return Scope Parameters))
         When a parameter is passed by `ref` and has both the `return` and `scope` storage classes,
         it gets $(LINK2 #return-scope-parameters, `return scope`) semantics if and only if the `return` and `scope`
         keywords appear adjacent to each other, in that order.
-        Specifying a `return ref` and `scope` parameter enables returning a reference to a scope pointer.
-        In all other cases, the parameter has $(LINK2 #return-ref-parameters, `return ref`) semantics
-        and regular $(LINK2 #scope-parameters, `scope`) semantics.)
+        This behavior is summarized as follows:)
+
+        $(TABLE2 Combinations of `ref` $(COMMA) `return` and `scope`,
+        $(THEAD Order, Interpretation)
+        $(TROW `ref`,              $(REFP))
+        $(TROW `return`,           `return`)
+        $(TROW `scope`,            $(SCOPE))
+        $(TROW `return ref`,       $(RETURN_REF))
+        $(TROW `ref return`,       $(RETURN_REF))
+        $(TROW `return scope`,     $(RETURN_SCOPE))
+        $(TROW `scope return`,     $(RETURN_SCOPE))
+        $(TROW `ref scope`,        $(REFP) and $(SCOPE))
+        $(TROW `scope ref`,        $(REFP) and $(SCOPE))
+        $(TROW `ref return scope`, $(REFP) and $(RETURN_SCOPE))
+        $(TROW `return scope ref`, $(REFP) and $(RETURN_SCOPE))
+        $(TROW `ref scope return`, $(RETURN_REF) and $(SCOPE))
+        $(TROW `return ref scope`, $(RETURN_REF) and $(SCOPE))
+        $(TROW `scope return ref`, $(RETURN_REF) and $(SCOPE))
+        $(TROW `scope ref return`, $(RETURN_REF) and $(SCOPE))
+        )
+
+        $(BEST_PRACTICE do not use `ref return` and `scope return`.)
+
+        $(P Specifying a `return ref` and `scope` parameter enables returning a reference to a scope pointer.
+        In all other cases, the parameter has $(RETURN_REF) semantics
+        and regular $(SCOPE) semantics.)
 
 ---
 U xerxes(       ref return scope V v) // (1) ref and return scope
@@ -4230,3 +4253,7 @@ Macros:
         TITLE=Functions
         ASSIGNEXPRESSION=$(GLINK2 expression, AssignExpression)
         CHECK=✔
+        REFP=$(LINK2 #ref-params, `ref`)
+        RETURN_REF=$(LINK2 #return-ref-parameters, `return ref`)
+        SCOPE=$(LINK2 #scope-parameters, `scope`)
+        RETURN_SCOPE=$(LINK2 #return-scope-parameters, `return scope`)