r240296 - Document the nullability attributes.

[Aaron Ballman]

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?

~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
>
>