[llvm-branch-commits] [clang] 🍒[NFC][BoundsSafety] Give `counted_by_or_null`, `sized_by`, and `sized_by_or_null` their own documentation (#212877) (PR #217720)

[Dan Liew via llvm-branch-commits]

================
@@ -9895,13 +9895,79 @@ Example:
 
 def CountedByDocs : Documentation {
   let Category = DocCatField;
-  let Content = [{
-Clang supports the ``counted_by`` attribute on the flexible array member of a
-structure in C. The argument for the attribute is the name of a field member
-holding the count of elements in the flexible array. This information can be
-used to improve the results of the array bound sanitizer and the
-``__builtin_dynamic_object_size`` builtin. The ``count`` field member must be
-within the same non-anonymous, enclosing struct as the flexible array member.
+  let Heading = "counted_by";
+  let Content = [{
+The ``counted_by`` attribute is applied to a pointer or flexible array member to
+indicate that the pointer points to (or the flexible array member contains) at
+least the number of *elements* given by the attribute's argument.
+
+This attribute is used by `-fbounds-safety <BoundsSafety.html>`__ to propagate
+bounds information on API surfaces without any ABI changes. This attribute is
+also used to improve the results of the array bound sanitizer and the
+``__builtin_dynamic_object_size`` builtin.
+
+Because the size of the pointee type must be known to compute the pointer's
+bounds, such a pointer must not be used while its pointee type is incomplete; a
+pointer to a forward-declared type is accepted on fields annotated with
+``counted_by``, but the type must be completed before the pointer is used. If
+the pointee type can never be completed, ``counted_by`` is rejected and
+``sized_by`` should be used instead. ``void *`` is a special case: as a GNU
+extension (diagnosed by ``-Wgnu-pointer-arith``), ``counted_by`` is accepted on
+it, where it behaves like ``sized_by`` (the argument is treated as a byte count,
+``void`` having an assumed size of one byte).
+
----------------
delcypher wrote:

Maybe but this is not the place for this feedback. 
This is a cherry-pick PR. The right place would've been https://github.com/llvm/llvm-project/pull/212877 where this change was originally reviewed and approved.

You're welcome to put up a PR against `main` restructuring things if you think it would be useful.

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