On Fri, Jan 31, 2020 at 07:11:15AM +0100, Markus Armbruster wrote: > Kashyap Chamarthy <kcham...@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
