Re: "Future directions" vs. "TODO" in doc comments (was: [PATCH 01/14] qapi: BlockExportRemoveMode: move comments to TODO)

[John Snow]

On Mon, Mar 28, 2022 at 3:46 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> Victor Toso <victortoso@redhat.com> writes:
>
> > Hi,
> >
> > On Fri, Mar 25, 2022 at 11:11:23AM -0400, John Snow wrote:
> >> On Fri, Mar 25, 2022, 8:33 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> [...]
>
> >> > Doc comments embed user documentation in the source code.  The doc
> >> > generator extracts it.
> >> >
> >> > TODOs are generally for developers.  Should the doc generator suppress
> >> > TODO sections?
> >>
> >> Needs an audit to make sure we're using it consistently with
> >> that semantic, but broadly it's probably a good idea to squelch
> >> "internal" todos, yes.
> >>
> >> Things like "Watch out, were definitely gonna deprecate this
> >> soon probably maybe!" can stay outside of the TODO section.
> >> (Sometimes heads up are legitimate, even if most won't read
> >> them. the faithful and diligent will be rewarded with painless
> >> upgrades.)
>
> This is "future directions", not quite the same as "TODO".
>
> Would a section tag "Future directions" make sense?
>

If we're leaving these kinds of warnings already, sure. I was just
speaking generically.
I didn't actually audit all of our docs to see what types of notes
we've left so far.

> > There are 5 TODO sections in QAPI (including this patch):
>
> Let me try to sort them into "TODO" and "future directions" buckets.
> The former are of interest for developers only, and thus should be
> elided from documentation meant for users.
>

Oh, but it looks like *you* did the audit ;)

> >  qapi/block-export.json:222:# TODO: Potential additional modes to be added 
> > in the future:
>
> Do we believe our thoughts on evolving of this enum are relevant for
> users of the affected QMP commands (nbd-server-remove and
> block-export-del)?
>
> If yes, it's "future directions".
>

Presumably this evolves compatibly like QMP always does, and doesn't
necessarily warrant a special note. "future directions" feels
reasonable.

> >  qapi/introspect.json:300:# TODO: @success-response (currently irrelevant, 
> > because it's QGA, not QMP)
>
> As phrased, this is only useful for developers, and even for them, it's
> rather terse.
>
> If we add introspection to QGA, we'll want to add a @success-response
> member.
>
> So, if we intend to add introspection to QGA, *and* we think current
> users of (QMP-only) introspection need to know about a future addition
> of @success-response, then this should be rephrased as "future
> directions".
>
> I doubt it.
>

I'll defer to your judgment on this one. The last time I tried to bark
into QGA I got more than I bargained for. :')

> >  qapi/machine.json:913:# TODO: Better documentation; currently there is 
> > none.
>
> Clearly TODO.
>

Yuh

> >  qapi/migration.json:933:# TODO either fuse back into MigrationParameters, 
> > or make
>
> Clearly TODO.  Note that this one is *not* in a doc comment, and does
> *not* appear in generated documentation.
>
> Once we have concrete plans on how to address the TODO, these plans may
> motivate "future directions", namely if they involve user-visible change
> users need to know about in advance.
>
> >  qapi/qdev.json:70:# TODO: This command effectively bypasses QAPI 
> > completely due to its
>
> Likewise.
>
> I think this shows that we have a few comments just for developers in
> the middle of user documentation.
>
> We could simply keep these outside doc comments, like the TODO in
> qapi/migration.json.
>
> This can occasionally be awkward.  For instance, TODO @success-response
> is right where @success-response ought to be.  Moving it outside the doc
> comment would lose that.  Not the end of the world, just awkward.
>
> If this annoys us enough, we could provide means to let us have elide
> parts of doc comments from generated docs.  The simplest one is probably
> eliding certain sections, say the TODO sections.
>
> Thoughts?
>

I'm fine with it, maybe pending the spelling of such a section.
Keeping the docs clean and useful on generation sounds like a noble
endeavor. I don't think it's urgent, but I'm willing to let Victor
tell me which pieces are annoying and getting in his way.

(I still want to redo our docstring handling, but it wound up being a
bigger project than I could bite off in a week or two. It's extremely
high on my list of things to do, but I am already in debt to you on
the typing project I wanted to engage on, so ... I will sit on my
hands for right now.)