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

[Anthony Liguori <anthony@codemonkey.ws>]

On 05/12/2011 11:18 AM, Markus Armbruster wrote:
> Anthony Liguori<anthony@codemonkey.ws>  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

> [...]
>