Attribute documentation

Aaron Ballman aaron at aaronballman.com
Mon Feb 10 11:36:24 PST 2014


On Mon, Feb 10, 2014 at 2:34 PM, Reid Kleckner <rnk at google.com> wrote:
> On Mon, Feb 10, 2014 at 11:28 AM, Aaron Ballman <aaron at aaronballman.com>
> wrote:
>>
>> (Removing llvm-admin since this doesn't concern them.)
>>
>> 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.
>> >
>> > 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?
>>
>> We could, but I believe this approach is an improvement. For starters,
>> it's a way that we can *require* attributes to have some documentation
>> which is a drastic improvement over the LangRef.rst approach (at least
>> as far as users are concerned). Also, there are things we can
>> automatically generate for attributes which would require duplicated
>> effort if it was done manually (such as what syntaxes are supported,
>> what subjects the attribute can appertain to, etc). The declarative
>> nature of the attribute tablegen lends itself nicely to this sort of
>> automation.
>>
>> Honestly, I think the benefits are significant enough to warrant this
>> approach.
>
>
> I'm OK with repeating the complete set of attribute names once in the
> documentation, but doing a nice pretty printing of all the spellings seems
> like a nice win that I hadn't thought of.

The other big win, as far as I am concerned, is that you cannot add an
attribute without documenting it in some form or fashion (I suspect
that new attributes getting an Undocumented designator will not pass
review very often).

~Aaron



More information about the cfe-commits mailing list