Attribute documentation

[Aaron Ballman]

Attributes in clang are largely declarative. We have Attr.td, and it
specifies what attributes exist, what they appertain to, what
arguments they take, etc. I am proposing to extend this declarative
functionality to cover documentation. That's one thing clang is sorely
lacking when it comes to the attributes we support. This patch
demonstrates the direction I think we should go with attribute
documentation -- put it right in with the rest of the attribute
declarations, and generate the documentation for the website
as-needed.

This patch adds a new declarative item: Documentation. It lets you
specify content for the attribute's documentation, in RST form, along
with some extra pieces of functionality to make doc generation a bit
nicer (such as categorization, the ability to "deprecate" an
attribute, etc). Currently, most attributes are set to Undocumented.
This should change over time so that the only undocumented attributes
are ones which we truly wish to not document (such as attributes which
have no spelling).

The workflow for using this functionality is for attribute authors to
simply add their documentation to the attributes they create and
commit as normal. Periodically, a crontab job will be run on a server
which will run the appropriate tablegen command (clang-tblgen
-gen-attr-docs) to create the RST file, and generate the HTML from
that. However, due to the way RST works, there will be a committed
"AttributeReference.rst" file that just holds placeholder data so that
people can locally generate error-free documentation without having to
run clang-tblgen (unless they want to). This file will be what is
replaced by the cron job on the server. I will act as the point of
contact for any issues with this process on the server.

The goal of this early patch is to demonstrate direction and gather
feedback before going further.

~Aaron
-------------- next part --------------
A non-text attachment was scrubbed...
Name: AttrDocs.patch
Type: application/octet-stream
Size: 53232 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20140204/b5825856/attachment.obj>