[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our pref
From: |
Peter Maydell |
Subject: |
Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments |
Date: |
Thu, 14 Jun 2018 11:46:17 +0100 |
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 :-)
> 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
- Re: [Qemu-trivial] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, (continued)
- Re: [Qemu-trivial] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Thomas Huth, 2018/06/11
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, John Snow, 2018/06/11
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Richard Henderson, 2018/06/12
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Peter Maydell, 2018/06/13
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, John Snow, 2018/06/13
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments,
Peter Maydell <=
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, John Snow, 2018/06/14
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Philippe Mathieu-Daudé, 2018/06/14
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Thomas Huth, 2018/06/15
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Peter Maydell, 2018/06/15
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Markus Armbruster, 2018/06/15
Re: [Qemu-trivial] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Stefan Hajnoczi, 2018/06/13