Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]

[Markus Armbruster]

Paolo Bonzini <address@hidden> writes:

> Il ven 31 gen 2020, 11:36 Peter Maydell <address@hidden> ha
> scritto:
>
>> On Fri, 31 Jan 2020 at 06:11, Markus Armbruster <address@hidden> wrote:
>> > Beware, personal opinion.
>> >
>> > When you put documentation next to the code it documents (which you
>> > absolutely should, because it's your only realistic chance to keep the
>> > two in sync), then extracting API comments is useful, because it
>> > collects them in one place.
>> >
>> > It's of next to no use to me when the comments are all in the same place
>> > already, namely the header.
>>
>
> The advantage of putting them in the header is that you have them all in
> one place (inline functions and structs must be in the header). In practice
> that balances for me the disadvantage of having some comments far from the
> code they document, which increases the risk of bitrot especially for
> comments such as "called with lock X held".

With suitable doc generation from source, we can have them next to the
code *and* all in one place, namely the generated interface docs.

>> I definitely agree that the overview/introduction/conventions
>> side of things is where we'd benefit most if somebody wanted
>> to try to tackle that. We could roll
>> https://wiki.qemu.org/Documentation/QOMConventions
>> into that if we had a better place to put that info.
>>
>
> I am travelling this weekend so I might try to do some kind of thread
> summary and brain dump in the wiki. I'll leave to Kashyap to do the rST
> conversion and patch submission. ;-)

That would be awesome!