[Attrs] Elaborate on the trivial_abi documentation

[rnk]

Summary

My team recently answered some questions about the trivial_abi
attribute. This change attempts to distill those answers into
user-focused documentation. The previous documentation is somewhat
technical, and the new documentation tries to focus on documenting when
the attribute is safe to use, and what impact the user should expect to
see from the attribute.

[• Quuxplusone]

LgenerallyGTM!

• I would say "special member functions" instead of "methods"
• instead of "passed indirectly by address", consider saying "passed by hidden reference" — is this something people will get, or is it a me-ism? :) There are lots of Google hits for "by hidden reference," including apparently some ABI docs.
• "mark [...] as safe to copy as part of a function call" — Here you want a phrase that indicates "copy the bits, but don't 'copy' in the C++ sense of calling the copy constructor." One technically correct option would be to say "trivially relocate" (you mean "relocate" not "copy", and it's going to be trivial because you're just copying the bits). Alternatively, maybe say something more verbose about how the object will be seen to "jump" from one address to another with no intervening ctor or dtor calls — and this "jump" will happen precisely at the point of the call. The object goes from memory (in the caller's frame), into a register, and then back into memory again (at a new address in the callee's frame). This attribute is safe to use only when such "jumps" are unobservable by (or harmless to) the program. [I know you know this; I just don't think your wording makes it crystal clear to the future reader that this is what you mean.]
• http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1144r5.html#non-trivial-samples contains all the examples of non-trivially-relocatable types I can think of. A big one is libc++ std::list and std::map. You allude to these with the words "Objects that register themselves into a doubly linked list", but I think that requires eagle eyes on the reader's part. "Objects whose address escapes onto the heap ... std::list" probably deserves its own dedicated bullet point, called out separately from "side table of live instances [...] debug iterators."
• Also, objects with vptrs should never be considered trivially relocatable; but that's so arcane that I'm happy not to mention it here.

[rjmccall]

clang/include/clang/Basic/AttrDocs.td

3217

I would change the first sentence here to:

Arguments of `trivial_abi` type are destroyed in the callee, not the caller.

The rest of this paragraph seems to be restating the first sentence in ways that I would expect users to find more confusing than helpful.

You might add something like: "On some platforms, arguments are normally not destroyed until the end of the full expression containing the call; `trivial_abi` arguments will therefore be destroyed earlier than usual, immediately before the called function returns."

3267

This paragraph is redundant with the new paragraph above.

clang/include/clang/Basic/AttrDocs.td

 <http://wg21.link/p0936r0>`_, but does not affect whether temporary objects
 have their lifetimes extended.
   }];
 }
 
 def TrivialABIDocs : Documentation {
   let Category = DocCatDecl;
   let Content = [{
-The ``trivial_abi`` attribute can be applied to a C++ class, struct, or union.
-It instructs the compiler to pass and return the type using the C ABI for the
-underlying type when the type would otherwise be considered non-trivial for the
-purpose of calls.
+The ``trivial_abi`` attribute helps the compiler pass some C++ objects more
+efficiently.
+
+Normally, the compiler must pass records (classes, structs, or unions) with
+non-trivial copy constructors or destructors very carefully. When these methods
+are provided, the compiler can no longer freely copy the bytes of the object
+when it is passed by value. As a result, such objects are typically passed
+indirectly by address. This is usually less efficient for small objects such as
+``std::unique_ptr<T>`` and other smart pointers. Smart pointers are often
+passed by value in performance-sensitive code, so this attribute exists to
+allow the user to mark a C++ class, struct, or union as safe to copy as part of
+a function call.
+
+Instances of ``trivial_abi`` classes are always destroyed in the callee, and
+not the caller. The destructor is not called on the storage allocated for the
+object in the caller. This ensures that calls to constructors and destructors
+are balanced, and that this attribute can safely be applied to
+reference-counting smart pointers.
+
+It is not safe to apply the ``trivial_abi`` attribute to classes with
+constructors that capture pointers to the object or its subobjects (fields and
+bases). Most constructors do not capture interior object pointers, so this
+attribute can be safely applied to many value types. Two unsafe common use
+cases to look out for are:
+
+1. "Small" objects: The small string optimization often requires taking the
+   address of an array field and storing it into a pointer field. This is
+   unsafe, as the interior pointer becomes stale when the object is copied into
+   the callee.
+2. Self-registration: Objects that register themselves into a doubly linked
+   list or side table of live instances cannot use ``trivial_abi``. This
+   pattern can be used to implement debug iterators, for example.
+
+The ``trivial_abi`` attribute changes the ABI of all functions that pass or
+return objects of annotated types by value, so it is not safe to apply to types
+passed across stable ABI boundaries.
+
+The ``trivial_abi`` attribute does **not** guarantee that the marked object
+will be passed in registers. It only disables the logic that causes objects
+that are non-trivial for the purpose of calls to be passed indirectly. The
+remaining rules of the platform's calling convention often require that large
+records be passed indirectly. This attribute is most beneficial for
+pointer-sized records such as smart pointers.
+
 A class annotated with ``trivial_abi`` can have non-trivial destructors or
 copy/move constructors without automatically becoming non-trivial for the
 purposes of calls. For example:
 
   .. code-block:: c++
 
     // A is trivial for the purposes of calls because ``trivial_abi`` makes the
     // user-provided special functions trivial.
     struct __attribute__((trivial_abi)) A {
       ~A();
       A(const A &);
       A(A &&);
       int x;
     };
 
     // B's destructor and copy/move constructor are considered trivial for the
     // purpose of calls because A is trivial.
     struct B {
       A a;
     };
 
 If a type is trivial for the purposes of calls, has a non-trivial destructor,
 and is passed as an argument by value, the convention is that the callee will
 destroy the object before returning.
 
 Attribute ``trivial_abi`` has no effect in the following cases:
 
 - The class directly declares a virtual base or virtual methods.
 - Copy constructors and move constructors of the class are all deleted.
 - The class has a base class that is non-trivial for the purposes of calls.
 - The class has a non-static data member whose type is non-trivial for the
   purposes of calls, which includes: