Attribute documentation

Jordan Rose jordan_rose at apple.com
Fri Feb 7 09:30:59 PST 2014


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
-------------- 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/20140207/898969f6/attachment.obj>
-------------- next part --------------
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits



More information about the cfe-commits mailing list