On 13 June 2018 at 17:55, John Snow <js...@redhat.com> wrote: > The same reasoning could be used to justify > > /* two > * lines */ > > as it's ... actually just two lines. I think people don't seem to like > this much either (why? does it look 'naked' on the end?)
I dislike the way it breaks up the line of stars. For me it is the /* * */ shape that defines a multiline comment, and where exactly the text is on the RHS of it is not important to my sense of visual neatness :-) > 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. thanks -- PMM
