[RFC 01/12] Add documentation for randstruct attributes

[Connor Kuehl via cfe-commits]

Co-authored-by: Cole Nixon <nixontcole at gmail.com>
Co-authored-by: Connor Kuehl <cipkuehl at gmail.com>
Co-authored-by: James Foster <jafosterja at gmail.com>
Co-authored-by: Jeff Takahashi <jeffrey.takahashi at gmail.com>
Co-authored-by: Jordan Cantrell <jordan.cantrell at mail.com>
Co-authored-by: Nikk Forbus <nicholas.forbus at gmail.com>
Co-authored-by: Tim Pugh <nwtpugh at gmail.com>
---
 clang/include/clang/Basic/AttrDocs.td | 45 +++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index a9835cbeeed..a94e995ac14 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -4116,3 +4116,48 @@ it will be automatically applied to overrides if the method is virtual. The
 attribute can also be written using C++11 syntax: ``[[mig::server_routine]]``.
 }];
 }
+
+def ClangRandstructDocs : Documentation {
+  let Category = DocCatVariable;
+  let Heading = "randomize_layout, no_randomize_layout";
+  let Content = [{
+The attributes ``randomize_layout`` and ``no_randomize_layout`` can be applied
+to a record.
+
+``randomize_layout`` instructs the compiler to randomize the memory layout
+of the member variables of the record.
+
+Conversely, ``no_randomize_layout`` is used to indicate that if using the
+automatic strucuture selection feature of the Randstruct implementation, the
+compiler should not shuffle the members of the record.
+
+In the event that a record is labeled with both attributes, the compiler will
+emit a warning indicating that these two cannot be used on the same record.
+The default behavior in this case is to not randomize the struct, as the
+attribute ``no_randomize_layout`` takes precedence over ``randomize_layout``.
+This is implementation defined behavior.
+
+.. code-block:: c
+
+  // Indicates that this struct should be randomized by Randstruct implementation.
+  struct s {
+    char *a;
+    char *b;
+    char *c;
+  }__attribute__((randomize_layout));
+
+  // Indicates that this struct should NOT be randomized by Randstruct implementation.
+  struct s {
+    char *a;
+    char *b;
+    char *c;
+  }__attribute__((no_randomize_layout));
+
+  // Emits compiler warning. Struct is NOT randomized by Randstruct implementation.
+  struct s {
+    char *a;
+    char *b;
+    char *c;
+  }__attribute__((randomize_layout)) __attribute__((no_randomize_layout));
+}];
+}
-- 
2.17.1