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

[Markus Armbruster <armbru@redhat.com>]

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?

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

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

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

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

Clearly TODO.

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

[...]