<div dir="ltr">This is really great.<div><br></div><div>Some more comments inline.<div><div><br></div><div><div><div class="gmail_extra"><div class="gmail_quote">On Tue, Feb 4, 2014 at 4:38 PM, Aaron Ballman <span dir="ltr"><<a href="mailto:aaron@aaronballman.com" target="_blank">aaron@aaronballman.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Attributes in clang are largely declarative. We have Attr.td, and it<br>

specifies what attributes exist, what they appertain to, what<br>
arguments they take, etc. I am proposing to extend this declarative<br>
functionality to cover documentation. That's one thing clang is sorely<br>
lacking when it comes to the attributes we support. This patch<br>
demonstrates the direction I think we should go with attribute<br>
documentation -- put it right in with the rest of the attribute<br>
declarations, and generate the documentation for the website<br>
as-needed.<br>
<br>
This patch adds a new declarative item: Documentation. It lets you<br>
specify content for the attribute's documentation, in RST form, along<br>
with some extra pieces of functionality to make doc generation a bit<br>
nicer (such as categorization, the ability to "deprecate" an<br>
attribute, etc). Currently, most attributes are set to Undocumented.<br>
This should change over time so that the only undocumented attributes<br>
are ones which we truly wish to not document (such as attributes which<br>
have no spelling).<br>
<br>
The workflow for using this functionality is for attribute authors to<br>
simply add their documentation to the attributes they create and<br>
commit as normal. Periodically, a crontab job will be run on a server<br>
which will run the appropriate tablegen command (clang-tblgen<br>
-gen-attr-docs) to create the RST file, and generate the HTML from<br>
that. However, due to the way RST works, there will be a committed<br>
"AttributeReference.rst" file that just holds placeholder data so that<br>
people can locally generate error-free documentation without having to<br>
run clang-tblgen (unless they want to).</blockquote><div><br></div><div>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).</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"> This file will be what is<br>
replaced by the cron job on the server. I will act as the point of<br>
contact for any issues with this process on the server.<br>
<br>
The goal of this early patch is to demonstrate direction and gather<br>
feedback before going further.<br></blockquote><div><br></div><div>SGTM. It would be great if down the road we could do something similar for commandline options.</div><div><br></div><div>btw, cute use of the tblgen "code" token as a multiline string literal :) (updated tblgen docs in r201033-r201035 to mention this)<br>
</div><div><br></div><div>-- Sean Silva</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<span class=""><font color="#888888"><br>
~Aaron<br>
</font></span><br>_______________________________________________<br>
cfe-commits mailing list<br>
<a href="mailto:cfe-commits@cs.uiuc.edu">cfe-commits@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits</a><br>
<br></blockquote></div><br></div></div></div></div></div></div>