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

[Peter Maydell]

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.

To throw in a personal opinion on the other side, API comments
should be in the header, not the .c file, because they're
your external interface and as an external consumer of that
interface I shouldn't have to go digging around in your
implementation source file to find the documentation.

Since Paolo put in the effort to upstream the kerneldoc
Sphinx plugin, it's now relatively simple to pull in
the doc comments into a rST file, so you might as well I
guess, though I agree that the cumulative benefit over
just reading the .h file is not enormous.

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.

thanks
-- PMM