[clang] [clang] Improve the documentation for the init_priority attribute (PR #123098)

[Louis Dionne via cfe-commits]

https://github.com/ldionne updated https://github.com/llvm/llvm-project/pull/123098

>From 05bb2f8554e7dab1e084738155348389284bcc36 Mon Sep 17 00:00:00 2001
From: Louis Dionne <ldionne.2 at gmail.com>
Date: Wed, 15 Jan 2025 13:03:04 -0500
Subject: [PATCH 1/2] [clang] Improve the documentation for the init_priority
 attribute

The documentation wasn't very clear about whether ordering is controlled
within or across TUs, and same for dylibs. Clarify that, and also add
mentions for the state of support on Mach-O platforms.
---
 clang/include/clang/Basic/AttrDocs.td | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 5e66e752512d0d..4edad37ba3a8ee 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/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.
   }];
 }
 

>From 095b618c069eb14c4ead8684513897927f0e1c9e Mon Sep 17 00:00:00 2001
From: Louis Dionne <ldionne.2 at gmail.com>
Date: Thu, 16 Jan 2025 17:19:46 -0500
Subject: [PATCH 2/2] Review comments

---
 clang/include/clang/Basic/AttrDocs.td | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 4edad37ba3a8ee..56a817892bbbaa 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -121,12 +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++, 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:
+initialization of objects declared at namespace scope in C++ within a single
+linked image on supported platforms. 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++
 
@@ -144,11 +144,11 @@ 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.
 
+On MachO platforms, this attribute also does not control the order of initialization
+across translation units, where it only affects the order within a single TU.
+
 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.
   }];
 }