Philippe Mathieu-Daudé <phi...@redhat.com> writes: > Many functions have documentation before the implementation in > cutils.c. Since we expect documentation around the prototype > declaration in headers,
We do? There are two justifiable function comment placement styles: (1) next to definition, and (2) next to declaration if it's in a header, else next to definition. The rationale for the latter is having the headers do double-duty as interface documentation. The rationale for the former is consistently placing the function comments close to the code gives them a fighting chance to actually match the code. I'm in the "next to definition" camp. If you want concise interface specification, use something like Sphinx. QEMU code is, as so often, in all camps. > move the comments in cutils.h. We document some cutils functions next to their definition, and some next to their declaration. The inconsistency is ugly, and your patch fixes it. I'd fix it in the other direction. Even if we decide to fix this one in this direction, I object to the sweeping generalization in the commit message :)
