Update the LangRef description of the 'returned' attribute

[hfinkel]

Summary

The description of the 'returned' attribute says that it is only used when optimizing the function itself, but not the callee. This is already not quite right (at least for the WebAssembly backend: lib/Target/WebAssembly/WebAssemblyOptimizeReturned.cpp), and I'd like to make the optimizer smarter about looking through functions with returned arguments (generally, but motivated by my llvm.noalias work). As David pointed out in the review of D22202, this will require updating the LangRef.

[sunfish]

The referenced WebAssembly optimization is a caller-side optimization, not a callee-side optimization, so it itself isn't actually a motivation for this LangRef change.

Also, it's not clear what the optimization purpose of returned would be in the callee. If some IR producer or transformer knows that one of the argument values is returned, it should just set the return operand(s) to use the argument value, or a bitcast thereof, and let SSA form to describe the property naturally.

[hfinkel]

In D22203#479707, @sunfish wrote:

The referenced WebAssembly optimization is a caller-side optimization, not a callee-side optimization, so it itself isn't actually a motivation for this LangRef change.

Also, it's not clear what the optimization purpose of returned would be in the callee. If some IR producer or transformer knows that one of the argument values is returned, it should just set the return operand(s) to use the argument value, or a bitcast thereof, and let SSA form to describe the property naturally.

Yep. I'm not sure what I was thinking. I think perhaps David meant to generalize the description of the caller-side optimizations. I'll post a different patch.

docs/LangRef.rst

``nest``
     This indicates that the pointer parameter can be excised using the
     :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid
     attribute for return values and can only be applied to one parameter.
 
 ``returned``
     This indicates that the function always returns the argument as its return
     value. This is an optimization hint to the code generator when generating
     the caller, allowing tail call optimization and omission of register saves
-    and restores in some cases; it is not checked or enforced when generating
-    the callee. The parameter and the function return type must be valid
-    operands for the :ref:`bitcast instruction <i_bitcast>`. This is not a
-    valid attribute for return values and can only be applied to one parameter.
+    and restores in some cases; it can also be used when optimizing the callee.
+    The parameter and the function return type must be valid operands for the
+    :ref:`bitcast instruction <i_bitcast>`. This is not a valid attribute for
+    return values and can only be applied to one parameter.
 
 ``nonnull``
     This indicates that the parameter or return pointer is not null. This
     attribute may only be applied to pointer typed parameters. This is not
     checked or enforced by LLVM, the caller must ensure that the pointer
     passed in is non-null, or the callee must ensure that the returned pointer
     is non-null.