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

[Alon Levy <alevy@redhat.com>]

On Thu, May 12, 2011 at 08:15:43PM +0200, Peter Maydell wrote:
> On 12 May 2011 19:58, Markus Armbruster <armbru@redhat.com> wrote:
> > Anthony Liguori <anthony@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
>