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

[Thomas Huth]

On 14.06.2018 22:11, John Snow wrote:
> 
> On 06/14/2018 06:46 AM, Peter Maydell wrote:
[...]
> 
> *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.

But why do we hate them? I remember there were some reasons for not
using them 10 or 15 years ago (some old C-compilers still did not
support them yet), but today? ... it's likely just a legacy feeling.
Maybe it's time to get over that feeling now?

>>> 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.
[...]
> 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...

I remember that some years ago, somebody (I forgot who it was, sorry)
once told me that we should use the same format in QEMU as in glib, i.e.
GTK-Doc. But citing the GTK-Doc homepage: "For a more polished
general-purpose documentation tool you may want to look at Doxygen" - so
maybe that's the better choice instead.

 Thomas