Documenting our attributes

I’ve noticed that we have 107 undocumented attributes (including synonymous attributes). This makes it very difficult to work out—from a Clang user perspective—whether or not they’re desirable, or why they’re useful.

From what I can tell, a lot of the attributes that aren’t documented are documented by other vendors (e.g. GCC), but we should be documenting what we support (as we support it). There are two reasons for this:

  1. it means that our implementation won’t go out of sync with the only searchable documentation
  2. users won’t need to scour the web for an explanation with lower confidence, because it will be on our website.

If we intentionally defer to external documentation, then we should say something along the lines of

This attribute will always mean the same thing across GCC and Clang: please see the `GCC documentation <link>`_ for more.

That will—at the very least—give users a starting point.