Merge pull request #2003 from wilzbach/1040-attributes

Revive #1040 - spec/attributes.d
merged-on-behalf-of: Sebastian Wilzbach <sebi.wilzbach@gmail.com>

Author: dlang-bot

spec/attribute.dd

@@ -37,12 +37,13 @@ $(GNAME Property):
     $(GLINK UserDefinedAttribute)
 
 $(GNAME PropertyIdentifier):
-    $(RELATIVE_LINK2 property, $(D property))
-    $(D safe)
-    $(D trusted)
-    $(D system)
+    $(RELATIVE_LINK2 property, `property`)
+    $(RELATIVE_LINK2 safe, `@safe`)
+    $(RELATIVE_LINK2 safe, `@trusted`)
+    $(RELATIVE_LINK2 safe, `@system`)
     $(RELATIVE_LINK2 disable, $(D disable))
-    $(RELATIVE_LINK2 nogc, $(D nogc))
+    $(RELATIVE_LINK2 nogc, `nogc`)
+    $(RELATIVE_LINK2 disable, `@disable`)
 
 $(GNAME DeclarationBlock):
     $(GLINK2 module, DeclDef)
@@ -502,45 +503,13 @@ void main() { foo(); /* error, foo is disabled */ }
         makes the struct not copyable.
         )
 
-$(H2 $(LNAME2 nogc, $(D @nogc) Attribute))
-
-        $(P $(D @nogc) applies to functions, and means that that function does not
-        allocate memory on the GC heap, either directly such as with
-        $(GLINK2 expression, NewExpression) or
-        indirectly through functions it may call, or through language features
-        such as array concatenation and dynamic closures.
-        )
-
-        ---
-        @nogc void foo(char[] a)
-        {
-            auto p = new int;  // error, operator new allocates
-            a ~= 'c';          // error, appending to arrays allocates
-            bar();             // error, bar() may allocate
-        }
-
-        void bar() { }
-        ---
+$(H2 $(LNAME2 safe, $(D @safe), $(D @trusted), and $(D @system) Attribute))
 
-        $(P $(D @nogc) affects the type of the function. An $(D @nogc) function is covariant
-        with a non-$(D @nogc) function.
-        )
-
-        ---
-        void function() fp;
-        void function() @nogc gp;  // pointer to @nogc function
+    $(P See $(DDSUBLINK function, function-safety, Function Safety).)
 
-        void foo();
-        @nogc void bar();
+$(H2 $(LNAME2 nogc, $(D @nogc) Attribute))
 
-        void test()
-        {
-            fp = &foo; // ok
-            fp = &bar; // ok, it's covariant
-            gp = &foo; // error, not contravariant
-            gp = &bar; // ok
-        }
-        ---
+    $(P See $(DDSUBLINK function, nogc-functions, No-GC Functions).)
 
 $(H2 $(LNAME2 property, $(D @property) Attribute))
 
@@ -643,6 +612,10 @@ $(H2 $(LNAME2 auto, $(D auto) Attribute))
 auto i = 6.8;   // declare i as a double
 ---
 
+    $(P For functions, the `auto` attribute means return type inference.
+        See $(DDSUBLINK function, auto-functions, Auto Functions).
+    )
+
 $(H2 $(LNAME2 scope, $(D scope) Attribute))
 
 $(P
@@ -703,16 +676,6 @@ $(P
 
 $(H2 $(LNAME2 uda, User Defined Attributes))
 
-        $(P
-            User Defined Attributes (UDA) are compile time expressions that can be attached
-            to a declaration. These attributes can then be queried, extracted, and manipulated
-            at compile time. There is no runtime component to them.
-        )
-
-        $(P
-            Grammatically, a UDA is a StorageClass:
-        )
-
 $(GRAMMAR
 $(GNAME UserDefinedAttribute):
     $(D @ $(LPAREN)) $(GLINK2 expression, ArgumentList) $(D $(RPAREN))
@@ -722,7 +685,13 @@ $(GNAME UserDefinedAttribute):
     $(D @) $(GLINK2 template, TemplateInstance) $(D $(LPAREN)) $(GLINK2 expression, ArgumentList)$(OPT) $(D $(RPAREN))
 )
 
-And looks like:
+    $(P
+        User Defined Attributes (UDA) are compile-time expressions that can be attached
+        to a declaration. These attributes can then be queried, extracted, and manipulated
+        at compile time. There is no runtime component to them.
+    )
+
+A user-defined attribute looks like:
 
 ---
 @(3) int a;