[clang] aligned attribute doc (PR #195278)

[Kartik Ohlan via cfe-commits]

https://github.com/Ko496-glitch updated https://github.com/llvm/llvm-project/pull/195278

>From 0c1c9d7717fbb84a1b70c84e739a18c4832eb727 Mon Sep 17 00:00:00 2001
From: Kartik Ohlan <kartik7ohlan at gmail.com>
Date: Fri, 1 May 2026 11:29:06 -0400
Subject: [PATCH 1/2] Added aligned attribute doc

---
 clang/include/clang/Basic/Attr.td     |  2 +-
 clang/include/clang/Basic/AttrDocs.td | 37 +++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/clang/include/clang/Basic/Attr.td b/clang/include/clang/Basic/Attr.td
index 97536ac7a1966..7eee75d5c6d78 100644
--- a/clang/include/clang/Basic/Attr.td
+++ b/clang/include/clang/Basic/Attr.td
@@ -898,7 +898,7 @@ def Aligned : InheritableAttr {
                                           CustomKeyword<"_Alignas">]>,
                    Accessor<"isDeclspec",[Declspec<"align">]>];
   let comparisonFn = "areAlignedAttrsEqual";
-  let Documentation = [Undocumented];
+  let Documentation = [AlignedDocs];
 }
 
 def AlignValue : Attr {
diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index c956ac426daa4..29345a1ee2ed8 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -9983,3 +9983,40 @@ different languages to coexist on the same call stack while each interpreting
 exceptions according to their own rules.
   }];
 }
+
+def AlignedDocs : Documentation {
+  let Category = DocCatDecl;
+  let Heading = "aligned";
+  let Content = [{
+The ``aligned`` attribute specifies a minimum alignment (in bytes) for a 
+variable, structure field, or type definition. The attribute takes an 
+optional integer constant expression that must evaluate to a power of two.
+
+.. code-block:: c++
+
+  struct __attribute__((aligned(8))) S { 
+    short f[3]; 
+  };
+
+If the alignment factor is omitted, the compiler defaults to the largest 
+alignment supported by the target machine for any data type. 
+
+Applying this attribute to a structure or union changes the type's layout 
+properties. To ensure that array indexing and pointer arithmetic remain 
+consistent, the compiler automatically increases the structure's total size 
+(via tail padding) to a multiple of the alignment value. For example, a 
+struct with a natural size of 6 bytes marked ``aligned(8)`` will be 
+padded to 8 bytes.
+
+The attribute is additive and can only increase alignment; it cannot decrease 
+alignment below the type's natural requirement. To force a smaller 
+alignment, ``__attribute__((packed))`` must be used instead. 
+
+Furthermore, the attribute is incompatible with entities that do not 
+possess a stable, addressable memory location. It cannot be applied to 
+bit-fields, function parameters, or variables declared with the 
+``register`` storage class. The effectiveness of the attribute may also be 
+limited by the target's object file format and linker, which often impose 
+a maximum supported alignment boundary.
+  }];
+}

>From 414fb07c0eeaf55ac54ad9ae5b6c121f98f00102 Mon Sep 17 00:00:00 2001
From: Kartik Ohlan <kartik7ohlan at gmail.com>
Date: Sat, 2 May 2026 13:15:27 -0400
Subject: [PATCH 2/2] Added some fixes

---
 clang/include/clang/Basic/AttrDocs.td | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index 29345a1ee2ed8..70adf5c3d9a78 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -9990,7 +9990,9 @@ def AlignedDocs : Documentation {
   let Content = [{
 The ``aligned`` attribute specifies a minimum alignment (in bytes) for a 
 variable, structure field, or type definition. The attribute takes an 
-optional integer constant expression that must evaluate to a power of two.
+optional non-negative integral constant expression. If the value is a 
+power of two, the compiler ensures the declaration is aligned to at least 
+that boundary; a value of zero has no effect.
 
 .. code-block:: c++
 
@@ -9998,7 +10000,7 @@ optional integer constant expression that must evaluate to a power of two.
     short f[3]; 
   };
 
-If the alignment factor is omitted, the compiler defaults to the largest 
+If the alignment factor is omitted, the compiler defaults to the largest(the most strict) 
 alignment supported by the target machine for any data type. 
 
 Applying this attribute to a structure or union changes the type's layout 
@@ -10008,9 +10010,13 @@ consistent, the compiler automatically increases the structure's total size
 struct with a natural size of 6 bytes marked ``aligned(8)`` will be 
 padded to 8 bytes.
 
-The attribute is additive and can only increase alignment; it cannot decrease 
-alignment below the type's natural requirement. To force a smaller 
-alignment, ``__attribute__((packed))`` must be used instead. 
+The attribute is additive and follows a "strictest-wins" rule: if multiple 
+alignment specifications are applied to the same declaration—whether 
+through a mix of ``alignas`` and ``aligned`` or multiple ``aligned`` 
+attributes—the largest alignment requirement is honored. While the 
+attribute cannot decrease alignment below a type's natural requirement 
+on its own, it can be used to increase the alignment of a type that has 
+been reduced via ``__attribute__((packed))``.
 
 Furthermore, the attribute is incompatible with entities that do not 
 possess a stable, addressable memory location. It cannot be applied to