Attribute documentation

[Aaron Ballman]

Thank you for the feedback! :-) I was contemplating finding a way to
make the td file a bit less choppy. One alternate solution is to have
a new file named AttrDocs.td that gets #included into Attr.td. Since
the Documentation member is required (you'll get a sensible error if
you leave it out), it shouldn't be too onerous of an approach. I think
it may be a nicer approach from a separation of concerns perspective
as well.

~Aaron

On Fri, Feb 7, 2014 at 12:30 PM, Jordan Rose <jordan_rose at apple.com> wrote:
> I don't have any specific comments, but I definitely approve of this direction. Even if it makes the .td file look choppy. :-)
>
> Jordan
>
>
> On Feb 4, 2014, at 13:38 , Aaron Ballman <aaron at aaronballman.com> wrote:
>
>> 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
>
>> _______________________________________________
>> cfe-commits mailing list
>> cfe-commits at cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>
>