[spec] Document ref variables

Author: ntrel

spec/declaration.dd

@@ -852,6 +852,43 @@ void main()
 }
 --------
 )
+
+$(H4 $(LNAME2 ref-variables, `ref` Variables))
+
+        $(P From version 2.111, `ref` can be used to declare local, static, extern, and global variables.)
+
+$(COMMENT SPEC_RUNNABLE_EXAMPLE_RUN)
+---
+struct S { int a; }
+
+void main()
+{
+    S s;
+    ref int r = s.a;
+    r = 3;
+    assert(s.a == 3);
+}
+---
+
+        $(BEST_PRACTICE Use a `ref` variable instead of a pointer when pointer
+        arithmetic is not needed.)
+
+        $(P `auto ref` can also be used to declare local, static, extern, and global variables.)
+
+$(COMMENT SPEC_RUNNABLE_EXAMPLE_COMPILE)
+---
+void f()
+{
+    auto ref x = 0;
+    auto ref y = x;
+    static assert(!__traits(isRef, x));
+    static assert( __traits(isRef, y));
+}
+---
+
+        $(P See also: $(DDSUBLINK spec/template, auto-ref-parameters, `auto ref`)
+        template function parameters.)
+
 $(H3 $(LNAME2 methods-returning-qualified, Methods Returning a Qualified Type))
 
         $(P Some keywords, such as $(D const), can be used