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

[Saleem Abdulrasool 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.
----------------
compnerd wrote:

What if I have an inline definition in the body that should be exported? That is, `__declspec(dllexport) inline int f(void) { return 32; }` is a totally well-defined valid construct (as is the mirror'ed `__declspec(dllimport) inline int f(void) { return 32; }`.

I think that there needs to be more clear text here about the application of the attribute and the reasoning.

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