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

[andrurogerz]

Purpose

Add documentation for the existing family of LLVM_ABI annotation macros defined in llvm/Support/Compiler.h. These annotations are used to describe LLVM's public interface.

Background

This documentation is in support of the annotation effort described here.

Validation

Manually inspected rendered ReST document on GitHub.

[andrurogerz]

• @compnerd, @fsfod, @vvassilev

This write-up is based on my exercise of annotating most of the LLVM codebase, and I think it is worth merging it prior to merging more annotations.

[fsfod]

I can list some edge cases that might be worth including in some way:

• Taking address of a imported function is not is a valid constexpr at least for clang on windows. I've seen this happen multiple times in the LLVM and Clang codebase.
• If a class has some existing attributes there can be issues with adding the visibility attribute for some older compilers https://github.com/tstellar/template-visibility/blob/testing/templates.h.
• dllimport\dllexport can't go before other attributes when built with clang-cl example.
• MSVC has ancient unfixed bug where a dllexported class declares two or more static variables on the same line results in a compile error https://developercommunity.visualstudio.com/t/c2487-in-dllexport-class-with-static-members/69878.
• There are some explicit template instantiations that indirectly derive from a STL class like cl::opt<std::string> that can't be exported because you will get missing symbol errors for symbols that should of come from the c++ runtime shared library i think. There might also be some bug with MSVC and cl::opt specializations for primitive types like cl::opt<int> where its not exported from the file with the explicit instantiation definition with it being used in a function.

[andrurogerz]

I can list some edge cases that might be worth including in some way:

Thank you for these, @fsfod! That's valuable info, and I have not yet encountered these problems myself. I will create an addendum at the end of the doc to call-out these edge cases.

[andrurogerz]

Thanks @compnerd, @vgvassilev, and @fsfod for the great feedback on this. I've made additions and improvements based on your input.

I have one more change to make: I will incorporate @fsfod's list of edge cases at the end of the doc after I've tested them out.

[nikic]

Thanks for adding the docs!