[llvm] [llvm] add documentation for public interface annotations (LLVM_ABI, etc) (PR #134710)

[Andrew Rogers via llvm-commits]

================
@@ -0,0 +1,277 @@
+LLVM Interface Export Annotations
+=================================
+
+With the following build settings, LLVM will be built as a shared library with
+hidden default symbol visibility:
+
+::
+
+   LLVM_BUILD_LLVM_DYLIB_VIS=On
+   LLVM_BUILD_LLVM_DYLIB=On
+   LLVM_LINK_LLVM_DYLIB=On
+
+When building LLVM in this configuration, any symbol intended to be visible to
+clients must be explicitly exported.
+
+Exporting a symbol typically requires annotating it with the ``LLVM_ABI`` macro
+defined in `compiler.h
+<https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Support/Compiler.h#L152>`__.
+There are similar annotations that must be used in a few special cases. This
+document describes the common patterns for annotating LLVM symbols for export.
+
+Functions
+---------
+
+Exported function declarations in header files must be annotated with
+``LLVM_ABI``.
+
+.. code:: cpp
+
+   #include "llvm/Support/Compiler.h"
+
+   LLVM_ABI void exported_function(int a, int b);
+
+Global Variables
+----------------
+
+Exported global variables must be annotated with ``LLVM_ABI`` at their
+``extern`` declarations.
+
+.. code:: cpp
+
+   #include "llvm/Support/Compiler.h"
+
+   LLVM_ABI extern int exported_global_variable;
+
+Classes, Structs, and Unions
+----------------------------
+
+Classes, structs, and unions can be annotated with ``LLVM_ABI`` at their
+definition, but this option is generally discouraged. Annotating the entire
+definition exports unnecessary symbols, such as private functions, vtables, and
+type information. Instead, ``LLVM_ABI`` should be applied only to public and
+protected method declarations without a body in the header, including
+constructors and destructors.
----------------
andrurogerz wrote:

Do you have a scenario in mind when someone would want to export an inline function? I was going with the assumption that there isn't a case where this is required.

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