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

[Markus Armbruster]

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*.

> 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.