From: Anthony Liguori <anthony@codemonkey.ws>
To: Gerd Hoffmann <kraxel@redhat.com>
Cc: amit.shah@redhat.com, Markus Armbruster <armbru@redhat.com>,
Brad Hards <bradh@frogmouth.net>,
qemu-devel@nongnu.org
Subject: Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
Date: Thu, 12 May 2011 10:58:19 -0500 [thread overview]
Message-ID: <4DCC039B.5070608@codemonkey.ws> (raw)
In-Reply-To: <4DCBFBFF.7000203@redhat.com>
[-- Attachment #1: Type: text/plain, Size: 651 bytes --]
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
>
>
[-- Attachment #2: 0001-qdev-add-centralized-documentation-for-qdev.patch --]
[-- Type: text/x-patch, Size: 2528 bytes --]
>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
next prev parent reply other threads:[~2011-05-12 15:58 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-05-10 10:30 [Qemu-devel] [PATCH 0/2] usb-linux: physical port handling Gerd Hoffmann
2011-05-10 10:30 ` [Qemu-devel] [PATCH 1/2] usb-linux: fix device path aka " Gerd Hoffmann
2011-05-11 8:52 ` Markus Armbruster
2011-05-12 9:17 ` Gerd Hoffmann
2011-05-10 10:30 ` [Qemu-devel] [PATCH 2/2] usb-linux: add hostport property Gerd Hoffmann
2011-05-10 14:24 ` [Qemu-devel] [PATCH 0/2] usb-linux: physical port handling Brad Hards
2011-05-12 9:25 ` [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.) Gerd Hoffmann
2011-05-12 11:09 ` Markus Armbruster
2011-05-12 15:25 ` Gerd Hoffmann
2011-05-12 15:35 ` Anthony Liguori
2011-05-12 16:08 ` Markus Armbruster
2011-05-12 16:23 ` Anthony Liguori
2011-05-12 17:58 ` Markus Armbruster
2011-05-12 18:07 ` Anthony Liguori
2011-05-13 7:35 ` Markus Armbruster
2011-05-13 14:29 ` Anthony Liguori
2011-05-13 14:30 ` Anthony Liguori
2011-05-12 18:15 ` Peter Maydell
2011-05-12 19:32 ` Alon Levy
2011-05-12 20:08 ` Anthony Liguori
2011-05-13 7:13 ` Markus Armbruster
2011-05-12 15:56 ` Markus Armbruster
2011-05-12 16:05 ` Anthony Liguori
2011-05-12 15:58 ` Anthony Liguori [this message]
2011-05-12 16:18 ` Markus Armbruster
2011-05-12 16:25 ` Anthony Liguori
2011-05-12 18:00 ` Markus Armbruster
2011-05-12 17:21 ` Anthony Liguori
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4DCC039B.5070608@codemonkey.ws \
--to=anthony@codemonkey.ws \
--cc=amit.shah@redhat.com \
--cc=armbru@redhat.com \
--cc=bradh@frogmouth.net \
--cc=kraxel@redhat.com \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).