Attribute documentation

[Sean Silva]

This is really great.

Some more comments inline.

On Tue, Feb 4, 2014 at 4: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).


While I think your current approach is the simplest, Sphinx has a powerful
plugin system (that can run arbitrary Python) which could e.g. check for
the file and do something smart if it's not there (however, locating the
build directory for clang-tblgen is a pain which is why this would be way
more complicated than your current approach).


> 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.
>

SGTM. It would be great if down the road we could do something similar for
commandline options.

btw, cute use of the tblgen "code" token as a multiline string literal :)
(updated tblgen docs in r201033-r201035 to mention this)

-- Sean Silva


>
> ~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/20140208/0f5a48eb/attachment.html>