<div dir="ltr"><div>Sure, this sounds good.</div><div><br></div><div>I'm kind of toying with the idea of having the full text documentation be a valid .rst file containing some easy to parse directives, which tablegen then substitutes into. We already need a placeholder .rst file, so we might as well keep the full text docs there.</div>
<div><br></div><div>It's an idle thought, though, since I'm not running off to implement this. Let's go with what we have and get some real docs.</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">
On Tue, Feb 11, 2014 at 12:33 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">
Since Reid expressed a bit of concern which I believe to be resolved,<br>
I figured I'd pass the latest incarnation of the patch around just to<br>
make sure.<br>
<br>
This patch splits the documentation out into AttrDocs.td (which should<br>
address some concerns Jordan had about chopping up Attr.td). It also<br>
adds some documentation to the internals reference so that authors<br>
know they have to add documentation and how it works.<br>
<span class="HOEnZb"><font color="#888888"><br>
~Aaron<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
On Mon, Feb 10, 2014 at 2:38 PM, Sean Silva <<a href="mailto:silvas@purdue.edu">silvas@purdue.edu</a>> wrote:<br>
><br>
><br>
><br>
> On Mon, Feb 10, 2014 at 2:21 PM, Reid Kleckner <<a href="mailto:rnk@google.com">rnk@google.com</a>> wrote:<br>
>><br>
>> I'm conflicted about this. The less time I spend editing .td files, the<br>
>> happier I am. Vim has reasonable support for highlighting and editting rst<br>
>> out of the box, and I'd rather edit full text in that directly.<br>
><br>
><br>
> As a vim user, I don't remember vim doing anything special for rst files. Or<br>
> are you just talking about syntax highlighting? If you want it's not too<br>
> difficult to tweak the TableGen syntax file to delegate the interior of<br>
> "code fragments" (aka multiline string literals) to the rst syntax<br>
> highlighter (which would be fine to do globally if you don't work with the<br>
> backend stuff that has C++ inside those fragments).<br>
><br>
>><br>
>><br>
>> We're pretty good at keeping LLVM's LangRef.rst up to date through code<br>
>> review. Could we use the same approach with something in<br>
>> docs/AttributesReference.rst, or do people think it would quickly become<br>
>> stale?<br>
><br>
><br>
> This is because we have a culture of maintaining LangRef ("everybody knows<br>
> that changes to the IR require changes to LangRef"). The same cannot be said<br>
> about attributes, and while it would be nice to develop such a culture for<br>
> attributes, realistically I don't expect it to happen.<br>
><br>
> Also, LangRef.rst is bound to get split up one of these days to make it more<br>
> modular, with a tiny bit of Sphinx plugin to piece it together nicely[*]<br>
> (e.g. one rst file per instruction; this is inspired by how CMake documents<br>
> its commands which is really clean and neat). Currently LangRef is bursting<br>
> at its seams and the "pile everything into one huge file" approach is<br>
> already making it really difficult to organize and navigate. I would not<br>
> like to start down that path with new stuff.<br>
><br>
> [*] This is essentially what Aaron's patch is doing, albeit in TableGen and<br>
> deriving the stuff from a nicely modular (semantic, machine-readable)<br>
> description in the .td file.<br>
><br>
> -- Sean Silva<br>
><br>
>><br>
>><br>
>><br>
>> On Tue, Feb 4, 2014 at 1:38 PM, Aaron Ballman <<a href="mailto:aaron@aaronballman.com">aaron@aaronballman.com</a>><br>
>> wrote:<br>
>>><br>
>>> 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>
>>><br>
>>> ~Aaron<br>
>>><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>
>><br>
>><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>
><br>
</div></div></blockquote></div><br></div>