Re: [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments

[Philippe Mathieu-Daudé]

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 <address@hidden> 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.