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

Consistent, stable, and bit-rotten.  Unless you come up with a way to
catch bit-rot immediately.  That means on "make", not on "make docs".

Extra points if the error message points right to the offending source
line.

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

No need to tell me; I'm well aware that when you have sufficiently
strong opinions, consensus doesn't matter ;-P

>                                     qdev properties are part of our UI
> and need to be stable.

Presenting them all to the user in a single document makes sense.
Doesn't follow we have to *write* the documentation in a single place.

Keeping property documentation in one place makes it soemwhat easier to
keep the properties consistent with each other across devices.

Property documentation next the device code implementing them makes it
easier to keep the documentation consistent with reality.  It also
serves as code documentation.

It's a trade off.  I prefer property documentation next to the code.  To
really get consistency across devices, you have to read the resulting
user document, anyway.

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

Having to code stuff twice, once in C and once in JSON, is a pretty ugly
downside.

JSON is a fine data interchange format for programs, but neither a
programming language, nor a document markup language.

[...]