Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
Peter Maydell peter.mayd...@linaro.org writes: On 12 May 2011 19:58, Markus Armbruster arm...@redhat.com wrote: Anthony Liguori anth...@codemonkey.ws writes: But for things like Spice where the lack of libspice influences whether the device is available, how do I extract formal documentation to publish on qemu.org reliably? If no maintainer of QEMU can build with Spice enabled, it got more serious problems than extracting its documentation. The point isn't that you can arrange to build with option Foo enabled but that if the build environment changes accidentally there's not much warning that the official docs have suddenly lost some devices. Fair point. Compare against list of known devices. That way, all you keep at bit-rotting distance from code is the list of known devices. [...]
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
Anthony Liguori anth...@codemonkey.ws writes: On 05/12/2011 12:58 PM, Markus Armbruster wrote: Anthony Liguorianth...@codemonkey.ws writes: On 05/12/2011 11:08 AM, Markus Armbruster wrote: Anthony Liguorianth...@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 ... Inline documentation is bad. Our documentation should be centralized. That's the only way to keep it consistent and thorough. External documentation of code details is bad. Our documentation should be next to the code. That's the only way to keep it up-to-date and consistent with the code. qdev properties are *not* code details. It's a public user interface that we have to support for every. The fact that they are public user interface doesn't change the fact that they're code at all. They are *both*. That's fine. But what better way to ensure a consistent and stable UI than having it centralized in one place. Consistent, stable, and bit-rotten. Unless you come up with a way to catch bit-rot immediately. That means on make, not on make docs. Extra points if the error message points right to the offending source line. It should be disconnected from the internal implementation. And yes, the incestuous relationship that exists today is a problem, but it's one we're going to have to live with. I doubt we'll ever reach consensus on this one. I don't think that matters though. No need to tell me; I'm well aware that when you have sufficiently strong opinions, consensus doesn't matter ;-P qdev properties are part of our UI and need to be stable. Presenting them all to the user in a single document makes sense. Doesn't follow we have to *write* the documentation in a single place. Keeping property documentation in one place makes it soemwhat easier to keep the properties consistent with each other across devices. Property documentation next the device code implementing them makes it easier to keep the documentation consistent with reality. It also serves as code documentation. It's a trade off. I prefer property documentation next to the code. To really get consistency across devices, you have to read the resulting user document, anyway. Just like we express our command line options centrally (with documentation) via qemu-options.hx, it seems reasonable to me to do it for qdev properties. I think the only downside is that we have to duplicate this the current DeviceInfo definitions but that's a harder problem that can be deferred for another day. Having to code stuff twice, once in C and once in JSON, is a pretty ugly downside. JSON is a fine data interchange format for programs, but neither a programming language, nor a document markup language. [...]
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
On 05/13/2011 02:35 AM, Markus Armbruster wrote: That's fine. But what better way to ensure a consistent and stable UI than having it centralized in one place. Consistent, stable, and bit-rotten. Unless you come up with a way to catch bit-rot immediately. That means on make, not on make docs. How about make check? See the latest patch. Here is the output from a bad doc file: Warning: device `virtio-9p-pci' is undocumented Warning: device `virtio-balloon-pci' is undocumented Warning: device `virtio-serial-pci' is undocumented Warning: device `virtio-net-pci' is undocumented Warning: device `virtio-blk-pci' is undocumented [ .. snip .. ] Warning: device `x3130-upstream' is undocumented Warning: device `xio3130-downstream' is undocumented Error: device `isa-serial' has documented property `bad-property' with no definition Warning: device `isa-parallel' is undocumented Warning: device `isa-pit' is undocumented [ .. snip .. ] Warning: device `i440FX-xen' is undocumented Warning: device `i440FX' is undocumented Warning: device `i440FX-pcihost' is undocumented Warning: device `vmport' is undocumented Warning: device `ib700' is undocumented Warning: device `isa-debugcon' is undocumented Error: documented device `BadDevice' has no definition 91 warnings, 2 errors. Extra points if the error message points right to the offending source line. Would need some macro magic in the qdev registration functions. It's not outside the realm of possibility. qdev properties are part of our UI and need to be stable. Presenting them all to the user in a single document makes sense. Doesn't follow we have to *write* the documentation in a single place. Keeping property documentation in one place makes it soemwhat easier to keep the properties consistent with each other across devices. Property documentation next the device code implementing them makes it easier to keep the documentation consistent with reality. It also serves as code documentation. It's a trade off. I prefer property documentation next to the code. To really get consistency across devices, you have to read the resulting user document, anyway. I see this evolving. To me, this is the start of a qdev schema from which we can generate factory interfaces to each qdev device. Just like we express our command line options centrally (with documentation) via qemu-options.hx, it seems reasonable to me to do it for qdev properties. I think the only downside is that we have to duplicate this the current DeviceInfo definitions but that's a harder problem that can be deferred for another day. Having to code stuff twice, once in C and once in JSON, is a pretty ugly downside. At least I didn't submit it using XML ;-) Regards, Anthony Liguori JSON is a fine data interchange format for programs, but neither a programming language, nor a document markup language. [...]
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
On 05/13/2011 02:35 AM, Markus Armbruster wrote:
Anthony Liguorianth...@codemonkey.ws writes:
That's fine. But what better way to ensure a consistent and stable UI
than having it centralized in one place.
Consistent, stable, and bit-rotten. Unless you come up with a way to
catch bit-rot immediately. That means on make, not on make docs.
Extra points if the error message points right to the offending source
line.
Er, hit send too fast. Here's the next patch.
From f5c30c922ce1cf755ef78887f4015c131d8d6841 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 1/1] qdev: add centralized documentation for qdev (v2)
This adds a -qdev-verify option that will confirm that the documentation matches
the code. It returns a non-zero exit status if any errors are detected.
Signed-off-by: Anthony Liguori aligu...@us.ibm.com
---
Makefile|2 +
Makefile.doc|5 ++
Makefile.objs |2 +-
qdev-doc.h | 23 +++
qdev-doc.json | 16
qemu-options.hx | 10 +
scripts/qdev-doc-to-c.py| 30 ++
scripts/qdev-doc-to-html.py | 40 +++
vl.c| 89 +++
9 files changed, 216 insertions(+), 1 deletions(-)
create mode 100644 Makefile.doc
create mode 100644 qdev-doc.h
create mode 100644 qdev-doc.json
create mode 100644 scripts/qdev-doc-to-c.py
create mode 100644 scripts/qdev-doc-to-html.py
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 000..c1cf74a
--- /dev/null
+++ b/Makefile.doc
@@ -0,0 +1,5 @@
+qdev-doc.html: $(SRC_PATH)/qdev-doc.json $(SRC_PATH)/scripts/qdev-doc-to-html.py
+ python $(SRC_PATH)/scripts/qdev-doc-to-html.py $ $@
+
+qdev-doc.c: $(SRC_PATH)/qdev-doc.json $(SRC_PATH)/scripts/qdev-doc-to-c.py
+ python $(SRC_PATH)/scripts/qdev-doc-to-c.py $ $@
diff --git a/Makefile.objs b/Makefile.objs
index 4478c61..9547ab1 100644
--- a/Makefile.objs
+++ b/Makefile.objs
@@ -97,7 +97,7 @@ common-obj-y += bt-hci-csr.o
common-obj-y += buffered_file.o migration.o migration-tcp.o
common-obj-y += qemu-char.o savevm.o #aio.o
common-obj-y += msmouse.o ps2.o
-common-obj-y += qdev.o qdev-properties.o
+common-obj-y += qdev.o qdev-properties.o qdev-doc.o
common-obj-y += block-migration.o iohandler.o
common-obj-y += pflib.o
common-obj-y += bitmap.o bitops.o
diff --git a/qdev-doc.h b/qdev-doc.h
new file mode 100644
index 000..401e03e
--- /dev/null
+++ b/qdev-doc.h
@@ -0,0 +1,23 @@
+#ifndef QDEV_DOC_H
+#define QDEV_DOC_H
+
+#include qemu-common.h
+
+typedef struct PropertyDocumentation
+{
+const char *name;
+const char *type;
+const char *docs;
+} PropertyDocumentation;
+
+typedef struct DeviceStateDocumentation
+{
+const char *name;
+PropertyDocumentation *properties;
+} DeviceStateDocumentation;
+
+extern DeviceStateDocumentation device_docs[];
+
+bool qdev_verify_docs(void);
+
+#endif
diff --git a/qdev-doc.json b/qdev-doc.json
new file mode 100644
index 000..a798bff
--- /dev/null
+++ b/qdev-doc.json
@@ -0,0 +1,16 @@
+# -*- 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/qemu-options.hx b/qemu-options.hx
index 9f121ad..a6abab4 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2378,6 +2378,16 @@ Specify a trace file to log output traces to.
ETEXI
#endif
+DEF(qdev-verify, 0, QEMU_OPTION_qdev_verify,
+-qdev-verify\n
+Verify qdev properties match documentation\n,
+QEMU_ARCH_ALL)
+STEXI
+@item -qdev-verify
+@findex -qdev-verify
+Verify qdev properties match documentation.
+ETEXI
+
HXCOMM This is the last statement. Insert new options before this line!
STEXI
@end table
diff --git a/scripts/qdev-doc-to-c.py b/scripts/qdev-doc-to-c.py
new file mode 100644
index 000..eb7ee59
--- /dev/null
+++ b/scripts/qdev-doc-to-c.py
@@ -0,0 +1,30 @@
+#!/usr/bin/python
+
+import sys
+
+data = sys.stdin.read()
+
+docs = eval(data)
+
+sys.stdout.write('''
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
[note cc: Amit] Gerd Hoffmann kra...@redhat.com writes: Hi, Some additional docs (based on 2/2 hints) might be a useful addition. Indeed. Possible candidates: - docs/qdev-device-use.txt - qemu-doc.texi Hmm. qemu-doc.texi only documents the pre-qdev way to create devices. qdev-device-use.txt is a conversion guide. devices which can only be created via -device (or provide additional features via qdev attributes when created that way) are not documented anywhere now. Suggestions? Should we add a qdev section to qemu-doc.texi? Or better a separate qemu-devices.txt (or .texi)? What is the status of the qdev documentation patches btw.? http://lists.gnu.org/archive/html/qemu-devel/2011-02/msg02169.html Maybe we should just merge them, then start filling stuff and maybe also autogenerate documentation from that? Yes. Amit, once more into the breach?
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
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 ... cheers, Gerd
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
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 ... Inline documentation is bad. Our documentation should be centralized. That's the only way to keep it consistent and thorough. There's no way to easily extract the inline docs in a complete way since some devices are built conditionally. Regards, Anthony Liguori cheers, Gerd
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
Gerd Hoffmann kra...@redhat.com writes: 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? Anthony ;) [...]
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
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 000..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 000..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 000..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
+titleQEMU device documentation/title
+/head
+body
+''')
+
+for item in docs:
+sys.stdout.write('''
+h2%(device)s :: %(parent)s/h2
+
+table border=1
+tr
+thName/ththType/ththComments/th
+/tr
+''' % item)
+for prop in item[properties]:
+sys.stdout.write('''
+tr
+td%s/tdtd%s/tdtd%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
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
On 05/12/2011 10:56 AM, Markus Armbruster wrote: Gerd Hoffmannkra...@redhat.com writes: 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? Anthony ;) 1) It doesn't help us get good written documentation without non-existent magic to extract a qdev schema. 2) It makes the documentation hidden in random places in the tree making it hard to audit what is undocumented. 3) It guarantees that documentation will vary drastically in language and quality. 4) I greatly fear that we're embarking down yet another introduce a new API that never gets fully converted path. I've sent a quick patch out with what I think is a significantly better approach. Regards, Anthony Liguori [...]
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
Anthony Liguori anth...@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 ... Inline documentation is bad. Our documentation should be centralized. That's the only way to keep it consistent and thorough. External documentation of code details is bad. Our documentation should be next to the code. That's the only way to keep it up-to-date and consistent with the code. There's no way to easily extract the inline docs in a complete way since some devices are built conditionally. For each configured target: extract docs of the devices it builds Concatenate and discard the duplicates Yes, that means you don't get docs for devices none of your targets has. That's a feature. If you really want docs for all devices, build all targets.
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
Anthony Liguori anth...@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. [...]
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
On 05/12/2011 11:08 AM, Markus Armbruster wrote: Anthony Liguorianth...@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 ... Inline documentation is bad. Our documentation should be centralized. That's the only way to keep it consistent and thorough. External documentation of code details is bad. Our documentation should be next to the code. That's the only way to keep it up-to-date and consistent with the code. qdev properties are *not* code details. It's a public user interface that we have to support for every. It should be disconnected from the internal implementation. And yes, the incestuous relationship that exists today is a problem, but it's one we're going to have to live with. There's no way to easily extract the inline docs in a complete way since some devices are built conditionally. For each configured target: extract docs of the devices it builds Concatenate and discard the duplicates Yes, that means you don't get docs for devices none of your targets has. That's a feature. If you really want docs for all devices, build all targets. But for things like Spice where the lack of libspice influences whether the device is available, how do I extract formal documentation to publish on qemu.org reliably? Regards, Anthony Liguori
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
On 05/12/2011 11:18 AM, Markus Armbruster wrote: Anthony Liguorianth...@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 [...]
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
On 05/12/2011 11:18 AM, Markus Armbruster wrote:
Anthony Liguorianth...@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
[...]
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
Anthony Liguori anth...@codemonkey.ws writes: On 05/12/2011 11:08 AM, Markus Armbruster wrote: Anthony Liguorianth...@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 ... Inline documentation is bad. Our documentation should be centralized. That's the only way to keep it consistent and thorough. External documentation of code details is bad. Our documentation should be next to the code. That's the only way to keep it up-to-date and consistent with the code. qdev properties are *not* code details. It's a public user interface that we have to support for every. The fact that they are public user interface doesn't change the fact that they're code at all. They are *both*. It should be disconnected from the internal implementation. And yes, the incestuous relationship that exists today is a problem, but it's one we're going to have to live with. I doubt we'll ever reach consensus on this one. There's no way to easily extract the inline docs in a complete way since some devices are built conditionally. For each configured target: extract docs of the devices it builds Concatenate and discard the duplicates Yes, that means you don't get docs for devices none of your targets has. That's a feature. If you really want docs for all devices, build all targets. But for things like Spice where the lack of libspice influences whether the device is available, how do I extract formal documentation to publish on qemu.org reliably? If no maintainer of QEMU can build with Spice enabled, it got more serious problems than extracting its documentation.
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
On 05/12/2011 12:58 PM, Markus Armbruster wrote: Anthony Liguorianth...@codemonkey.ws writes: On 05/12/2011 11:08 AM, Markus Armbruster wrote: Anthony Liguorianth...@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 ... Inline documentation is bad. Our documentation should be centralized. That's the only way to keep it consistent and thorough. External documentation of code details is bad. Our documentation should be next to the code. That's the only way to keep it up-to-date and consistent with the code. qdev properties are *not* code details. It's a public user interface that we have to support for every. The fact that they are public user interface doesn't change the fact that they're code at all. They are *both*. That's fine. But what better way to ensure a consistent and stable UI than having it centralized in one place. It should be disconnected from the internal implementation. And yes, the incestuous relationship that exists today is a problem, but it's one we're going to have to live with. I doubt we'll ever reach consensus on this one. I don't think that matters though. qdev properties are part of our UI and need to be stable. Just like we express our command line options centrally (with documentation) via qemu-options.hx, it seems reasonable to me to do it for qdev properties. I think the only downside is that we have to duplicate this the current DeviceInfo definitions but that's a harder problem that can be deferred for another day. Yes, that means you don't get docs for devices none of your targets has. That's a feature. If you really want docs for all devices, build all targets. But for things like Spice where the lack of libspice influences whether the device is available, how do I extract formal documentation to publish on qemu.org reliably? If no maintainer of QEMU can build with Spice enabled, it got more serious problems than extracting its documentation. It's not about Spice. But having documentation that is influenced by build options seems like a bad thing to me. But regardless, centralized documentation means more consistency in the documentation. I think this is a critically important point. Regards, Anthony Liguori
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
On 12 May 2011 19:58, Markus Armbruster arm...@redhat.com wrote: Anthony Liguori anth...@codemonkey.ws writes: But for things like Spice where the lack of libspice influences whether the device is available, how do I extract formal documentation to publish on qemu.org reliably? If no maintainer of QEMU can build with Spice enabled, it got more serious problems than extracting its documentation. The point isn't that you can arrange to build with option Foo enabled but that if the build environment changes accidentally there's not much warning that the official docs have suddenly lost some devices. The spice probe in configure will barf if you said --enable-spice and spice wasn't found, but I bet not all configure checks that influence availability of a device do that. And since there isn't currently an '--enable-all' option to configure the docs builder would have to keep track of every new --enable-foo switch and add it to the configure command... Which looks pretty ugly and not very reliable to me. -- PMM
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
Anthony Liguori anth...@codemonkey.ws writes: On 05/12/2011 11:18 AM, Markus Armbruster wrote: Anthony Liguorianth...@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. [...]
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
On Thu, May 12, 2011 at 08:15:43PM +0200, Peter Maydell wrote: On 12 May 2011 19:58, Markus Armbruster arm...@redhat.com wrote: Anthony Liguori anth...@codemonkey.ws writes: But for things like Spice where the lack of libspice influences whether the device is available, how do I extract formal documentation to publish on qemu.org reliably? If no maintainer of QEMU can build with Spice enabled, it got more serious problems than extracting its documentation. The point isn't that you can arrange to build with option Foo enabled but that if the build environment changes accidentally there's not much warning that the official docs have suddenly lost some devices. The spice probe in configure will barf if you said --enable-spice and spice wasn't found, but I bet not all configure checks that influence availability of a device do that. And since there isn't currently an '--enable-all' option to configure the docs builder would have to keep track of every new --enable-foo switch and add it to the configure command... Which looks pretty ugly and not very reliable to me. We could have a (just picking up the Spice example) spice-docs file that was checked in and updated periodically by generation by the maintainer. It's error prone, you could still update the source but forget to checkin the spice-docs and get an old version, but at least it would still be auto-generated, and it would not prevent the docs builder from working. -- PMM
Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.)
On 05/12/2011 02:32 PM, Alon Levy wrote: We could have a (just picking up the Spice example) spice-docs file that was checked in and updated periodically by generation by the maintainer. It's error prone, you could still update the source but forget to checkin the spice-docs and get an old version, but at least it would still be auto-generated, and it would not prevent the docs builder from working. It's not just Spice though. There are still a number of devices that only get built with certain targets. Doing it right is actually fairly complicated. It's far easier to use a central doc file, and then add mechanisms to ensure things don't get out of sync. Regards, Anthony Liguori -- PMM
