[spec/function.dd] Improve *Virtual Functions* section

Move simple overriding example from 'Function Inheritance and
Overriding'. This introduces `override` before the next more complex
example about virtual vs non-virtual methods.
Explain that `override` is required and that it can catch bugs.
Use list for kinds of non-virtual functions.
Simplify examples a bit.
Move paragraph about Objective-C to end of section.
Add 'Covariance' subheading.
Add 'Calling Base Class Methods' subheading & tweak wording.
Change 'Function Inheritance and Overriding' subheading to 'Overload
Sets and Overriding'.
Default Values))
Add 'Default Values', 'Inherited Attributes', 'Restrictions'
subheadings.

'Function Parameters' section:
Add subheading & move `this` reference and Obj-C selector docs here.

attributes.dd:
Remove info and link to 'Virtual Functions'.

Author: ntrel

spec/attribute.dd

@@ -549,30 +549,7 @@ $(H2 $(LNAME2 return, $(D return) Attribute))
 
 $(H2 $(LNAME2 override, $(D override) Attribute))
 
-        $(P The $(D override) attribute applies to virtual functions.
-        It means that the function must override a function with the
-        same name and parameters in a base class. The override attribute
-        is useful for catching errors when a base class's member function
-        gets its parameters changed, and all derived classes need to have
-        their overriding functions updated.
-        )
-
----------------
-class Foo
-{
-    int bar();
-    int abc(int x);
-}
-
-class Foo2 : Foo
-{
-    override
-    {
-        int bar(char c); // error, no bar(char) in Foo
-        int abc(int x);  // ok
-    }
-}
----------------
+    $(P See $(DDSUBLINK spec/function, virtual-functions, Virtual Functions).)
 
 $(H2 $(LNAME2 static, $(D static) Attribute))
 

spec/function.dd

@@ -954,26 +954,45 @@ $(H2 $(LNAME2 virtual-functions, Virtual Functions))
 
         $(P Virtual functions are class member functions that are called indirectly through a
         function pointer table, called a `vtbl[]`, rather than directly.
+        Member functions that are virtual can be overridden in a derived class:
         )
 
-        $(P Member functions that are virtual can be overridden, unless they are `final`.
-        )
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+------
+class A
+{
+    void foo(int x) {}
+}
 
-        $(P Struct and union member functions are not virtual.
-        )
+class B : A
+{
+    override void foo(int x) {}
+    //override void foo() {} // error, no foo() in A
+}
 
-        $(P Static member functions are not virtual.
-        )
+void test()
+{
+    A a = new B();
+    a.foo(1);   // calls B.foo(int)
+}
+------
+)
 
-        $(P Member functions which are $(D private) or $(D package) are not virtual.
-        )
+        $(P The `override` attribute is required when overriding a function.
+        This is useful for catching errors when a base class's member function
+        has its parameters changed, and all derived classes need to have
+        their overriding functions updated.)
 
-        $(P Member template functions are not virtual.
+        $(P The following are not virtual:)
+        $(UL
+        $(LI Struct and union member functions)
+        $(LI `final` member functions)
+        $(LI $(DDSUBLINK attribute, static, `static`) member functions)
+        $(LI Member functions which are $(D private) or $(D package))
+        $(LI Member template functions)
         )
 
-        $(P Member functions with `Objective-C` linkage are virtual even if marked
-        with `final` or `static`.
-        )
+        $(P $(B Example:))
 
 ------
 class A
@@ -992,22 +1011,23 @@ class B : A
     int abc() { ... }  // ok, A.abc is not virtual, B.abc is virtual
 }
 
-void test(A a)
+void test()
 {
+    A a = new B;
     a.def();    // calls B.def
     a.foo();    // calls A.foo
     a.bar();    // calls A.bar
     a.abc();    // calls A.abc
 }
-
-void func()
-{
-    B b = new B();
-    test(b);
-}
 ------
 
-        $(P The overriding function may be covariant with the overridden function.
+        $(P Member functions with `Objective-C` linkage are virtual even if marked
+        with `final` or `static`, and can be overridden.
+        )
+
+$(H3 $(LNAME2 covariance, Covariance))
+
+        $(P An overriding function may be covariant with the overridden function.
         A covariant function has a type that is implicitly convertible to the
         type of the overridden function.
         )
@@ -1030,21 +1050,12 @@ class Bar : Foo
 ------
 )
 
-        $(P
-            Non-static (i.e., virtual functions and `final` member
-            functions) all have a hidden parameter called the
-            `this` reference, which refers to the class object for which
-            the function is called.
-        )
+$(H3 $(LNAME2 base-methods, Calling Base Class Methods))
 
