[clang] aligned attribute doc (PR #195278)

[via cfe-commits]

llvmorg-github-actions[bot] wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang

Author: Kartik Ohlan (Ko496-glitch)

<details>
<summary>Changes</summary>

This PR document aligned attribute.

---
Full diff: https://github.com/llvm/llvm-project/pull/195278.diff


2 Files Affected:

- (modified) clang/include/clang/Basic/Attr.td (+1-1) 
- (modified) clang/include/clang/Basic/AttrDocs.td (+37) 


``````````diff
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.
+  }];
+}

``````````

</details>


https://github.com/llvm/llvm-project/pull/195278