Victor Toso <victort...@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 <arm...@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? [...]
