Attribute documentation

[Reid Kleckner]

I'm conflicted about this.  The less time I spend editing .td files, the
happier I am.  Vim has reasonable support for highlighting and editting rst
out of the box, and I'd rather edit full text in that directly.

We're pretty good at keeping LLVM's LangRef.rst up to date through code
review.  Could we use the same approach with something in
docs/AttributesReference.rst, or do people think it would quickly become
stale?


On Tue, Feb 4, 2014 at 1:38 PM, 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20140210/ef2c4f94/attachment.html>