On Fri, 31 Jan 2020 at 06:11, Markus Armbruster <arm...@redhat.com> 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