Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)

[Anthony Liguori]

On 05/13/2011 02:35 AM, Markus Armbruster wrote:

> > That's fine.  But what better way to ensure a consistent and stable UI
> > than having it centralized in one place.
>
> Consistent, stable, and bit-rotten.  Unless you come up with a way to
> catch bit-rot immediately.  That means on "make", not on "make docs".

How about make check?

See the latest patch.  Here is the output from a bad doc file:


Warning: device `virtio-9p-pci' is undocumented
Warning: device `virtio-balloon-pci' is undocumented
Warning: device `virtio-serial-pci' is undocumented
Warning: device `virtio-net-pci' is undocumented
Warning: device `virtio-blk-pci' is undocumented
[ .. snip .. ]
Warning: device `x3130-upstream' is undocumented
Warning: device `xio3130-downstream' is undocumented
Error: device `isa-serial' has documented property `bad-property' with 
no definition
Warning: device `isa-parallel' is undocumented
Warning: device `isa-pit' is undocumented
[ .. snip .. ]
Warning: device `i440FX-xen' is undocumented
Warning: device `i440FX' is undocumented
Warning: device `i440FX-pcihost' is undocumented
Warning: device `vmport' is undocumented
Warning: device `ib700' is undocumented
Warning: device `isa-debugcon' is undocumented
Error: documented device `BadDevice' has no definition
91 warnings, 2 errors.


> Extra points if the error message points right to the offending source
> line.

Would need some macro magic in the qdev registration functions.  It's 
not outside the realm of possibility.

> >                                      qdev properties are part of our UI
> > and need to be stable.
>
> Presenting them all to the user in a single document makes sense.
> Doesn't follow we have to *write* the documentation in a single place.
>
> Keeping property documentation in one place makes it soemwhat easier to
> keep the properties consistent with each other across devices.
>
> Property documentation next the device code implementing them makes it
> easier to keep the documentation consistent with reality.  It also
> serves as code documentation.
>
> It's a trade off.  I prefer property documentation next to the code.  To
> really get consistency across devices, you have to read the resulting
> user document, anyway.

I see this evolving.  To me, this is the start of a qdev schema from 
which we can generate factory interfaces to each qdev device.

> > Just like we express our command line options centrally (with
> > documentation) via qemu-options.hx, it seems reasonable to me to do it
> > for qdev properties.
> >
> > I think the only downside is that we have to duplicate this the
> > current DeviceInfo definitions but that's a harder problem that can be
> > deferred for another day.
>
> Having to code stuff twice, once in C and once in JSON, is a pretty ugly
> downside.

At least I didn't submit it using XML ;-)

Regards,

Anthony Liguori


> JSON is a fine data interchange format for programs, but neither a
> programming language, nor a document markup language.
>
> [...]