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
>From 130c817790880c61b79dbccf66f5863c406eb7d4 Mon Sep 17 00:00:00 2001
From: Anthony Liguori <aligu...@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 <aligu...@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
