This is really great. Some more comments inline.
On Tue, Feb 4, 2014 at 4:38 PM, Aaron Ballman <[email protected]>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 > [email protected] > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits > >
_______________________________________________ cfe-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
