r240296 - Document the nullability attributes.

[Aaron Ballman]

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).

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. 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).

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