[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Improving QOM documentation [Was: Re: Making QEMU easier for managem
From: |
Kashyap Chamarthy |
Subject: |
Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications] |
Date: |
Fri, 31 Jan 2020 10:50:23 +0100 |
On Fri, Jan 31, 2020 at 07:11:15AM +0100, Markus Armbruster wrote:
> Kashyap Chamarthy <address@hidden> 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
- Re: Making QEMU easier for management tools and applications, (continued)
- Re: Making QEMU easier for management tools and applications, Markus Armbruster, 2020/01/15
- Re: Making QEMU easier for management tools and applications, Christophe de Dinechin, 2020/01/15
- Re: Making QEMU easier for management tools and applications, Markus Armbruster, 2020/01/15
- Re: Making QEMU easier for management tools and applications, Daniel P . Berrangé, 2020/01/15
- Re: Making QEMU easier for management tools and applications, Markus Armbruster, 2020/01/15
- Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications], Kashyap Chamarthy, 2020/01/30
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications], Markus Armbruster, 2020/01/31
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications], Paolo Bonzini, 2020/01/31
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications], Christophe de Dinechin, 2020/01/31
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications], Paolo Bonzini, 2020/01/31
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications],
Kashyap Chamarthy <=
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications], Peter Maydell, 2020/01/31
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications], Paolo Bonzini, 2020/01/31
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications], Kashyap Chamarthy, 2020/01/31
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications], Markus Armbruster, 2020/01/31
- Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications], Markus Armbruster, 2020/01/31
- Re: Making QEMU easier for management tools and applications, Stefan Hajnoczi, 2020/01/20
- Re: Making QEMU easier for management tools and applications, Markus Armbruster, 2020/01/21
- Re: Making QEMU easier for management tools and applications, Stefan Hajnoczi, 2020/01/21
- Re: Making QEMU easier for management tools and applications, Marc-André Lureau, 2020/01/21
- Integrating QOM into QAPI (was: Making QEMU easier for management tools and applications), Markus Armbruster, 2020/01/21