[LangRef] State that a nocapture pointer cannot be returned

[aqjune]

Summary

This is a small patch stating that a nocapture pointer cannot be returned.

Discussed in D93189.

[jdoerfert]

Should we add the, "if broken -> UB!" clause while we are here?

[aqjune]

In D94386#2490154, @jdoerfert wrote:

Should we add the, "if broken -> UB!" clause while we are here?

That's a good point, but I think there are a few candidate semantics and I'm not sure which one is the best.
It can be (1) UB, or (2) the stored pointer magically turns into poison when it returns. Also, it isn't certain when the program should raise UB (during the execution of the callee, or when the callee finally returns).
Diving into this issue more, it can be indirectly captured using ptr-int casts:

if (p == 0x100) {
  escape ((i8*)0x100);
}

So, TBH, I'd like to make this patch just a simple step clarifying that nocapture pointer cannot be returned. :/ Making a further step might require as much discussion as lifetime/nonnull.
(BTW, for the lifetime patch, I'm still interested in making further progress; I'm busy until the end of Jan, I'll restart working on it after the busy thing is done.)

[jdoerfert]

This spells out uncontroversial effective semantics, so LGTM.

[aqjune]

Thank you!

llvm/docs/LangRef.rst

``noalias``
     attribute on return values are stronger than the semantics of the attribute
     when used on function arguments. On function return values, the ``noalias``
     attribute indicates that the function acts like a system memory allocation
     function, returning a pointer to allocated storage disjoint from the
     storage for any other object accessible to the caller.
 
 ``nocapture``
     This indicates that the callee does not make any copies of the
-    pointer that outlive the callee itself. This is not a valid
+    pointer that outlive the callee itself in any form such as a pointer stored
+    in the memory or as a return value. This is not a valid
     attribute for return values.  Addresses used in volatile operations
     are considered to be captured.
 
 ``nofree``
     This indicates that callee does not free the pointer argument. This is not
     a valid attribute for return values.
 
 .. _nest: