Peter Maydell <peter.mayd...@linaro.org> writes: > On 13 June 2018 at 17:55, John Snow <js...@redhat.com> wrote: [...] >> It would only begin to matter terribly much if we actually decided we >> wanted to do a doxygen-style doc generation for our internal APIs for >> compatibility with, say, fancier IDEs than vim/emacs. > > We ought to do that at some point -- I had some prototype patches > for it. Doc-comment comments always start /** on a line of its own, > though. > >> As it stands, we're pretty inconsistent about which exact style we apply >> when we "document" internal functions -- sometimes we document the >> header, sometimes the implementation, sometimes both (but differently!) >> and always with different styles all over the place. That's the real >> problem, IMO. > > IMHO -- global functions should always be documented in the header > with the prototype, and any new global function should get a > doc comment (I require this for code I review...) I should be able > to read about the API your code exposes to the rest of QEMU purely > by looking at your headers.
Putting the function contract far from the actual function is a proven way to end up with a contract that is far from what the function actually does. With a documentation generator such as Sphinx, the usual argument for putting the contracts in headers "I want API documentation in one place, without clutter" carries a lot less weight: the generated documentation is exactly that.
