Improve return ref examples (#3630)

* Improve return ref examples

Make some examples runnable.
Mention @safe needed to check returning address of `return ref`
parameter.
Note -dip1000 is *still* needed to return the address of a `return ref`
parameter.
The example compiler is currently 2.102, so one example can't be made
runnable yet. (The mars function errors with it but pluto always errors
anyway so _FAIL is OK).

* Apply suggestions from code review

Co-authored-by: Dennis <[email protected]>

---------

Co-authored-by: Dennis <[email protected]>

Author: ntrel

spec/function.dd

@@ -1707,21 +1707,22 @@ $(H3 $(LNAME2 return-ref-parameters, Return Ref Parameters))
         returned reference will not outlive the matching argument's lifetime.
         )
 
+$(SPEC_RUNNABLE_EXAMPLE_FAIL
 ---
 ref int identity(return ref int x) {
-  return x; // pass-through function that does nothing
+    return x; // pass-through function that does nothing
 }
 
 ref int fun() {
-  int x;
-  return identity(x); // Error: escaping reference to local variable x
+    int x;
+    return identity(x); // Error: escaping reference to local variable x
 }
 
 ref int gun(return ref int x) {
-  return identity(x); // OK
+    return identity(x); // OK
 }
 ---
-
+)
         $(P Struct non-static methods marked with the `return` attribute ensure the returned
         reference will not outlive the struct instance.
         )
@@ -1740,26 +1741,49 @@ ref int escape()
 }
 ---
 
-        $(P Returning the address of a `ref` variable is also checked.)
+        $(P Returning the address of a `ref` variable is also checked in `@safe` code.)
 
+$(SPEC_RUNNABLE_EXAMPLE_FAIL
 ---
-int* pluto(ref int i)
+int* pluto(ref int i) @safe
 {
     return &i; // error: returning &i escapes a reference to parameter i
 }
 
-int* mars(return ref int i)
+int* mars(return ref int i) @safe
 {
-    return &i;  // ok
+    return &i;  // OK with -preview=dip1000
 }
 ---
+)
 
-$(P If the function returns `void`, and the first parameter is `ref` or `out`, then
+$(P If a function returns `void`, and the first parameter is `ref` or `out`, then
 all subsequent `return ref` parameters are considered as being assigned to
 the first parameter for lifetime checking.
 The `this` reference parameter to a struct non-static member function is
 considered the first parameter.)
 
+---
+struct S
+{
+    private int* p;
+
+    void f(return ref int i) scope @safe
+    {
+        p = &i;
+    }
+}
+
+void main() @safe
+{
+    int i;
+    S s;
+    s.f(i); // OK with -preview=dip1000, lifetime of `s` is shorter than `i`
+    *s.p = 2;
+    assert(i == 2);
+}
+---
+
 $(P If there are multiple `return ref` parameters, the lifetime of the return
 value is the smallest lifetime of the corresponding arguments.)
 
@@ -1778,7 +1802,10 @@ int mercury(return ref int i)
 $(P Template functions, auto functions, nested functions and $(DDSUBLINK spec/expression, function_literals, lambdas)
  can deduce the `return` attribute.)
 
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
 ---
+@safe:
+
 ref int templateFunction()(ref int i)
 {
     return i; // ok
@@ -1795,17 +1822,14 @@ void uranus()
     {
         return i; // ok
     }
-}
-
-void venus()
-{
     auto lambdaFunction =
         (ref int i)
         {
             return &i; // ok
         };
 }
 ---
+)
 
 $(H3 $(LNAME2 scope-parameters, Scope Parameters))