Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]

[Kashyap Chamarthy <kchamart@redhat.com>]

On Fri, Jan 31, 2020 at 07:11:15AM +0100, Markus Armbruster wrote:
> Kashyap Chamarthy <kchamart@redhat.com> writes:

[...]

> > What can be done to improve QOM documentation (or lack thereof)?
> 
> Are you trying to push us from idle grousing to actually improve things?
> No fair!

I first wrote it as a semi-complaint, and then I caught myself: "you're
not helping"; so I rephrased it to be more constructive. :-)

> > From a couple of hurried `grep` queries in the QEMU tree, there seems to
> > be no explicit qom.rst|txt, or qemu-object-model.txt|rst or some such.
> > (I hope I haven't missed any other files.)
> 
> As far as I know, all we have is the lovingly[*] written comments in
> include/qom/object.h.  Sadly, we've let them rot in places.  In
> particular, many newer functions are undocumented.
> 
> This is *reference* documentation.  What we lack (sorely!) is an
> overview / friendly introduction, and a design document with rationale.
> Reconstructing rationale now would involve guesswork.

Me nods; that (guesswork in retroactive rationale construction) makes
matters slightly more difficult.

[...]

> >     Opening qom/object.h[2], indeed there is copious amounts of docs,
> >     expressed as commented-out text.  Two questions:
> >
> >     - How much of this is still accurate?  (Sorry, if that's a loaded
> >       question.)
> 
> May I present you Armbru's Comment Trust Levels:
>
> ACTL2: The comment may be overly terse or incomplete, but the
> probability for it to be outright wrong is low.
> 
> ACTL1: Treat as helpful guidance (with gratitude), but trust only the
> code.
> 
> ACTL0: It is a tale Told by an idiot[**], full of sound and fury,
> Signifying nothing.
> 
> Most comments in decently maintained code are at ACTL1.

Noted.  (And thanks for the useful reference scale :-))

> Around the time initial QOM development solidified, object.h's comments
> were ACTL2.  The neglect that is now clearly visible there makes me
> downgrade to ACTL1.
> 
> Paolo will have a more informed and possibly different opinion.
> 
> >     - If at least 60% is still accurate, is it valuable to extract and
> >       publish it as rendered rST, as part of the on-going QEMU Docs
> >       improvement?
> 
> Beware, personal opinion.
> 
> When you put documentation next to the code it documents (which you
> absolutely should, because it's your only realistic chance to keep the
> two in sync), then extracting API comments is useful, because it
> collects them in one place.
> 
> It's of next to no use to me when the comments are all in the same place
> already, namely the header.

Yeah, reasonable point.

> > (b) The other clue is also from the same post, where Eduardo provides
> >     pointers to past KVM Forum presentations by MarkusA, PaoloB,
> >     AndreasF on QOM, Qdev et al.
> >
> >     Is it worth slapping all these references (with a clear intro and
> >     outro) into a qom.rst file in QEMU tree, even if only for
> >     reference/context?  Or are these references, in-tree docs in
> >     object.h out-of-date beyond repair?  
> 
> Uff.
> 
> My qdev talks predate the rebase onto QOM.  They may well confuse /
> mislead as much as inform now.

Good to know.  (We don't want to add additional sources of confusion.)

> > If it is useful, I'm happy to get the initial doc going, secure in the
> > knowledge that more clueful people than me will chip in during the
> > review :-)
> 
> Ha, nerd sniping!

:-)

Thanks for the response; it was useful.

[...]

-- 
/kashyap