Attribute documentation

Jordan Rose jordan_rose at apple.com
Mon Feb 10 09:36:47 PST 2014


At some point (now?) we should probably set up diagtool (or similar) to warn about new attributes without documentation, the same way we do new warnings without flags.

Jordan


On Feb 9, 2014, at 20:22 , Aaron Ballman <aaron at aaronballman.com> wrote:

> Since this appears to be non-controversial, I will commit the initial
> implementation soon (one that splits the docs out into a separate .td
> file). I'll do some of the initial documenting, but will reach out to
> attribute authors to see if I can get some assistance with moving this
> forward.
> 
> Until there's a bit more documentation written, I don't think there's
> anything llvm-admin needs to handle. But once we reach some form of
> critical mass, I'll need some help getting the web server side of
> things set up and will reach out at that time.
> 
> Thanks for the feedback!
> 
> ~Aaron
> 
> On Sat, Feb 8, 2014 at 10:00 PM, Sean Silva <silvas at purdue.edu> wrote:
>> This is really great.
>> 
>> Some more comments inline.
>> 
>> On Tue, Feb 4, 2014 at 4: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).
>> 
>> 
>> While I think your current approach is the simplest, Sphinx has a powerful
>> plugin system (that can run arbitrary Python) which could e.g. check for the
>> file and do something smart if it's not there (however, locating the build
>> directory for clang-tblgen is a pain which is why this would be way more
>> complicated than your current approach).
>> 
>>> 
>>> 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.
>> 
>> 
>> SGTM. It would be great if down the road we could do something similar for
>> commandline options.
>> 
>> btw, cute use of the tblgen "code" token as a multiline string literal :)
>> (updated tblgen docs in r201033-r201035 to mention this)
>> 
>> -- Sean Silva
>> 
>>> 
>>> 
>>> ~Aaron
>>> 
>>> _______________________________________________
>>> cfe-commits mailing list
>>> cfe-commits at cs.uiuc.edu
>>> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>>> 
>> 




More information about the cfe-commits mailing list