Merge pull request #318 from 9rnsr/fix_attrib

Improve descriptions for various attributes

attribute.dd

@@ -11,21 +11,21 @@ $(GNAME Attribute):
     $(RELATIVE_LINK2 linkage, $(I LinkageAttribute))
     $(RELATIVE_LINK2 align, $(I AlignAttribute))
     $(GLINK2 pragma, Pragma)
-    $(RELATIVE_LINK2 deprecated, $(D deprecated))
+    $(RELATIVE_LINK2 deprecated, $(I DeprecatedAttribute))
     $(GLINK ProtectionAttribute)
-    $(D static)
+    $(RELATIVE_LINK2 static, $(D static))
     $(RELATIVE_LINK2 linkage, $(D extern))
     $(D final)
     $(D synchronized)
     $(RELATIVE_LINK2 override, $(D override))
     $(RELATIVE_LINK2 abstract, $(D abstract))
-    $(RELATIVE_LINK2 const, $(D const))
     $(RELATIVE_LINK2 auto, $(D auto))
     $(RELATIVE_LINK2 scope, $(D scope))
-    $(RELATIVE_LINK2 gshared, $(D __gshared))
-    $(RELATIVE_LINK2 shared, $(D shared))
+    $(RELATIVE_LINK2 const, $(D const))
     $(RELATIVE_LINK2 immutable, $(D immutable))
     $(RELATIVE_LINK2 inout, $(D inout))
+    $(RELATIVE_LINK2 shared, $(D shared))
+    $(RELATIVE_LINK2 gshared, $(D __gshared))
     $(RELATIVE_LINK2 disable, $(D @disable))
 
 
@@ -214,20 +214,36 @@ auto sz = S.sizeof;  // 12
 
 $(H3 $(LNAME2 deprecated, Deprecated Attribute))
 
+$(GRAMMAR
+$(GNAME DeprecatedAttribute):
+    $(D deprecated)
+    $(D deprecated $(LPAREN)) $(GLINK2 lex, StringLiteral) $(D $(RPAREN))
+)
+
         $(P It is often necessary to deprecate a feature in a library,
         yet retain it for backwards compatibility. Such
         declarations can be marked as deprecated, which means
         that the compiler can be set to produce an error
-        if any code refers to deprecated
-        declarations:
+        if any code refers to deprecated declarations:
         )
 
----------------
-deprecated
-{
-  void oldFoo();
-}
----------------
+        ---------------
+        deprecated
+        {
+          void oldFoo();
+        }
+
+        oldFoo();   // Deprecated: function test.oldFoo is deprecated
+        ---------------
+
+        $(P Optional $(GLINK2 lex, StringLiteral) can show additional
+        information in the deprecation message.
+        )
+
+        ---------------
+        deprecated("Don't use bar") void oldBar();
+        oldBar();   // Deprecated: function test.oldBar is deprecated - Don't use bar
+        ---------------
 
         $(P $(D Implementation Note:) The compiler should have a switch
         specifying if deprecated declarations should be compiled with
@@ -309,50 +325,79 @@ Foo f1; // error, could be either A.Foo or B.Foo
 B.Foo f2; // ok
 ---------------
 
-$(H3 $(LNAME2 const, Const Attribute))
+$(H3 $(LNAME2 const, $(D const) Attribute))
 
-        $(P The $(D const) attribute declares constants that can be
-        evaluated at compile time. For example:
+        $(P The $(D const) attribute affects the type of declared symbol,
+        and modifies the type to $(D const).
         )
 
----------------
-const int foo = 7;
+        ---------------
+        const int foo = 7;
+        static assert(is(typeof(foo) == const(int)));
+
+        const {
+          double bar = foo + 6;
+        }
+        static assert(is(typeof(bar) == const(double)));
+
+        class C {
+          const void foo();
+          const {
+            void bar();
+          }
+          void baz() const;
+        }
+        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)));
+        ---------------
+
+$(H3 $(LNAME2 immutable, $(D immutable) Attribute))
+
+        $(P The $(D immutable) attribute affects the type of declared symbol,
+        and modifies the type to $(D immutable), same as $(D const) does.
+        )
 
