diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -3197,10 +3197,50 @@
 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: