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 <[email protected]> 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 <[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). 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 >> [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
