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

[Anthony Liguori <anthony@codemonkey.ws>]

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