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".
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. ;-)
Paolo