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 <[email protected]> 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 <[email protected]> > 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 <[email protected]> wrote: >> > >> > >> > >> > On Mon, Feb 10, 2014 at 2:21 PM, Reid Kleckner <[email protected]> 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 <[email protected]> >> >> 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 >> >>> [email protected] >> >>> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits >> >>> >> >> >> >> >> >> _______________________________________________ >> >> cfe-commits mailing list >> >> [email protected] >> >> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits >> >> >> > > > _______________________________________________ cfe-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
