r240296 - Document the nullability attributes.

[Sean Silva]

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

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.

-- 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
> >
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20150622/27a1e18a/attachment.html>