Move scope parameter row to its own section

Also split return scope example.
Reparent `return scope` section headings.
Remove note about -dip1000 in return scope section as it is now
mentioned in the (earlier) scope parameter section.

Author: ntrel

spec/function.dd

@@ -1246,14 +1246,6 @@ int foo(in int x, out int y, ref int z, int q);
     The parameter must not escape the function call
     (e.g. by being assigned to a global variable).
     Ignored for any parameter that is not a reference type.
-    `scope` escape analysis is only done for `@safe` functions. For other functions `scope`
-    semantics must be manually enforced.)
-    $(P $(B Note): `scope` escape analysis is currently only done by `dmd`
-    when the `-dip1000` switch is passed.)
-    $(P As the parameter must not escape, the compiler can potentially avoid heap-allocation of a
-    unique argument to a `scope` parameter. Due to this, passing an array literal, delegate
-    literal or a $(GLINK2 expression, NewExpression) to a scope parameter may be used in a
-    `@nogc` context, depending on the compiler implementation.)
     ))
     $(TROW $(D return), $(ARGS Parameter may be returned or copied to the first parameter,
     but otherwise does not escape from the function.
@@ -1545,35 +1537,60 @@ inout(int)* neptune(inout ref int i)
 }
 ---
 
-$(H3 $(LNAME2 return-scope-parameters, Return Scope Parameters))
+$(H3 $(LNAME2 scope-parameters, Scope Parameters))
 
-        $(P Parameters marked as `return scope` that contain indirections
-        can only escape those indirections via the function's return value.)
+    $(P A `scope` parameter of reference type must not escape the function call
+    (e.g. by being assigned to a global variable). It has no effect for non-reference types.
+    `scope` escape analysis is only done for `@safe` functions. For other functions `scope`
+    semantics must be manually enforced.)
+    $(P $(B Note): `scope` escape analysis is currently only done by `dmd`
+    when the `-dip1000` switch is passed.)
 
 ---
 @safe:
 
 int* gp;
 void thorin(scope int*);
 void gloin(int*);
-int* balin(return scope int* p, scope int* q, int* r)
+int* balin(scope int* q, int* r)
 {
-     gp = p; // error, p escapes to global gp
      gp = q; // error, q escapes to global gp
      gp = r; // ok
 
-     thorin(p); // ok, p does not escape thorin()
-     thorin(q); // ok
+     thorin(q); // ok, q does not escape thorin()
      thorin(r); // ok
 
-     gloin(p); // error, gloin() escapes p
      gloin(q); // error, gloin() escapes q
      gloin(r); // ok that gloin() escapes r
 
-     return p; // ok
      return q; // error, cannot return 'scope' q
      return r; // ok
 }
+---
+
+    $(P As a `scope` parameter must not escape, the compiler can potentially avoid heap-allocating a
+    unique argument to a `scope` parameter. Due to this, passing an array literal, delegate
+    literal or a $(GLINK2 expression, NewExpression) to a scope parameter may be allowed in a
+    `@nogc` context, depending on the compiler implementation.)
+
+$(H4 $(LNAME2 return-scope-parameters, Return Scope Parameters))
+
+        $(P Parameters marked as `return scope` that contain indirections
+        can only escape those indirections via the function's return value.)
+
+---
+@safe:
+
+int* gp;
+void thorin(scope int*);
+void gloin(int*);
+int* balin(return scope int* p)
+{
+     gp = p; // error, p escapes to global gp
+     thorin(p); // ok, p does not escape thorin()
+     gloin(p); // error, gloin() escapes p
+     return p; // ok
+}
 ---
 
         $(P Class references are considered pointers that are subject to `scope`.)
@@ -1617,10 +1634,7 @@ class C
         $(P Template functions, auto functions, nested functions and lambdas can deduce
         the `return scope` attribute.)
 
-        $(P $(B Note:) Checks for `scope` parameters are currently enabled
-        only for $(D @safe) functions when compiled with the $(D -dip1000) flag.)
-
-$(H3 $(LNAME2 ref-return-scope-parameters, Ref Return Scope Parameters))
+$(H4 $(LNAME2 ref-return-scope-parameters, Ref Return Scope Parameters))
 
         $(P Parameters marked as `ref return scope` come in two forms:)