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

[Anthony Liguori]

On 05/12/2011 11:18 AM, Markus Armbruster wrote:
> Anthony Liguori<address@hidden>  writes:
>
> > On 05/12/2011 10:25 AM, Gerd Hoffmann wrote:
> > > Hi,
> > >
> > > > > What is the status of the qdev documentation patches btw.?
> > > >
> > > > http://lists.gnu.org/archive/html/qemu-devel/2011-02/msg02169.html
> > >
> > > What is the problem with the empty strings btw?
> > >
> > > The only way around I can see is having _DOC and _NODOC versions for all
> > > the property macros, but I'd prefer to not have _NODOC macros in the
> > > tree ...
> >
> > Here's an example of what I'm suggesting.  I think we should just go
> > with this and add better output as we go.
> >
> > But we need all of the qdev information..  not just a doc string for
> > each property.
>
> Missing: make "device_add ?" show your device doc strings, and
> "device_add NAME,?" show your property doc strings.

This is all it takes:

#!/usr/bin/python

import sys

data = sys.stdin.read()

docs = eval(data)

sys.stdout.write('DeviceStateDocumentation device_docs[] = {')

for item in docs:
    sys.stdout.write('''
    {
      .name = "%(device)s",
      .properties = (PropertyDocumentation[])({''' % item)
    for prop in item["properties"]:
        sys.stdout.write('''
        { "%s", "%s", "%s" },''' % (prop, 
item["properties"][prop]['type'], item["properties"][prop]['doc']))

    sys.stdout.write('''
        { },
    },''')

sys.stdout.write('''
};
''')

Plus a little plumbing magic to add the actual command.

> Missing: automated check qdev-doc.json matches the code.  Keeping the
> docs far from the code is a bad idea even with such a check.

If you walk the DeviceInfo list, you can validate that (1) each device 
has a corresponding entry in device_docs (2) any field in device_docs is 
present in device (3) the types match.

Regards,

Anthony Liguori

> [...]