[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: |
Markus Armbruster |
Subject: |
Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments |
Date: |
Fri, 15 Jun 2018 14:45:53 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux) |
Peter Maydell <address@hidden> writes:
> On 13 June 2018 at 17:55, John Snow <address@hidden> wrote:
[...]
>> 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.
Putting the function contract far from the actual function is a proven
way to end up with a contract that is far from what the function
actually does.
With a documentation generator such as Sphinx, the usual argument for
putting the contracts in headers "I want API documentation in one place,
without clutter" carries a lot less weight: the generated documentation
is exactly that.
- Re: [Qemu-trivial] [Qemu-devel] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, (continued)
- 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, 2018/06/14
- 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 <=
Re: [Qemu-trivial] [PATCH v2] CODING_STYLE: Define our preferred form for multiline comments, Stefan Hajnoczi, 2018/06/13