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

login
register
mail settings
Submitter Anthony Liguori
Date May 12, 2011, 3:58 p.m.
Message ID <4DCC039B.5070608@codemonkey.ws>
Download mbox | patch
Permalink /patch/95336/
State New
Headers show

Comments

Anthony Liguori - May 12, 2011, 3:58 p.m.
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.

Regards,

Anthony Liguori

>
> cheers,
> Gerd
>
>
Markus Armbruster - May 12, 2011, 4:18 p.m.
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.

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.

[...]
Anthony Liguori - May 12, 2011, 4:25 p.m.
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.

I really dislike overloading things for inline help.  Introducing a 
device_help is fine and hopefully you realize that generating this is 
trivial.

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

I view this as a feature.  What's documented is what's supported. 
Anything that isn't documented isn't supported.

But yes, hopefully it's obvious that we can add automated checks to 
improve this.

But if we're going to start somewhere, this is where I think we should 
start.

Regards,

Anthony Liguori

> [...]
>
Anthony Liguori - May 12, 2011, 5:21 p.m.
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

> [...]
>
Markus Armbruster - May 12, 2011, 6 p.m.
Anthony Liguori <anthony@codemonkey.ws> writes:

> 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.
>
> I really dislike overloading things for inline help.  Introducing a
> device_help is fine and hopefully you realize that generating this is
> trivial.

I never liked "device_add ?" myself, but it's what we got.  I'd support
replacing it with something more decent.

[...]

Patch

From 130c817790880c61b79dbccf66f5863c406eb7d4 Mon Sep 17 00:00:00 2001
From: Anthony Liguori <aliguori@us.ibm.com>
Date: Thu, 12 May 2011 10:56:29 -0500
Subject: [PATCH] qdev: add centralized documentation for qdev

This is mostly a proof-of-concept.

Signed-off-by: Anthony Liguori <aliguori@us.ibm.com>

diff --git a/Makefile b/Makefile
index 2b0438c..fddb261 100644
--- a/Makefile
+++ b/Makefile
@@ -341,5 +341,7 @@  tarbin:
 	$(mandir)/man1/qemu-img.1 \
 	$(mandir)/man8/qemu-nbd.8
 
+include $(SRC_PATH)/Makefile.doc
+
 # Include automatically generated dependency files
 -include $(wildcard *.d audio/*.d slirp/*.d block/*.d net/*.d ui/*.d)
diff --git a/Makefile.doc b/Makefile.doc
new file mode 100644
index 0000000..f769b23
--- /dev/null
+++ b/Makefile.doc
@@ -0,0 +1,2 @@ 
+qdev-doc.html: $(SRC_PATH)/qdev-doc.json
+	python $(SRC_PATH)/scripts/qdev-doc-to-html.py < $< > $@
diff --git a/qdev-doc.json b/qdev-doc.json
new file mode 100644
index 0000000..c24630b
--- /dev/null
+++ b/qdev-doc.json
@@ -0,0 +1,14 @@ 
+# -*- Mode: Python -*-
+
+[ { "device": "isa-serial",
+    "parent": "ISADevice",
+    "properties": {
+            "index": { "type": "uint32",
+                       "doc": "A value from 0-3 that describes which IO regions to expose the device on.  This sets appropriate values for iobase and irq." },
+            "iobase": { "type": "hex32",
+                        "doc": "The base IO address to expose the device on." },
+            "irq": { "type": "uint32",
+                     "doc": "The IRQ to use for the device." },
+            "chardev": { "type": "chr",
+                         "doc": "The name of a character device to specify." } } }
+  ]
diff --git a/scripts/qdev-doc-to-html.py b/scripts/qdev-doc-to-html.py
new file mode 100644
index 0000000..a25fe35
--- /dev/null
+++ b/scripts/qdev-doc-to-html.py
@@ -0,0 +1,40 @@ 
+#!/usr/bin/python
+
+import sys
+
+data = sys.stdin.read()
+
+docs = eval(data)
+
+sys.stdout.write('''
+<html>
+<head>
+<title>QEMU device documentation</title>
+</head>
+<body>
+''')
+
+for item in docs:
+    sys.stdout.write('''
+<h2>%(device)s :: %(parent)s</h2>
+
+<table border="1">
+<tr>
+<th>Name</th><th>Type</th><th>Comments</th>
+</tr>
+''' % item)
+    for prop in item["properties"]:
+        sys.stdout.write('''
+<tr>
+<td>%s</td><td>%s</td><td>%s</td>
+</tr>
+''' % (prop, item["properties"][prop]['type'], item["properties"][prop]['doc']))
+
+    sys.stdout.write('''
+</table>
+''')
+
+sys.stdout.write('''
+</body>
+</html>
+''')
-- 
1.7.4.1