r240296 - Document the nullability attributes.

[Aaron Ballman]

On Mon, Jun 22, 2015 at 7:51 PM, Sean Silva <chisophugis at gmail.com> wrote:
>
>
> On Mon, Jun 22, 2015 at 3:44 PM, Aaron Ballman <aaron at aaronballman.com>
> wrote:
>>
>> On Mon, Jun 22, 2015 at 5:27 PM, Sean Silva <chisophugis at gmail.com> wrote:
>> >
>> >
>> > On Mon, Jun 22, 2015 at 11:18 AM, Aaron Ballman <aaron at aaronballman.com>
>> > wrote:
>> >>
>> >> On Mon, Jun 22, 2015 at 1:59 PM, Douglas Gregor <dgregor at apple.com>
>> >> wrote:
>> >> >
>> >> >> On Jun 22, 2015, at 10:31 AM, Aaron Ballman <aaron at aaronballman.com>
>> >> >> wrote:
>> >> >>
>> >> >> On Mon, Jun 22, 2015 at 1:06 PM, Douglas Gregor <dgregor at apple.com>
>> >> >> wrote:
>> >> >>> Author: dgregor
>> >> >>> Date: Mon Jun 22 12:06:56 2015
>> >> >>> New Revision: 240296
>> >> >>>
>> >> >>> URL: http://llvm.org/viewvc/llvm-project?rev=240296&view=rev
>> >> >>> Log:
>> >> >>> Document the nullability attributes.
>> >> >>
>> >> >> Thank you!
>> >> >>
>> >> >>>
>> >> >>> Modified:
>> >> >>>    cfe/trunk/docs/AttributeReference.rst
>> >> >>>    cfe/trunk/include/clang/Basic/Attr.td
>> >> >>>    cfe/trunk/include/clang/Basic/AttrDocs.td
>> >> >>>
>> >> >>> Modified: cfe/trunk/docs/AttributeReference.rst
>> >> >>
>> >> >> Please do not commit changes to AttributeReference.rst directly.
>> >> >> This
>> >> >> file is automatically generated on the server (daily) from
>> >> >> AttrDocs.td. It exists because we need it for folks who want to
>> >> >> generate documentation locally.
>> >> >>
>> >> >> I think it's time to change the contents of this file to be nothing
>> >> >> but a comment saying, "Please do not commit changes to this file",
>> >> >> but
>> >> >> the downside is that will kill off AttributeReference.html on the
>> >> >> live
>> >> >> site until the server generates the new documentation. I am starting
>> >> >> to suspect that pain may be worth it, and I might do this task later
>> >> >> tonight.
>> >> >
>> >> > Neither of these workflows are intuitive for the developer.
>> >>
>> >> Strongly agreed.
>> >>
>> >> > Why aren’t we building AttributeReference.rst into the build
>> >> > directory
>> >> > as part of the documentation build, as one would expect?
>> >>
>> >> It wasn't that this wasn't desirable, it was because it was hard
>> >> (especially for the server side of things, IIRC).
>> >
>> >
>> > It is useful to keep the documentation build independent from the "code"
>> > build. Assuming clang-tblgen to always be present would lose this
>> > property.
>>
>> Good point.
>>
>> >> Going from memory (this was discussed on the lists when we did this
>> >> work initially though): that turned out to be prohibitively difficult
>> >> to accomplish. clang-tblgen lives in the build folder, but the
>> >> documentation does not (it lives in the source folder which we don't
>> >> usually want to write changes back into), and the build folder for the
>> >> documentation is not the same as the build folder for where
>> >> clang-tblgen lives.
>> >
>> >
>> > It should be when the documentation is being built through the CMake
>> > build.
>>
>> I don't think the server-side process that generates the attribute
>> documentation currently uses CMake, but Tanya would be able to speak
>> to that better than I.
>>
>> >> I think the ultimate idea was that we'd need to
>> >> write a Sphinx plugin to make this work, and now people have more
>> >> dependency issues (and that still needs to solve the "where does
>> >> clang-tblgen live" problem).
>> >
>> >
>> > A Sphinx plugin would allow us to switch over to "TableGen-like"
>> > structure
>> > inside rst file (vs. our current rst inside TableGen). This would avoid
>> > the
>> > need for clang-tblgen to be present when building the docs, but would
>> > require sphinx to be around when building the code. I'm not sure which
>> > is
>> > preferable, but the current scheme doesn't seem much better/worse.
>>
>> Ah, thank you for the information Sean. I knew someone would recall
>> this better than I. The build system parts of this are definitely not
>> my area of expertise. :-)
>>
>> Is there a desire to get rid of the server-side build process and
>> instead replace it with one where the developer is required to update
>> AttrDocs.td, generate the documentation with clang-tblgen (likely
>> through an automated build target) to get the RST file, and then
>> commit AttrDocs.td and AttributeReference.rst when they make a
>> modification to the attribute documentation?
>
>
> That is what we do for clang-format options IIRC (through some scripts in
> clang/docs/tools). It seems to effectively decouple the source build from
> the docs build, while requiring somebody to regenerate the rst from time to
> time (if a developer has forgotten to update it when changing the "source"
> that generates the rst).

My concern with that approach is that it is committing code that's
table generated (which always irks me), and duplicates information
(which worries me for maintenance, as we're currently running into
already). I would strongly prefer to keep the server-side build
process and not have an AttributeReference.rst that lives locally
unless the user wants to generate documentation manually. The
server-side process would be one such user. However, I am uncertain of
how to achieve such an ideal.

> Actually, what would be almost ideal is a bot that watches changes to the
> TableGen files, and commits an upated rst file automatically. But that's a
> bit beyond my expectations for our current infrastructure.

I think that's pretty close to the ideal I was thinking, except for
the commit of the RST part. I think the only three things this process
would have to watch are: changes to clang-tblgen itself, and changes
to AttrDocs.td or Attr.td.

~Aaron

>
> -- Sean Silva
>
>>
>>
>> ~Aaron
>>
>> >
>> > -- Sean Silva
>> >
>> >>
>> >>
>> >> > Having to manually call clang-tblgen to update
>> >> > AttributeReference.rst,
>> >> > then separately build the docs with Sphinx, then avoid committing the
>> >> > changes… makes improving documentation harder than it should be.
>> >>
>> >> The thought was that you didn't need to run clang-tblgen and build the
>> >> docs manually in the first place (because RST is supposed to be
>> >> trivial). That being said, I like the idea of making things testable
>> >> locally and would prefer if we could do that. If you (or anyone) has
>> >> ideas on how to improve this, patches are very much welcome.
>> >>
>> >> ~Aaron
>> >>
>> >> >
>> >> >         - Doug
>> >> >
>> >>
>> >> _______________________________________________
>> >> cfe-commits mailing list
>> >> cfe-commits at cs.uiuc.edu
>> >> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>> >
>> >
>
>