On 06/14/2018 05:11 PM, John Snow wrote: > On 06/14/2018 06:46 AM, Peter Maydell wrote: >> 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 :-) >> > > Yours does look an awful lot more symmetrical once you remove the text, > yeah. > > *cough* I hate the way it looks too, but C99 comments have a few things > going for them: > > // A multi-line comment block like this has no extra lines and every > // line in the comment is prefaced individually which aids grep > // readability, while maintained good vertical symmetry. > > I think we hate C99 comments, though? Certainly we don't use them at all > right now, so it's not a good fit. > >>> 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. >> > > I'd love this! I love vim/emacs, but my usage of it is not wizard-tier > and in the past when working on large C++ projects I have benefited from > the magical refactoring click-buttons, tool-tips and etc. These > operations are infrequent enough that I believe it's reasonable to not > know how to do them in traditional CLI editors. If we want to lure in > new contributors, maybe this could sweeten the pot a bit? > > Rigorous, mechanically verifiable function documentation is quite nice > to have in these cases. It'd be nice in general, really. It would go a > long way to help us attract less "hardcore" developers implementing > devices and features for QEMU without such a steep onboarding curve. > > Do you have a proposed standard / do we have some consensus on which > generator tool or doc format we'd most like to see in QEMU? I could put > in some elbow grease to shine up the block layer if so... > >>> 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. >> > > This makes sense, though the way C code is laid out makes it unfortunate > you don't get to see the same comment right beside the implementation if > that's what you're working on -- but I suppose this is why we have tabs, > multi-monitors and IDEs with tooltips.
Thanks to tabs we don't need multi-monitors of 1600+ resolution to fit 80 chars per line.