Paolo Bonzini <pbonz...@redhat.com> writes: > Il ven 31 gen 2020, 11:36 Peter Maydell <peter.mayd...@linaro.org> ha > scritto: > >> 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. >> > > 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!
