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

[Anthony Liguori]

On 05/12/2011 12:58 PM, Markus Armbruster wrote:
> Anthony Liguori<address@hidden>  writes:
>
> > On 05/12/2011 11:08 AM, Markus Armbruster wrote:
> > > Anthony Liguori<address@hidden>   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