From: Paolo Bonzini <pbonzini@redhat.com>
To: Peter Maydell <peter.maydell@linaro.org>
Cc: "Kevin Wolf" <kwolf@redhat.com>,
"Daniel P. Berrangé" <berrange@redhat.com>,
"Denis V. Lunev" <den@virtuozzo.com>,
"Kashyap Chamarthy" <kchamart@redhat.com>,
"Stefan Hajnoczi" <stefanha@gmail.com>,
"Markus Armbruster" <armbru@redhat.com>,
qemu-devel <qemu-devel@nongnu.org>,
"Christophe de Dinechin" <dinechin@redhat.com>,
"Marc-André Lureau" <marcandre.lureau@redhat.com>,
"Dominik Csapak" <d.csapak@proxmox.com>,
"John Snow" <jsnow@redhat.com>,
"Eduardo Habkost" <ehabkost@redhat.com>
Subject: Re: Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications]
Date: Fri, 31 Jan 2020 12:02:05 +0100 [thread overview]
Message-ID: <CABgObfaB=wHXyJbQR163bZdFHhWdCc4D8sWRHzte019_hSTuhA@mail.gmail.com> (raw)
In-Reply-To: <CAFEAcA-545QS9mnM6hwa6TxUpw_pDQ3Pa8tkf4qtzWS1Zi_fxQ@mail.gmail.com>
[-- Attachment #1: Type: text/plain, Size: 1418 bytes --]
Il ven 31 gen 2020, 11:36 Peter Maydell <peter.maydell@linaro.org> ha
scritto:
> On Fri, 31 Jan 2020 at 06:11, Markus Armbruster <armbru@redhat.com> wrote:
> > Beware, personal opinion.
> >
> > When you put documentation next to the code it documents (which you
> > absolutely should, because it's your only realistic chance to keep the
> > two in sync), then extracting API comments is useful, because it
> > collects them in one place.
> >
> > It's of next to no use to me when the comments are all in the same place
> > already, namely the header.
>
The advantage of putting them in the header is that you have them all in
one place (inline functions and structs must be in the header). In practice
that balances for me the disadvantage of having some comments far from the
code they document, which increases the risk of bitrot especially for
comments such as "called with lock X held".
I definitely agree that the overview/introduction/conventions
> side of things is where we'd benefit most if somebody wanted
> to try to tackle that. We could roll
> https://wiki.qemu.org/Documentation/QOMConventions
> into that if we had a better place to put that info.
>
I am travelling this weekend so I might try to do some kind of thread
summary and brain dump in the wiki. I'll leave to Kashyap to do the rST
conversion and patch submission. ;-)
Paolo
> thanks
> -- PMM
>
>
[-- Attachment #2: Type: text/html, Size: 2480 bytes --]
next prev parent reply other threads:[~2020-01-31 11:03 UTC|newest]
Thread overview: 183+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-12-20 16:13 Making QEMU easier for management tools and applications Stefan Hajnoczi
2019-12-20 21:07 ` Richard W.M. Jones
2020-01-02 11:26 ` Stefan Hajnoczi
2019-12-21 9:02 ` Markus Armbruster
2019-12-23 15:04 ` Michal Prívozník
2020-01-07 9:36 ` Kevin Wolf
2020-01-07 10:55 ` Michal Privoznik
2020-01-07 12:57 ` Kevin Wolf
2020-01-07 17:53 ` Christophe de Dinechin
2019-12-24 13:41 ` Daniel P. Berrangé
2020-01-22 22:28 ` John Snow
2020-01-23 7:19 ` Markus Armbruster
2020-01-23 17:58 ` John Snow
2020-01-23 19:01 ` Daniel P. Berrangé
2020-01-23 21:07 ` John Snow
2020-01-24 7:59 ` Markus Armbruster
2020-01-24 10:27 ` Daniel P. Berrangé
2020-01-24 14:38 ` Kevin Wolf
2020-01-24 18:23 ` John Snow
2020-01-24 18:30 ` Dr. David Alan Gilbert
2020-01-24 18:48 ` John Snow
2020-01-24 18:52 ` Dr. David Alan Gilbert
2020-01-24 18:58 ` John Snow
2020-01-25 10:18 ` Markus Armbruster
2020-01-27 10:18 ` Daniel P. Berrangé
2020-01-27 12:48 ` Markus Armbruster
2020-01-27 11:56 ` Kevin Wolf
2020-01-27 12:04 ` Peter Maydell
2020-01-27 20:11 ` John Snow
2020-01-27 22:38 ` Paolo Bonzini
2020-01-28 0:37 ` John Snow
2020-01-28 10:16 ` Daniel P. Berrangé
2020-01-28 10:39 ` Kevin Wolf
2020-01-28 15:36 ` Markus Armbruster
2020-01-31 12:25 ` Eric Blake
2020-01-28 10:28 ` Kevin Wolf
2020-01-28 12:36 ` Markus Armbruster
2020-01-28 12:54 ` Kevin Wolf
2020-01-28 13:45 ` Gerd Hoffmann
2020-01-31 6:50 ` Markus Armbruster
2020-01-31 7:48 ` Paolo Bonzini
2020-01-31 8:09 ` Markus Armbruster
2020-02-03 20:07 ` Andrea Bolognani
2020-02-04 9:58 ` Markus Armbruster
2020-01-31 12:27 ` Eric Blake
2020-02-02 9:21 ` Kevin Wolf
2020-02-02 10:44 ` Paolo Bonzini
2020-02-03 6:20 ` Markus Armbruster
2020-02-03 8:48 ` Markus Armbruster
2020-01-27 20:12 ` Dr. David Alan Gilbert
2020-01-24 20:34 ` John Snow
2020-01-27 8:35 ` Gerd Hoffmann
2020-01-27 12:13 ` Kevin Wolf
2020-01-27 16:18 ` Gerd Hoffmann
2020-01-24 9:50 ` Daniel P. Berrangé
2020-01-25 11:52 ` Paolo Bonzini
2020-01-27 10:05 ` Daniel P. Berrangé
2020-01-27 8:25 ` Tooling to help humans use JSON (was: Making QEMU easier for management tools and applications) Markus Armbruster
2020-01-27 9:06 ` Making QEMU easier for management tools and applications Markus Armbruster
2020-01-27 10:00 ` Daniel P. Berrangé
2020-01-27 14:35 ` Kevin Wolf
2020-01-27 20:29 ` Dr. David Alan Gilbert
2020-01-28 10:59 ` Kevin Wolf
2020-02-05 13:09 ` Kevin Wolf
2020-02-05 19:09 ` qmp-shell for GSoC/Outreachy? (Was: Re: Making QEMU easier for management tools and applications) John Snow
2020-02-05 19:49 ` Dr. David Alan Gilbert
2020-02-06 9:40 ` qmp-shell for GSoC/Outreachy? Markus Armbruster
2020-02-06 10:09 ` Daniel P. Berrangé
2020-02-06 12:11 ` Markus Armbruster
2020-02-06 12:15 ` Daniel P. Berrangé
2020-02-06 18:02 ` Dr. David Alan Gilbert
2020-02-07 21:03 ` John Snow
2020-02-08 7:17 ` Markus Armbruster
2020-02-06 14:21 ` Kevin Wolf
2020-02-06 18:26 ` Dr. David Alan Gilbert
2020-02-07 10:49 ` Kevin Wolf
2020-02-07 21:23 ` John Snow
2020-02-08 7:25 ` Markus Armbruster
2020-02-10 11:59 ` Kevin Wolf
2020-02-10 12:26 ` Kevin Wolf
2020-02-06 18:18 ` Dr. David Alan Gilbert
2020-02-07 7:47 ` Markus Armbruster
2020-02-07 21:31 ` Eric Blake
2020-02-08 7:34 ` Markus Armbruster
2020-02-07 21:56 ` John Snow
2020-02-07 20:56 ` John Snow
2020-01-27 20:59 ` Making QEMU easier for management tools and applications John Snow
2020-01-28 10:16 ` Markus Armbruster
2020-01-28 19:21 ` John Snow
2020-01-24 6:38 ` Markus Armbruster
2020-01-25 22:34 ` Christophe de Dinechin
2020-01-25 11:55 ` Paolo Bonzini
2020-01-02 14:47 ` Stefan Hajnoczi
2020-01-16 11:03 ` Kashyap Chamarthy
2020-01-20 9:55 ` Stefan Hajnoczi
2020-01-20 13:57 ` Kashyap Chamarthy
2020-01-25 11:41 ` Paolo Bonzini
2020-01-27 19:41 ` John Snow
2020-01-02 15:05 ` Dr. David Alan Gilbert
2020-01-13 13:44 ` Markus Armbruster
2019-12-24 13:00 ` Daniel P. Berrangé
2020-01-02 14:22 ` Stefan Hajnoczi
2020-01-22 22:42 ` John Snow
2020-01-23 7:21 ` Markus Armbruster
2020-01-23 10:27 ` Daniel P. Berrangé
2020-01-23 18:13 ` John Snow
2020-01-23 19:12 ` Daniel P. Berrangé
2020-01-02 15:10 ` Dr. David Alan Gilbert
2020-01-07 17:11 ` Christophe de Dinechin
2020-01-08 10:43 ` Kevin Wolf
2020-01-08 11:40 ` Christophe de Dinechin
2020-01-08 13:38 ` Kevin Wolf
2020-01-14 13:04 ` Markus Armbruster
2020-01-14 17:31 ` Christophe de Dinechin
2020-01-15 9:20 ` Markus Armbruster
2020-01-15 9:34 ` Christophe de Dinechin
2020-01-15 12:15 ` Markus Armbruster
2020-01-15 12:19 ` Daniel P. Berrangé
2020-01-15 14:02 ` Markus Armbruster
2020-01-30 21:09 ` Improving QOM documentation [Was: Re: Making QEMU easier for management tools and applications] Kashyap Chamarthy
2020-01-31 6:11 ` Markus Armbruster
2020-01-31 7:46 ` Paolo Bonzini
2020-01-31 15:37 ` Christophe de Dinechin
2020-01-31 16:28 ` Paolo Bonzini
2020-01-31 9:50 ` Kashyap Chamarthy
2020-01-31 10:35 ` Peter Maydell
2020-01-31 11:02 ` Paolo Bonzini [this message]
2020-01-31 15:22 ` Kashyap Chamarthy
2020-01-31 17:23 ` Markus Armbruster
2020-02-03 8:56 ` Paolo Bonzini
2020-02-03 9:54 ` Markus Armbruster
2020-02-03 15:21 ` Paolo Bonzini
2020-02-04 8:42 ` Markus Armbruster
2020-01-31 16:39 ` Markus Armbruster
2020-01-20 10:08 ` Making QEMU easier for management tools and applications Stefan Hajnoczi
2020-01-21 5:42 ` Markus Armbruster
2020-01-21 11:32 ` Stefan Hajnoczi
2020-01-21 12:03 ` Marc-André Lureau
2020-01-21 13:36 ` Integrating QOM into QAPI (was: Making QEMU easier for management tools and applications) Markus Armbruster
2020-01-21 14:36 ` Daniel P. Berrangé
2020-01-21 15:01 ` Integrating QOM into QAPI Markus Armbruster
2020-01-21 15:11 ` Marc-André Lureau
2020-01-21 16:21 ` Peter Maydell
2020-01-22 5:16 ` Getting whole-tree patches reviewed and merged (was: Integrating QOM into QAPI) Markus Armbruster
2020-02-07 21:53 ` Getting whole-tree patches reviewed and merged Eric Blake
2020-02-10 11:26 ` Paolo Bonzini
2020-02-10 16:04 ` Markus Armbruster
2020-02-10 16:12 ` Peter Maydell
2020-01-22 10:50 ` Integrating QOM into QAPI Alex Bennée
2020-01-22 12:24 ` Markus Armbruster
2020-01-22 12:42 ` Marc-André Lureau
2020-01-22 13:28 ` Peter Maydell
2020-01-22 13:32 ` Marc-André Lureau
2020-01-23 7:37 ` Markus Armbruster
2020-01-24 18:32 ` Paolo Bonzini
2020-01-25 4:44 ` Marc-André Lureau
2020-01-25 9:28 ` Paolo Bonzini
2020-01-25 21:25 ` Peter Maydell
2020-01-26 8:09 ` Christophe de Dinechin
2020-01-26 9:11 ` Marc-André Lureau
2020-01-26 16:47 ` Paolo Bonzini
2020-01-27 19:05 ` Christophe de Dinechin
2020-01-27 19:05 ` Christophe de Dinechin
2020-01-26 15:04 ` Peter Maydell
2020-01-27 19:05 ` Christophe de Dinechin
2020-01-28 8:00 ` Markus Armbruster
2020-01-28 10:03 ` Daniel P. Berrangé
2020-01-29 12:42 ` Christophe de Dinechin
2020-01-15 9:35 ` Making QEMU easier for management tools and applications Marc-André Lureau
2020-01-15 12:25 ` Markus Armbruster
2020-01-25 17:18 ` Paolo Bonzini
2020-01-27 9:30 ` Markus Armbruster
2020-01-13 16:30 ` Stefan Hajnoczi
2020-02-04 15:54 ` Summary of " Markus Armbruster
2020-02-05 6:38 ` Markus Armbruster
2020-02-10 10:56 ` Stefan Hajnoczi
2020-02-10 11:01 ` Peter Maydell
2020-02-10 11:08 ` Daniel P. Berrangé
2020-02-10 11:29 ` Peter Maydell
2020-02-10 11:04 ` Paolo Bonzini
2020-02-10 16:43 ` Markus Armbruster
2020-02-12 13:54 ` Stefan Hajnoczi
2020-02-12 14:03 ` Daniel P. Berrangé
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CABgObfaB=wHXyJbQR163bZdFHhWdCc4D8sWRHzte019_hSTuhA@mail.gmail.com' \
--to=pbonzini@redhat.com \
--cc=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=d.csapak@proxmox.com \
--cc=den@virtuozzo.com \
--cc=dinechin@redhat.com \
--cc=ehabkost@redhat.com \
--cc=jsnow@redhat.com \
--cc=kchamart@redhat.com \
--cc=kwolf@redhat.com \
--cc=marcandre.lureau@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
--cc=stefanha@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).