[spec/declaration] Tweak Storage Class docs (#3554)

* [spec/declaration] Tweak Storage Class docs

Add links.
Make examples runnable.
Use distinct parameter name vs argument name.
Add 2 subheadings.

* Add links for const attribute

* Fix missing `)`, remove redundant MULTICOLS

Author: ntrel

spec/attribute.dd

@@ -31,7 +31,7 @@ $(GNAME Attribute):
     $(RELATIVE_LINK2 scope, $(D scope))
     $(RELATIVE_LINK2 shared, $(D shared))
     $(RELATIVE_LINK2 static, $(D static))
-    $(D synchronized)
+    $(DDSUBLINK spec/class, synchronized-classes, `synchronized`)
 
 $(GNAME FunctionAttributeKwd):
     $(RELATIVE_LINK2 nothrow, $(D nothrow))
@@ -463,7 +463,8 @@ $(H3 $(LNAME2 export, $(D export) Attribute))
 
 $(H2 $(LNAME2 const, $(D const) Attribute))
 
-        $(P The $(D const) attribute changes the type of the declared symbol from $(D T) to $(D const(T)),
+        $(P The $(DDLINK spec/const3, Type Qualifiers, $(D const) type qualifier)
+        changes the type of the declared symbol from $(D T) to $(D const(T)),
         where $(D T) is the type specified (or inferred) for the introduced symbol in the absence of $(D const).
         )
 
@@ -474,7 +475,10 @@ $(H2 $(LNAME2 const, $(D const) Attribute))
 
         const double bar = foo + 6;
         static assert(is(typeof(bar) == const(double)));
-
+        ---
+        )
+        $(SPEC_RUNNABLE_EXAMPLE_COMPILE
+        ---
         class C
         {
             const void foo();
@@ -487,11 +491,14 @@ $(H2 $(LNAME2 const, $(D const) Attribute))
         pragma(msg, typeof(C.foo)); // const void()
         pragma(msg, typeof(C.bar)); // const void()
         pragma(msg, typeof(C.baz)); // const void()
+
         static assert(is(typeof(C.foo) == typeof(C.bar)) &&
                       is(typeof(C.bar) == typeof(C.baz)));
         ---------------
         )
 
+        $(P See also: $(DDSUBLINK spec/declaration, methods-returning-qualified, Methods Returning a Qualified Type).)
+
 $(H2 $(LNAME2 immutable, $(D immutable) Attribute))
 
         $(P The $(D immutable) attribute modifies the type from $(D T) to $(D immutable(T)),
@@ -593,11 +600,12 @@ $(H2 $(LNAME2 pure, $(D pure) Attribute))
 
 $(H2 $(LNAME2 ref, $(D ref) Attribute))
 
-    $(P See $(DDSUBLINK spec/function, ref-functions, Ref Functions).)
+    $(P See $(DDSUBLINK spec/declaration, ref-storage, `ref` Storage Class).)
 
 $(H2 $(LNAME2 return, $(D return) Attribute))
 
-    $(P See $(DDSUBLINK spec/function, return-ref-parameters, Return Ref Parameters).)
+    * $(DDSUBLINK spec/function, return-ref-parameters, Return Ref Parameters).
+    * $(DDSUBLINK spec/function, return-scope-parameters, Return Scope Parameters).
 
 $(H2 $(LNAME2 override, $(D override) Attribute))
 

spec/declaration.dd

@@ -65,34 +65,36 @@ $(GNAME VarDeclarator):
 
 $(H3 $(LNAME2 storage-classes, Storage Classes))
 
+    $(P See $(RELATIVE_LINK2 typequal_vs_storageclass, Type Classes vs. Storage Classes).)
+
 $(GRAMMAR
 $(GNAME StorageClasses):
     $(GLINK StorageClass)
     $(GLINK StorageClass) $(GSELF StorageClasses)
 
 $(GNAME StorageClass):
-$(MULTICOLS 5,     $(GLINK2 attribute, LinkageAttribute)
+    $(GLINK2 attribute, LinkageAttribute)
     $(GLINK2 attribute, AlignAttribute)
     $(GLINK2 attribute, AtAttribute)
-    $(D deprecated)
-    $(D enum)
-    $(D static)
+    $(DDSUBLINK spec/attribute, deprecated, `deprecated`)
+    $(DDSUBLINK spec/enum, manifest_constants, `enum`)
+    $(DDSUBLINK spec/attribute, static, `static`)
     $(RELATIVE_LINK2 extern, $(D extern))
-    $(D abstract)
-    $(D final)
-    $(D override)
-    $(D synchronized)
-    $(D auto)
-    $(D scope)
-    $(D const)
-    $(D immutable)
-    $(D inout)
-    $(D shared)
-    $(D __gshared)
+    $(DDSUBLINK spec/class, abstract, `abstract`)
+    $(DDSUBLINK spec/class, final, `final`)
+    $(DDSUBLINK spec/function, virtual-functions, `override`)
+    $(DDSUBLINK spec/class, synchronized-classes, `synchronized`)
+    $(RELATIVE_LINK2 auto-declaration, `auto`)
+    $(DDSUBLINK spec/attribute, scope, `scope`)
+    $(DDLINK spec/const3, Type Qualifiers, `const`)
+    $(DDLINK spec/const3, Type Qualifiers, `immutable`)
+    $(DDSUBLINK spec/const3, inout, `inout`)
+    $(DDSUBLINK spec/const3, shared, `shared`)
+    $(DDSUBLINK spec/attribute, gshared, `__gshared`)
     $(GLINK2 attribute, Property)
-    $(D nothrow)
-    $(D pure)
-    $(D ref))
+    $(DDSUBLINK spec/function, nothrow-functions, `nothrow`)
+    $(DDSUBLINK spec/function, pure-functions, `pure`)
+    $(RELATIVE_LINK2 ref-storage, `ref`)
 )
 
 $(H3 $(LNAME2 initializers, Initializers))
@@ -664,7 +666,8 @@ $(H2 $(LNAME2 global_static_init, Global and Static Initializers))
 
 $(H2 $(LNAME2 typequal_vs_storageclass, Type Qualifiers vs. Storage Classes))
 
-        $(P Type qualifer and storage classes are distinct.)
+        $(P $(DDLINK spec/const3, Type Qualifiers, Type qualifers) and
+        $(RELATIVE_LINK2 storage-classes, storage classes) are distinct concepts.)
 
         $(P A $(I type qualifier) creates a derived type from an existing base
         type, and the resulting type may be used to create multiple instances
@@ -689,6 +692,7 @@ ImmutableInt z;     // typeof(z) == immutable(int)
         with the $(D const) storage class to indicate that it does not modify
         its implicit $(D this) argument:)
 
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
 --------
 struct S
 {
@@ -700,16 +704,22 @@ struct S
     }
 }
 --------
-
-        $(P Although some keywords can be used both as a type qualifier and a
+)
+        $(P Although some keywords can be
+        $(RELATIVE_LINK2 methods-returning-qualified, used as both) a type qualifier and a
         storage class, there are some storage classes that cannot be used to
-        construct new types, such as $(D ref):)
+        construct new types, such as $(D ref).)
+
+$(H3 $(LNAME2 ref-storage, `ref` Storage Class))
+
+        $(P A parameter $(DDSUBLINK spec/function, ref-params, declared with `ref`)
+        is passed by reference:)
 
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 --------
-// ref declares the parameter x to be passed by reference
-void func(ref int x)
+void func(ref int i)
 {
-    x++; // so modifications to x will be visible in the caller
+    i++; // modifications to i will be visible in the caller
 }
 
 void main()
@@ -719,12 +729,14 @@ void main()
     assert(x == 2);
 
     // However, ref is not a type qualifier, so the following is illegal:
-    ref(int) y; // Error: ref is not a type qualifier.
+    //ref(int) y; // Error: ref is not a type qualifier.
 }
 --------
