From: Markus Armbruster <armbru@redhat.com>
To: John Snow <jsnow@redhat.com>
Cc: qemu-devel@nongnu.org,
"Marc-André Lureau" <marcandre.lureau@redhat.com>,
"Michael S. Tsirkin" <mst@redhat.com>,
"Eduardo Habkost" <eduardo@habkost.net>,
"Jiri Pirko" <jiri@resnulli.us>,
"Peter Maydell" <peter.maydell@linaro.org>,
"Ani Sinha" <anisinha@redhat.com>,
"Zhao Liu" <zhao1.liu@intel.com>, "Peter Xu" <peterx@redhat.com>,
"Gerd Hoffmann" <kraxel@redhat.com>,
"Fabiano Rosas" <farosas@suse.de>,
qemu-block@nongnu.org, "Gonglei (Arei)" <arei.gonglei@huawei.com>,
"Laurent Vivier" <laurent@vivier.eu>,
"Jason Wang" <jasowang@redhat.com>,
"Yanan Wang" <wangyanan55@huawei.com>,
qemu-trivial@nongnu.org, "Stefan Hajnoczi" <stefanha@redhat.com>,
"Mads Ynddal" <mads@ynddal.dk>,
"Lukas Straub" <lukasstraub2@web.de>,
"Marcel Apfelbaum" <marcel.apfelbaum@gmail.com>,
"Kevin Wolf" <kwolf@redhat.com>,
"Vladimir Sementsov-Ogievskiy" <vsementsov@yandex-team.ru>,
"Michael Tokarev" <mjt@tls.msk.ru>,
"Paolo Bonzini" <pbonzini@redhat.com>,
"Daniel P. Berrangé" <berrange@redhat.com>,
"Eric Blake" <eblake@redhat.com>,
"Hanna Reitz" <hreitz@redhat.com>,
"Zhenwei Pi" <pizhenwei@bytedance.com>,
"Stefan Berger" <stefanb@linux.vnet.ibm.com>,
"Michael Roth" <michael.roth@amd.com>,
"Philippe Mathieu-Daudé" <philmd@linaro.org>
Subject: Re: [PATCH v6 4/4] qapi: rephrase return docs to avoid type name
Date: Mon, 14 Jul 2025 08:40:27 +0200 [thread overview]
Message-ID: <87wm8b6zs4.fsf@pond.sub.org> (raw)
In-Reply-To: <877c0eygpn.fsf@pond.sub.org> (Markus Armbruster's message of "Fri, 11 Jul 2025 15:55:48 +0200")
Markus Armbruster <armbru@redhat.com> writes:
> John Snow <jsnow@redhat.com> writes:
>
>> Well, I tried. Maybe not very hard. Sorry!
>
> Recommend to explain *why* we want to avoid the type name.
>
> "Returns: <description>" is rendered like "Return: <Type> –
> <description>". Mentioning the type in the description again is
> commonly redundant. Rephrase such descriptions not to.
>
>> Signed-off-by: John Snow <jsnow@redhat.com>
[...]
> I need to stop here to take care of another series. Gut feeling so far:
> right direction, doesn't go far enough.
>
> Choices:
>
> * Go far enough. Too close to the freeze for that, I'm afraid.
>
> * Merge it basically as is, come back later to finish the job.
Let's pick this one, then try to improve on top.
> * Drop it for now, adjust your "QAPI: add cross-references to qapi docs"
> to enclose the type names not removed in `backquotes`.
>
> Thoughts?
>
> [...]
Acked-by: Markus Armbruster <armbru@redhat.com>
next prev parent reply other threads:[~2025-07-14 6:50 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-07-11 5:10 [PATCH v6 0/4] qapi: add auto-generated return docs John Snow
2025-07-11 5:10 ` [PATCH v6 1/4] docs/qapi-domain: add return-nodesc John Snow
2025-07-11 17:22 ` Markus Armbruster
2025-07-11 5:10 ` [PATCH v6 2/4] docs, qapi: generate undocumented return sections John Snow
2025-07-11 13:22 ` Markus Armbruster
2025-07-11 5:10 ` [PATCH v6 3/4] qapi: remove trivial "Returns:" sections John Snow
2025-07-11 13:23 ` Markus Armbruster
2025-07-11 5:10 ` [PATCH v6 4/4] qapi: rephrase return docs to avoid type name John Snow
2025-07-11 13:55 ` Markus Armbruster
2025-07-14 6:40 ` Markus Armbruster [this message]
2025-07-14 13:40 ` [PATCH v6 0/4] qapi: add auto-generated return docs Markus Armbruster
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=87wm8b6zs4.fsf@pond.sub.org \
--to=armbru@redhat.com \
--cc=anisinha@redhat.com \
--cc=arei.gonglei@huawei.com \
--cc=berrange@redhat.com \
--cc=eblake@redhat.com \
--cc=eduardo@habkost.net \
--cc=farosas@suse.de \
--cc=hreitz@redhat.com \
--cc=jasowang@redhat.com \
--cc=jiri@resnulli.us \
--cc=jsnow@redhat.com \
--cc=kraxel@redhat.com \
--cc=kwolf@redhat.com \
--cc=laurent@vivier.eu \
--cc=lukasstraub2@web.de \
--cc=mads@ynddal.dk \
--cc=marcandre.lureau@redhat.com \
--cc=marcel.apfelbaum@gmail.com \
--cc=michael.roth@amd.com \
--cc=mjt@tls.msk.ru \
--cc=mst@redhat.com \
--cc=pbonzini@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=peterx@redhat.com \
--cc=philmd@linaro.org \
--cc=pizhenwei@bytedance.com \
--cc=qemu-block@nongnu.org \
--cc=qemu-devel@nongnu.org \
--cc=qemu-trivial@nongnu.org \
--cc=stefanb@linux.vnet.ibm.com \
--cc=stefanha@redhat.com \
--cc=vsementsov@yandex-team.ru \
--cc=wangyanan55@huawei.com \
--cc=zhao1.liu@intel.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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.