[spec] Improve Function Return Values section (#4296)

* [spec] Improve Function Return Values section

One `return` is required *per execution path*.
Don't mention `assert(0)` as that is covered by the `noreturn` case.
Clarify return value being an rvalue.

* Add missing return example

* Do list `assert(0)`

It's implementation defined whether it's recognized with type noreturn.

Author: ntrel

spec/function.dd

@@ -395,23 +395,53 @@ $(GNAME OutStatement):
 
 $(H2 $(LNAME2 function-return-values, Function Return Values))
 
-        $(P At least one $(DDSUBLINK spec/statement, return-statement, return statement)
-        is required if the function specifies a return type that is not void,
+        $(P One $(DDSUBLINK spec/statement, return-statement, return statement) per execution path
+        is required if the function specifies a return type that is not `void`,
         unless:)
         $(UL
-        $(LI the function executes an infinite loop)
-        $(LI the function executes an $(DDSUBLINK spec/expression, assert-ct,
-            `assert(0)` statement))
-        $(LI the function evaluates an expression of type
+        $(LI the path executes an infinite loop)
+        $(LI the path evaluates an $(DDSUBLINK spec/expression, assert-ct,
+            `assert(0)` expression))
+        $(LI the path evaluates an expression of type
             $(DDSUBLINK spec/type, noreturn, `noreturn`))
-        $(LI the function contains inline assembler code)
+        $(LI the path contains inline assembler code)
         )
 
+        $(P Simple forms of the first 3 cases above can be recognized by the compiler,
+        but not all.)
+
+$(SPEC_RUNNABLE_EXAMPLE_FAIL
+---
+int error(int i)
+{
+    if (i & 1)
+        i++;
+    else
+        return i;
+
+    // Error: no return statement
+}
+---
+)
+
+$(SPEC_RUNNABLE_EXAMPLE_COMPILE
+---
+int f(int i)
+{
+    if (i >= 0)
+        return i;
+
+    assert(0);
+    // OK, no return needed
+}
+---
+)
         $(P Function return values not marked as $(RELATIVE_LINK2 ref-functions, `ref`)
-        are considered to be rvalues.
+        are considered to be rvalues by the calling function.
         This means they cannot be passed by reference to other functions.
         )
 
+
 $(H2 $(LNAME2 pure-functions, Pure Functions))
 
         $(P Pure functions are annotated with the `pure` attribute.