+)
+        $(P Functions can also be $(DDSUBLINK spec/function, ref-functions, declared as `ref`),
+        meaning their return value is passed by reference:)
 
-        $(P Functions can also be declared as `ref`, meaning their return value is
-        passed by reference:)
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 --------
 ref int func2()
 {
@@ -749,11 +761,14 @@ void main()
                           // does not inherit the ref storage class from func2().
 }
 --------
+)
+$(H3 $(LNAME2 methods-returning-qualified, Methods Returning a Qualified Type))
 
         $(P Some keywords, such as $(D const), can be used
         both as a type qualifier and a storage class.
         The distinction is determined by the syntax where it appears.)
 
+        $(SPEC_RUNNABLE_EXAMPLE_COMPILE
         ---
         struct S
         {
@@ -763,8 +778,9 @@ void main()
              */
             const int* func() // a const function
             {
-                ++p;          // error, this.p is const
-                return p;     // error, cannot convert const(int)* to int*
+                //++p;          // error, this.p is const
+                //return p;     // error, cannot convert const(int)* to int*
+                return null;
             }
 
             const(int)* func() // a function returning a pointer to a const int
@@ -776,6 +792,7 @@ void main()
             int* p;
         }
         ---
+        )
 
         $(BEST_PRACTICE To avoid confusion, the type qualifier
         syntax with parentheses should be used for return types,