[clang] [clang] Add clang::preferred_type attribute for bitfields (PR #69104)

[Aaron Ballman via cfe-commits]

================
@@ -7219,6 +7219,31 @@ its underlying representation to be a WebAssembly ``funcref``.
   }];
 }
 
+def PreferredTypeDocumentation : Documentation {
+  let Category = DocCatField;
+  let Content = [{
+This attribute allows adjusting the type of a bit-field in debug information.
+This can be helpful when a bit-field is intended to store an enumeration value,
+but has to be specified as having the enumeration's underlying type in order to
+facilitate compiler optimizations or bit-field packing behavior. Normally, the
+underlying type is what is emitted in debug information, which can make it hard
+for debuggers to know to map a bit-field's value back to a particular enumeration.
+
+.. code-block:: c++
+
+    enum Colors { Red, Green, Blue };
+
+    struct S {
+      [[clang::preferred_type(Colors)]] unsigned ColorVal : 2;
+      [[clang::preferred_type(bool)]] unsigned UseAlternateColorSpace : 1;
+    } s = { Green, false };
+
+Without the attribute, a debugger is likely to display the value `1` for `ColorVal`
+and `0` for `UseAlternateColorSpace`. With the attribute, the debugger may now
+display `Green` and `false` instead.
+  }];
----------------
AaronBallman wrote:

We should add additional documentation now that we've not limited this to just enumeration types. Maybe something along the lines of:
```

This can be used to map a bit-field to an arbitrary type that isn't integral or an enumeration type. For example:

.. code-block:: c++

    struct A {
      short a1;
      short a2;
    };

    struct B {
      [[clang::preferred_type(A)]] unsigned b1 : 32 = 0x000F'000C;
    };

will associate the type ``A`` with the ``b1`` bit-field and is intended to display something like this in the debugger:

.. code-block:: text

    Process 2755547 stopped
    * thread #1, name = 'test-preferred-', stop reason = step in
        frame #0: 0x0000555555555148 test-preferred-type`main at test.cxx:13:14
       10   int main()
       11   {
       12       B b;
    -> 13       return b.b1;
       14   }
    (lldb) v -T
    (B) b = {
      (A:32) b1 = {
        (short) a1 = 12
        (short) a2 = 15
      }
    }

Note that debuggers may not be able to handle more complex mappings and so this usage is debugger-dependent.
```

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