Attribute documentation

[Reid Kleckner]

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
> >>
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20140212/793f4c2e/attachment.html>