From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from eggs.gnu.org ([140.186.70.92]:38608)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <anthony@codemonkey.ws>) id 1QKZa7-0000w5-7u
	for qemu-devel@nongnu.org; Thu, 12 May 2011 13:21:49 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <anthony@codemonkey.ws>) id 1QKZa6-0003u5-1y
	for qemu-devel@nongnu.org; Thu, 12 May 2011 13:21:47 -0400
Received: from mail-gy0-f173.google.com ([209.85.160.173]:46933)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <anthony@codemonkey.ws>) id 1QKZa5-0003t5-Rs
	for qemu-devel@nongnu.org; Thu, 12 May 2011 13:21:46 -0400
Received: by gyg4 with SMTP id 4so719115gyg.4
	for <qemu-devel@nongnu.org>; Thu, 12 May 2011 10:21:45 -0700 (PDT)
Message-ID: <4DCC1724.2090605@codemonkey.ws>
Date: Thu, 12 May 2011 12:21:40 -0500
From: Anthony Liguori <anthony@codemonkey.ws>
MIME-Version: 1.0
References: <1305023443-8722-1-git-send-email-kraxel@redhat.com>	<201105101624.08253.bradh@frogmouth.net>
	<4DCBA79B.5040608@redhat.com>	<m3d3jo2n1u.fsf@blackfin.pond.sub.org>
	<4DCBFBFF.7000203@redhat.com>	<4DCC039B.5070608@codemonkey.ws>
	<m3y62bj3iw.fsf@blackfin.pond.sub.org>
In-Reply-To: <m3y62bj3iw.fsf@blackfin.pond.sub.org>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2]
 usb-linux: physical port handling.)
List-Id: <qemu-devel.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/qemu-devel>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: Markus Armbruster <armbru@redhat.com>
Cc: amit.shah@redhat.com, Gerd Hoffmann <kraxel@redhat.com>, Brad Hards <bradh@frogmouth.net>, qemu-devel@nongnu.org

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

> [...]
>