fix Issue 13336 - auto ref return deduced to be ref despite return va…

…lue coercion

function.dd

@@ -147,29 +147,43 @@ $(H4 $(LNAME2 auto-functions, Auto Functions))
 
 $(H4 $(LNAME2 auto-ref-functions, Auto Ref Functions))
 
-        $(P Auto ref functions infer their return type just as
+    $(P Auto ref functions infer their return type just as
         $(RELATIVE_LINK2 auto-functions, auto functions) do.
         In addition, they become $(RELATIVE_LINK2 ref-functions, ref functions)
-        if the return expression is an lvalue,
+        if all return expressions are lvalues,
         and it would not be a reference to a local or a parameter.
-        )
 
----
-auto ref foo(int x)     { return x; }  // value return
-auto ref foo()          { return 3; }  // value return
-auto ref foo(ref int x) { return x; }  // ref return
-auto ref foo(out int x) { return x; }  // ref return
-auto ref foo() { static int x; return x; }  // ref return
----
+        ---
+        auto ref foo(int x)     { return x; }  // value return
+        auto ref foo()          { return 3; }  // value return
+        auto ref foo(ref int x) { return x; }  // ref return
+        auto ref foo(out int x) { return x; }  // ref return
+        auto ref foo() { static int x; return x; }  // ref return
+        ---
+    )
 
-        $(P The lexically first $(GLINK2 statement, ReturnStatement)
-        determines the ref-ness of a function:
-        )
+    $(P The ref-ness of a function is determined from all
+        $(GLINK2 statement, ReturnStatement)s in the function body:
 
----
-auto ref foo(ref int x) { return 3; return x; }  // ok, value return
-auto ref foo(ref int x) { return x; return 3; }  // error, ref return, 3 is not an lvalue
----
+        ---
+        auto ref foo(ref int x) { return 3; return x; }  // ok, value return
+        auto ref foo(ref int x) { return x; return 3; }  // ok, value return
+        auto ref foo(ref int x, ref double y)
+        {
+            return x; return y;
+            // The return type is deduced to double, but cast(double)x is not an lvalue,
+            // then become a value return.
+        }
+        ---
+    )
+
+    $(P Auto ref function can have explicit return type.
+
+        ---
+        auto ref int foo(ref int x) { return x; }  // ok, ref return
+        auto ref int foo(double x) { return x; }   // error, cannot convert double to int
+        ---
+    )
 
 
 $(H4 $(LNAME2 inout-functions, Inout Functions))