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

[Kashyap Chamarthy <kchamart@redhat.com>]

On Wed, Jan 15, 2020 at 03:02:48PM +0100, Markus Armbruster wrote:
> Daniel P. Berrangé <berrange@redhat.com> writes:

[Changed the subject-line to indicate deviation from the original
topic.]

[...]

> > Libvirt is of course happy to switch to something else instead of
> > qom-set for these features if QEMU wants to provide a safer
> > alternative.
> 
> Noted.
> 
> libvirt's use of qom-set is okay.  What's not okay is the near-complete
> lack of QOM documentation, its poor QMP interface, in part due to
> non-integration with QAPI, and last but not least the lack of QOM
> leadership leaving it adrift.

What can be done to improve QOM documentation (or lack thereof)?

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

Let's dig further.  Ah, I come across this helpful 2016 blog post[1]
("An incomplete list of QEMU APIs") by Eduardo from my bookmarks.  Here
I get some clues:

(a) In the section titled "QOM", Eduardo writes:

        "QOM is short for QEMU Object Model and was introduced in 2011.
        It is heavily documented on its header file
        [include/qom/object.h]" 

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

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

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

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 :-)

[1] https://habkost.net/posts/2016/11/incomplete-list-of-qemu-apis.html
[2] https://git.qemu.org/?p=qemu.git;a=blob;f=include/qom/object.h
[3] http://www.linux-kvm.org/images/9/90/Kvmforum14-qom.pdf

-- 
/kashyap