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

[Anthony Liguori <anthony@codemonkey.ws>]

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.

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

>