Attribute documentation

Aaron Ballman aaron at aaronballman.com
Tue Feb 11 12:33:25 PST 2014


Since Reid expressed a bit of concern which I believe to be resolved,
I figured I'd pass the latest incarnation of the patch around just to
make sure.

This patch splits the documentation out into AttrDocs.td (which should
address some concerns Jordan had about chopping up Attr.td). It also
adds some documentation to the internals reference so that authors
know they have to add documentation and how it works.

~Aaron

On Mon, Feb 10, 2014 at 2:38 PM, Sean Silva <silvas at purdue.edu> wrote:
>
>
>
> On Mon, Feb 10, 2014 at 2:21 PM, Reid Kleckner <rnk at google.com> wrote:
>>
>> 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.
>
>
> As a vim user, I don't remember vim doing anything special for rst files. Or
> are you just talking about syntax highlighting? If you want it's not too
> difficult to tweak the TableGen syntax file to delegate the interior of
> "code fragments" (aka multiline string literals) to the rst syntax
> highlighter (which would be fine to do globally if you don't work with the
> backend stuff that has C++ inside those fragments).
>
>>
>>
>> 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?
>
>
> This is because we have a culture of maintaining LangRef ("everybody knows
> that changes to the IR require changes to LangRef"). The same cannot be said
> about attributes, and while it would be nice to develop such a culture for
> attributes, realistically I don't expect it to happen.
>
> Also, LangRef.rst is bound to get split up one of these days to make it more
> modular, with a tiny bit of Sphinx plugin to piece it together nicely[*]
> (e.g. one rst file per instruction; this is inspired by how CMake documents
> its commands which is really clean and neat). Currently LangRef is bursting
> at its seams and the "pile everything into one huge file" approach is
> already making it really difficult to organize and navigate. I would not
> like to start down that path with new stuff.
>
> [*] This is essentially what Aaron's patch is doing, albeit in TableGen and
> deriving the stuff from a nicely modular (semantic, machine-readable)
> description in the .td file.
>
> -- Sean Silva
>
>>
>>
>>
>> On Tue, Feb 4, 2014 at 1:38 PM, Aaron Ballman <aaron at aaronballman.com>
>> 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
>>> cfe-commits at cs.uiuc.edu
>>> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>>>
>>
>>
>> _______________________________________________
>> cfe-commits mailing list
>> cfe-commits at cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>>
>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: AttrDocs.patch
Type: application/octet-stream
Size: 55359 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20140211/f2afcb79/attachment.obj>


More information about the cfe-commits mailing list