[clang] [docs] alias attribute doc (PR #193652)

[Aaron Ballman via cfe-commits]

================
@@ -9983,3 +9983,37 @@ different languages to coexist on the same call stack while each interpreting
 exceptions according to their own rules.
   }];
 }
+
+def AliasDocs : Documentation {
+  let Category = DocCatFunction;
+  let Content = [{
+The ``alias`` attribute causes the declaration to be emitted as an alias to
+another symbol, which must be defined in the same translation unit.
+
+The attribute can be applied to both functions and global variables. The 
+attribute must be placed on a declaration, as opposed to a definition.
+
+.. code-block:: c
+
+  void __impl(void) { /* ... */ }
+  void foo(void) __attribute__((alias("__impl")));
+
+In this example, ``foo`` becomes an alias for ``__impl``. 
+
+Note that the aliasee is specified as a string representing the name of the 
+symbol as it appears in the object file. If the symbols are subject to 
+name mangling (as in C++), the aliasee string must match the mangled name. 
+If the aliasee is not found, Clang will emit a diagnostic suggesting the 
+correct mangled name to use.
+
+Clang enforces compatibility between the alias and its target: it emits an 
+error if a function alias points to a variable (or vice versa), and issues 
+a warning if a function alias points to a function with a different 
+signature. For variables, while Clang allows aliasing ABI-compatible types 
+(such as an ``enum`` and its underlying integer type), the alias and the 
----------------
AaronBallman wrote:

CC @efriedma-quic @asl as to whether we want to commit to this as a documented behavior or not. 

GCC confirmed there's a bug here on their end (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=125015) but they've not said whether they plan to support this kind of compatibility or not. If we have an opinion strong enough to document, we should let them know on the issue so hopefully they resolve the same way.

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