<div dir="ltr"><div>I'm conflicted about this.  The less time I spend editing .td files, the happier I am.  Vim has reasonable support for highlighting and editting rst out of the box, and I'd rather edit full text in that directly.</div>
<div><br></div><div>We're pretty good at keeping LLVM's LangRef.rst up to date through code review.  Could we use the same approach with something in docs/AttributesReference.rst, or do people think it would quickly become stale?</div>
</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Tue, Feb 4, 2014 at 1: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:0 0 0 .8ex;border-left:1px #ccc 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). 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>
<span class="HOEnZb"><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>