From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 3F0D1C982D0 for ; Thu, 17 Sep 2026 18:52:21 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1x7HDC-0007Bi-Sd; Thu, 17 Sep 2026 14:51:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1x7HDB-0007BE-8g for qemu-devel@nongnu.org; Thu, 17 Sep 2026 14:51:57 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1x7HD9-0004Zb-Om for qemu-devel@nongnu.org; Thu, 17 Sep 2026 14:51:57 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1789671115; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=FxBbXNM4cRzWRyxM/CvJcZ+dcO+Bk3VgtUkJsWvgt5k=; b=Wlg6sBIUMhaVbQDdgQVrzsYAMVM0pV3nxsjMGU/RS2ajbQ9XdbI85uh7ls2rRxOKtl633z kgRtoVSjt951qWpvczzHStPfahS3uDKXBbESI37KR0V2GXhHosHWrI7ETx/XBtz0/P+++R RNtyyTsaVYbkzLunETlt6GTs25CUTS0= Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-84-IbHGdlh-MEqZV6G03_UWdw-1; Thu, 17 Sep 2026 14:51:50 -0400 X-MC-Unique: IbHGdlh-MEqZV6G03_UWdw-1 X-Mimecast-MFC-AGG-ID: IbHGdlh-MEqZV6G03_UWdw_1789671109 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id D970A1912C4C; Thu, 17 Sep 2026 18:51:48 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.5]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E2DB530001A2; Thu, 17 Sep 2026 18:51:47 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 7A32021E6A04; Thu, 17 Sep 2026 20:51:45 +0200 (CEST) From: Markus Armbruster To: John Snow Cc: qemu-devel@nongnu.org, Zhao Liu , Peter Xu , Philippe =?utf-8?Q?Mathieu-Daud=C3=A9?= , Philippe =?utf-8?Q?Mathieu-Daud=C3=A9?= , Jonathan Cameron , Eric Blake , Fabiano Rosas , Kevin Wolf , Michael Roth , linux-cxl@vger.kernel.org, qemu-block@nongnu.org, Junjie Cao , Lukas Straub , Hanna Reitz , Paolo Bonzini , Jason Wang Subject: Re: [PATCH v4 7/7] qapi: convert intro sections followed by notes/examples In-Reply-To: (John Snow's message of "Thu, 17 Sep 2026 13:50:59 -0400") References: <20260916135841.3614495-1-jsnow@redhat.com> <20260916135841.3614495-8-jsnow@redhat.com> <877bkl6p5s.fsf@pond.sub.org> Date: Thu, 17 Sep 2026 20:51:45 +0200 Message-ID: <87ld8zr9ry.fsf@pond.sub.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org John Snow writes: > On Wed, Sep 16, 2026 at 2:13=E2=80=AFPM Markus Armbruster wrote: >> >> John Snow writes: >> >> > These provide a rather natural cutoff point, but technically this does >> > introduce a new intro/details split to these documentation blocks. >> >> Not sure what you mean by "technically". > > As a German, when an American says "technically", you can just omit > that word from the sentence. > I think, translating for you: "I don't expect these changes to have > any immediate effect, but it's possible they might". > You found the case where they might - a case where we probably > actually did want a "TODO:" but never added it. > >> >> > >> > Signed-off-by: John Snow >> > --- >> > qapi/machine.json | 5 ++--- >> > qapi/migration.json | 15 +++++++-------- >> > qapi/misc.json | 3 +-- >> > qapi/run-state.json | 7 +++---- >> > 4 files changed, 13 insertions(+), 17 deletions(-) >> > >> > diff --git a/qapi/machine.json b/qapi/machine.json >> > index 84d95c8d87f..276258d9e5c 100644 >> > --- a/qapi/machine.json >> > +++ b/qapi/machine.json >> > @@ -1209,9 +1209,8 @@ >> > >> > ## >> > # @HV_BALLOON_STATUS_REPORT: >> > -# >> > -# Emitted when the hv-balloon driver receives a "STATUS" message from >> > -# the guest. >> > +# Emitted when the hv-balloon driver receives a "STATUS" message >> > +# from the guest. >> > # >> > # .. note:: This event is rate-limited. >> > # >> # Since: 8.2 >> >> The patch splits the first section between after the first paragraph, >> i.e. before the note. >> >> This matters, because we insert generated argument documentation after >> the first section. Rendered documentation changes like this >> >> Emitted when the hv-balloon driver receives a "STATUS" message from >> the guest. >> >> + Members: >> + * The members of "HvBalloonInfo". >> + >> Note: >> >> This event is rate-limited. >> >> - Members: >> - * The members of "HvBalloonInfo". >> - >> Example:: >> >> <- { "event": "HV_BALLOON_STATUS_REPORT", Improvement, actually. >> > diff --git a/qapi/migration.json b/qapi/migration.json >> > index d571c06fc20..a272e701385 100644 >> > --- a/qapi/migration.json >> > +++ b/qapi/migration.json >> > @@ -1254,10 +1254,10 @@ >> > >> > ## >> > # @migrate_cancel: >> > -# >> > -# Cancel the currently executing migration process. Allows a new >> > -# migration to be started right after. When postcopy-ram is in use, >> > -# cancelling is not allowed after the postcopy phase has started. >> > +# Cancel the currently executing migration process. Allows a new >> > +# migration to be started right after. When postcopy-ram is in >> > +# use, cancelling is not allowed after the postcopy phase has >> > +# started. >> > # >> > # .. note:: This command succeeds even if there is no migration >> > # process running. >> >> Similar split, but rendered documentation doesn't change, because >> nothing gets inserted. >> >> Same for the remaining hunks. >> >> Should the one hunk that changes rendered documentation be in the "qapi: >> convert/split remaining QAPI/QMP intro sections" series? > > If you should so please. I was splitting by semantics and not effect, > but I can split this one out for you. It's an honest question! If you think it fits here at least as well as in the next series, keep it here, and mention how it affects rendered documentation in the commit message. > >> >> [...] >>