-        $(P
-            Functions with `Objective-C` linkage have an additional hidden,
-            unnamed, parameter which is the selector it was called with.
-        )
-
-        $(P To directly call a base member function (i.e., avoid dynamic
-        binding on member function call), insert the base class name before
-        the member function name. For example:
+        $(P To directly call a member function of a base class `Base`,
+        write `Base.` before the function name.
+        This avoids dynamic dispatch through a function pointer. For
+        example:
         )
 
 $(SPEC_RUNNABLE_EXAMPLE_COMPILE
@@ -1086,33 +1097,7 @@ void main()
         known, such as if it is `final`, it can use a direct call instead.
         )
 
-$(H3 $(LNAME2 function-inheritance, Function Inheritance and Overriding))
-
-        $(P A function in a derived class with the same name and covariant
-        with a function in a base class overrides that function:)
-
-------
-class A
-{
-    int foo(int x) { ... }
-}
-
-class B : A
-{
-    override int foo(int x) { ... }
-}
-
-void test()
-{
-    B b = new B();
-    bar(b);
-}
-
-void bar(A a)
-{
-    a.foo(1);   // calls B.foo(int)
-}
-------
+$(H3 $(LNAME2 function-inheritance, Overload Sets and Overriding))
 
         $(P When doing overload resolution, the functions in the base
         class are not considered, as they are not in the same
@@ -1134,9 +1119,9 @@ class B : A
 void test()
 {
     B b = new B();
-    b.foo(1);  // calls B.foo(long), since A.foo(int) not considered
-    A a = b;
+    b.foo(1);  // calls B.foo(long), since A.foo(int) is not considered
 
+    A a = b;
     a.foo(1);  // issues runtime error (instead of calling A.foo(int))
 }
 ------
@@ -1160,12 +1145,7 @@ class B : A
 
 void test()
 {
-    B b = new B();
-    bar(b);
-}
-
-void bar(A a)
-{
+    A a = new B();
     a.foo(1);      // calls A.foo(int)
     B b = new B();
     b.foo(1);      // calls A.foo(int)
@@ -1180,6 +1160,8 @@ void bar(A a)
         implicit conversions to the base class, those other functions do
         get called:
         )
+
+$(SPEC_RUNNABLE_EXAMPLE_FAIL
 ---
 class A
 {
@@ -1188,22 +1170,19 @@ class A
 }
 class B : A
 {
-    void set(long i) { }
+    override void set(long i) { }
 }
 
-void foo(A a)
+void test()
 {
-    int i;
+    A a = new B;
     a.set(3);   // error, use of A.set(int) is hidden by B
                 // use 'alias set = A.set;' to introduce base class overload set
-    assert(i == 1);
-}
-
-void main()
-{
-    foo(new B);
 }
 ---
+)
+
+$(H3 $(LNAME2 override-defaults, Default Values))
 
         $(P A function parameter's default value is not inherited:)
 
@@ -1236,6 +1215,8 @@ void test()
 }
 ------
 
+$(H3 $(LNAME2 inheriting-attributes, Inherited Attributes))
+
         $(P An overriding function inherits any unspecified $(GLINK FunctionAttributes)
         from the attributes of the overridden function.)
 
@@ -1258,6 +1239,8 @@ void main()
 ------
 )
 
+$(H3 $(LNAME2 override-restrictions, Restrictions))
+
         $(P The attributes
         $(LINK2 attribute.html#disable, $(D @disable)) and
         $(LINK2 attribute.html#deprecated, $(D deprecated))
@@ -1281,7 +1264,6 @@ void main()
         }
         ---
 
-    $(P Static functions with `Objective-C` linkage are overridable.)
 
 $(H2 $(LNAME2 inline-functions, Inline Functions))
 
@@ -2414,6 +2396,19 @@ $(H4 $(LNAME2 lazy_variadic_functions, Lazy Variadic Functions))
         parameter. This will prevent a closure being generated for the delegate,
         as `scope` means the delegate will not escape the function.)
 
+$(H3 $(LNAME2 this-reference, `this` Reference))
+
+        $(P
+            Non-static member functions all have a hidden parameter called the
+            `this` reference, which refers to the object for which
+            the function is called.
+        )
+
+        $(P
+            Functions with `Objective-C` linkage have an additional hidden,
+            unnamed, parameter which is the selector it was called with.
+        )
+
 
 $(H2 $(LEGACY_LNAME2 Local Variables, local-variables, Local Variables))