Attribute documentation

[Aaron Ballman]

This was committed in r201515, but should obviously be considered a
WIP while we get more documentation going. I'll start reaching out to
some attribute authors to hopefully aid in this process.

Thanks!

~Aaron

On Wed, Feb 12, 2014 at 6:34 PM, Reid Kleckner <rnk at google.com> wrote:
> Sure, this sounds good.
>
> 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.
>
> 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.
>
>
> On Tue, Feb 11, 2014 at 12:33 PM, Aaron Ballman <aaron at aaronballman.com>
> wrote:
>>
>> 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
>> >>
>> >
>
>