[clang] Improve the documentation for the init_priority attribute

clang/include/clang/Basic/AttrDocs.td

@@ -121,11 +121,12 @@ def InitPriorityDocs : Documentation {
 In C++, the order in which global variables are initialized across translation
 units is unspecified, unlike the ordering within a single translation unit. The
 ``init_priority`` attribute allows you to specify a relative ordering for the
-initialization of objects declared at namespace scope in C++. The priority is
-given as an integer constant expression between 101 and 65535 (inclusive).
-Priorities outside of that range are reserved for use by the implementation. A
-lower value indicates a higher priority of initialization. Note that only the
-relative ordering of values is important. For example:
+initialization of objects declared at namespace scope in C++, even between translation
+units (but within a single final linked image). The priority is given as an integer
+constant expression between 101 and 65535 (inclusive). Priorities outside of that
+range are reserved for use by the implementation. A lower value indicates a higher
+priority of initialization. Note that only the relative ordering of values is
+important. For example:
 
 .. code-block:: c++
 
@@ -136,12 +137,18 @@ relative ordering of values is important. For example:
 ``Obj2`` will be initialized *before* ``Obj1`` despite the usual order of
 initialization being the opposite.
 
+Note that this attribute does not control the initialization order of objects
+across final linked image boundaries like shared objects and executables.
+
 On Windows, ``init_seg(compiler)`` is represented with a priority of 200 and
 ``init_seg(library)`` is represented with a priority of 400. ``init_seg(user)``
 uses the default 65535 priority.
 
 This attribute is only supported for C++ and Objective-C++ and is ignored in
 other language modes. Currently, this attribute is not implemented on z/OS.
+This attribute also does not control the order of initialization across
+translation units on Mach-O platforms, where it only affects the order within
+a single TU.
   }];
 }