-const {
-  double bar = foo + 6;
-}
----------------
+$(H3 $(LNAME2 inout, $(D inout) Attribute))
 
+        $(P The $(D inout) attribute affects the type of declared symbol,
+        and modifies the type to $(D inout), same as $(D const) does.
+        )
 
+$(H3 $(LNAME2 shared, $(D shared) Attribute))
 
-$(H3 $(LNAME2 immutable, immutable Attribute))
+        $(P The $(D shared) attribute affects the type of declared symbol,
+        and modifies the type to $(D shared), same as $(D const) does.
+        )
 
-$(H3 $(LNAME2 gshared, $(D __gshared Attribute)))
+$(H3 $(LNAME2 gshared, $(D __gshared) Attribute))
 
         $(P By default, non-immutable global declarations reside in thread local
         storage. When a global variable is marked with the $(D __gshared)
         attribute, its value is shared across all threads.)
 
----
-int foo;            // Each thread has its own exclusive copy of foo.
-__gshared int bar;  // bar is shared by all threads.
----
+        ---
+        int foo;            // Each thread has its own exclusive copy of foo.
+        __gshared int bar;  // bar is shared by all threads.
+        ---
 
         $(P $(D __gshared) may also be applied to member variables and local
         variables. In these cases, $(D __gshared) is equivalent to $(D static),
         except that the variable is shared by all threads rather than being
         thread local.)
 
----
-class Foo {
-  __gshared int bar;
-}
+        ---
+        class Foo {
+          __gshared int bar;
+        }
 
-int foo() {
-  __gshared int bar = 0;
-  return bar++; // Not thread safe.
-}
----
+        int foo() {
+          __gshared int bar = 0;
+          return bar++; // Not thread safe.
+        }
+        ---
 
         $(P Unlike the $(D shared) attribute, $(D __gshared) provides no
         safe-guards against data races or other multi-threaded synchronization
@@ -361,11 +406,7 @@ int foo() {
 
         $(P $(D __gshared) is disallowed in safe mode.)
 
-$(H3 $(LNAME2 shared, shared Attribute))
-
-$(H3 $(LNAME2 inout, inout Attribute))
-
-$(H3 $(LNAME2 disable, @disable Attribute))
+$(H3 $(LNAME2 disable, $(D @disable) Attribute))
 
         $(P A reference to a declaration marked with the $(CODE @disable) attribute causes
         a compile time error.
@@ -416,7 +457,7 @@ class Foo2 : Foo {
 }
 ---------------
 
-$(H3 Static Attribute)
+$(H3 $(LNAME2 static, Static Attribute))
 
         $(P The $(D static) attribute applies to functions and data.
         It means that the declaration does not apply to a particular

struct.dd

@@ -291,24 +291,24 @@ $(TABLE2 Struct Field Properties,
 $(THEAD Name, Description)
 $(TROW $(D .offsetof), Offset in bytes of field from beginning of struct))
 
-$(SECTION3 $(LNAME2 ConstStruct, Const and Immutable Structs),
+$(SECTION3 $(LNAME2 ConstStruct, Const, Immutable and Shared Structs),
 
         $(P A struct declaration can have a storage class of
         $(CODE const), $(CODE immutable) or $(CODE shared). It has an equivalent
         effect as declaring each member of the struct as
         $(CODE const), $(CODE immutable) or $(CODE shared).
         )
 
-----
-const struct S { int a; int b = 2; }
+        ----
+        const struct S { int a; int b = 2; }
 
-void main() {
-  S s = S(3); // initializes s.a to 3
-  S t;        // initializes t.a to 0
-  t = s;      // error, t is const
-  t.a = 4;    // error, t.a is const
-}
-----
+        void main() {
+          S s = S(3); // initializes s.a to 3
+          S t;        // initializes t.a to 0
+          t = s;      // error, t.a and t.b are const, so cannot modify them.
+          t.a = 4;    // error, t.a is const
+        }
+        ----
 )
 
 $(SECTION3 $(LNAME2 Struct-Constructor, Struct Constructors),