From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457048; cv=none; d=zohomail.com; s=zohoarc; b=LDb3jlzBa+QcczzQRD3PSj9EGQ4OiJVkFVVtd7ujG9OdzvLZaL0Bpjyj78DNBSdaBofoIhM43iOOTuhIlQTv5yTF/DNfkhcLf3de5c2r5QFkKA5cKxqxMHDX9xfavR4xuMAhtyBi4UWTMCviOykQYBpIQDKJnMOrQ8ZDQgZtXPQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457048; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=8D57LdqxPoD4a9j6wePWb8wwo2KDSwcsiMBMUdPpIx8=; b=jXnRulqU1d/OGERgkwt007trziq1qtkzFp8FiBN/OUHyOc5okkvaO2tPoOrIw7TLp0TfhmMcqZ6RB1rqJwIPC2yScNiZZW7MntWglFEjJTHCQPpmD4jdHnHDHp/xcclNwbShrAutdIsQgE1ge8U6d1dO5+P71rtbEPM2Rq+0vBs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780457048924225.50448201183985; Tue, 2 Jun 2026 20:24:08 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcBW-00009c-GC; Tue, 02 Jun 2026 23:22:26 -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 1wUcBU-000091-O5 for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:24 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUcBR-0002MQ-JA for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:24 -0400 Received: from mx-prod-mc-06.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-39-OjFNwjwaOg-Fpby1I_pYfA-1; Tue, 02 Jun 2026 23:22:14 -0400 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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id ECD36180123B; Wed, 3 Jun 2026 03:22:12 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 335353000203; Wed, 3 Jun 2026 03:22:08 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456936; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=8D57LdqxPoD4a9j6wePWb8wwo2KDSwcsiMBMUdPpIx8=; b=KOu8z5CvYoeYVMo3Ap7/U9Q66gxXaqetmPbnsUmJWL/LoRsI1MFo/0DpRtJOjAarzbMGgU 13kaJ0rTkaJr4maoUi1Lr2JysJpcZnCbgnOAXtV7qwMqK4K00v4zAr1kbPbrVs7tR4vlmw oYP+xALuw917zrnmOLk5wFbx7D/MOgI= X-MC-Unique: OjFNwjwaOg-Fpby1I_pYfA-1 X-Mimecast-MFC-AGG-ID: OjFNwjwaOg-Fpby1I_pYfA_1780456933 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 01/16] python: temporarily restrict max mypy version Date: Tue, 2 Jun 2026 23:21:46 -0400 Message-ID: <20260603032201.993015-2-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457050240154100 Content-Type: text/plain; charset="utf-8" The newest versions of mypy do not support targeting Python 3.9, which we still support. I want to address that soon, but in the meantime it's nice if the tests pass. Signed-off-by: John Snow --- python/setup.cfg | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/python/setup.cfg b/python/setup.cfg index 80975933971..ad4121a58d8 100644 --- a/python/setup.cfg +++ b/python/setup.cfg @@ -40,7 +40,8 @@ devel =3D flake8 >=3D 5.0.4 fusepy >=3D 2.0.4 isort >=3D 5.6.0 - mypy >=3D 1.4.0 + # Max ver is temporary until we drop 3.9 + mypy >=3D 1.4.0, <2.0.0 pylint >=3D 2.17.3 pylint !=3D 3.2.4; python_version<"3.9" pytest >=3D 6.0.2 --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457064; cv=none; d=zohomail.com; s=zohoarc; b=kuysJOEb62Iql1iGV3S4LHoTQbmpYx/tW83jSw5o3vloEWHuvDft+ia2AJL1FDoDaVUDe9pUaqio0JfJgGJdV9Q41P6u0sWwbZGqhSv6tZAuEA5FGdBzSxG1CA8e/UsfVkZei1nq1AgdEHP7gDnr6fLfHPSpXGhcoOTJRMFYcFc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457064; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=D39Y81M9rFkACn/NQlcX7QZiwh/aJXxhvafRYIbxpe8=; b=lhUJQmIUJ1reLMmuCdrR1oDyn19prnpi8bhV2cazgYFFpDZmSujHmOZ37X7PrvFxTZu+lZBkVH5cokXexxYTsD0QTFYD5olcXFLbBPLS9MY50nq/2lN2S1z/HEaQ5Rg27PZj1VM9FPwhZCN4Xa65zBI2GbrJLhoUxwJLv9gU+Ww= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780457064276570.7559460987212; Tue, 2 Jun 2026 20:24:24 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcBX-00009t-9B; Tue, 02 Jun 2026 23:22:27 -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 1wUcBV-000099-5P for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:25 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUcBS-0002Mt-6e for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:24 -0400 Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-141-W9w6AD-iN_6FkoJoulkQ3Q-1; Tue, 02 Jun 2026 23:22:18 -0400 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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 3C09519560B7; Wed, 3 Jun 2026 03:22:16 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 47DD7300022D; Wed, 3 Jun 2026 03:22:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456941; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=D39Y81M9rFkACn/NQlcX7QZiwh/aJXxhvafRYIbxpe8=; b=ZI/KilbeW6RZy9WO2Qm6eL/2Z4LulNZcLDA3VnpLnI6ZAGVev3qags1Nc9RuGltKaEIEAG Vy3vXCbkO3AiLEnl5oUZhbSbhOM13OhZpSlv9SGvCklRjkPCisH6zoz9oIRQxpwbJENT7v XrcEwf2r2DxPNIeJh9N11k6jNuPLOTI= X-MC-Unique: W9w6AD-iN_6FkoJoulkQ3Q-1 X-Mimecast-MFC-AGG-ID: W9w6AD-iN_6FkoJoulkQ3Q_1780456936 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 02/16] tests/qapi: generate output in source order Date: Tue, 2 Jun 2026 23:21:47 -0400 Message-ID: <20260603032201.993015-3-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457065631158500 Content-Type: text/plain; charset="utf-8" Rewrite the test doc generator to produce output in source order instead of arbitrarily by section name. This patch removes our last use of the "body" field, which has an effect on how the sections of each test documention block are printed. We now print the name of the section followed by the section text for all sections except Members and Features, which are printed as "Member=3D%s" or "Feature=3D%s" followed by the section text, respectively. This patch is motivated by a desire to move the QAPIDoc API away from named fields for specific sections in a bid to force all users to simply iterate through all_sections in order, instead - and to remove the named subsections. Signed-off-by: John Snow --- tests/qapi-schema/doc-good.out | 82 +++++++++++++++++----------------- tests/qapi-schema/test-qapi.py | 14 +++--- 2 files changed, 48 insertions(+), 48 deletions(-) diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 04a55072646..b9829e2f841 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -54,15 +54,15 @@ event EVT_BOXED Object boxed=3DTrue feature feat3 doc freeform - body=3D + Plain ******* Section ******* doc freeform - body=3D + Plain Just text, no heading. doc freeform - body=3D + Plain Subsection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -106,84 +106,84 @@ Examples: - *verbatim* - {braces} doc symbol=3DEnum - body=3D + Plain =20 - arg=3Done + Member=3Done The _one_ {and only}, description on the same line - arg=3Dtwo + Member=3Dtwo =20 - feature=3Denum-feat + Feature=3Denum-feat Also _one_ {and only} - feature=3Denum-member-feat + Feature=3Denum-member-feat a member feature - section=3DPlain + Plain @two is undocumented doc symbol=3DBase - body=3D + Plain =20 - arg=3Dbase1 + Member=3Dbase1 description starts on a new line, minimally indented doc symbol=3DVariant1 - body=3D + Plain A paragraph =20 Another paragraph =20 @var1 is undocumented - arg=3Dvar1 + Member=3Dvar1 =20 - feature=3Dvariant1-feat + Feature=3Dvariant1-feat a feature - feature=3Dmember-feat + Feature=3Dmember-feat a member feature doc symbol=3DVariant2 - body=3D + Plain =20 doc symbol=3DObject - body=3D + Plain =20 - feature=3Dunion-feat1 + Feature=3Dunion-feat1 a feature doc symbol=3DAlternate - body=3D + Plain =20 - arg=3Di + Member=3Di description starts on the same line remainder indented the same @b is undocumented - arg=3Db + Member=3Db =20 - feature=3Dalt-feat + Feature=3Dalt-feat a feature doc freeform - body=3D + Plain Another subsection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D doc symbol=3Dcmd - body=3D + Plain =20 - arg=3Darg1 + Member=3Darg1 description starts on a new line, indented - arg=3Darg2 + Member=3Darg2 description starts on the same line remainder indented differently - arg=3Darg3 + Member=3Darg3 =20 - feature=3Dcmd-feat1 + Feature=3Dcmd-feat1 a feature - feature=3Dcmd-feat2 + Feature=3Dcmd-feat2 another feature - section=3DPlain + Plain .. note:: @arg3 is undocumented - section=3DReturns + Returns @Object - section=3DErrors + Errors some - section=3DTodo + Todo frobnicate - section=3DPlain + Plain .. admonition:: Notes =20 - Lorem ipsum dolor sit amet @@ -207,23 +207,23 @@ Examples:: =20 Note:: Ceci n'est pas une note - section=3DSince + Since 2.10 doc symbol=3Dcmd-boxed - body=3D + Plain If you're bored enough to read this, go see a video of boxed cats - feature=3Dcmd-feat1 + Feature=3Dcmd-feat1 a feature - feature=3Dcmd-feat2 + Feature=3Dcmd-feat2 another feature - section=3DPlain + Plain .. qmp-example:: =20 -> "this example" =20 <- ... has no title ... doc symbol=3DEVT_BOXED - body=3D + Plain =20 - feature=3Dfeat3 + Feature=3Dfeat3 a feature diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py index cf7fb8a6df5..5beb96e894f 100755 --- a/tests/qapi-schema/test-qapi.py +++ b/tests/qapi-schema/test-qapi.py @@ -19,6 +19,7 @@ from io import StringIO =20 from qapi.error import QAPIError +from qapi.parser import QAPIDoc from qapi.schema import QAPISchema, QAPISchemaVisitor =20 =20 @@ -116,13 +117,12 @@ def test_frontend(fname): print('doc symbol=3D%s' % doc.symbol) else: print('doc freeform') - print(' body=3D\n%s' % doc.body.text) - for arg, section in doc.args.items(): - print(' arg=3D%s\n%s' % (arg, section.text)) - for feat, section in doc.features.items(): - print(' feature=3D%s\n%s' % (feat, section.text)) - for section in doc.sections: - print(' section=3D%s\n%s' % (section.kind, section.text)) + for section in doc.all_sections: + if isinstance(section, QAPIDoc.ArgSection): + print(' %s=3D%s' % (section.kind, section.name)) + else: + print(' %s' % section.kind) + print(section.text) =20 =20 def open_test_result(dir_name, file_name, update): --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780456973; cv=none; d=zohomail.com; s=zohoarc; b=Rw8QgEWj+AUrVfbCDvpZjUWupzquFjjQi2PzXA4GSTYaH2EPejm6Qsl3AZoE3NkY169LNTm34t8zmS5bzxkvjjEKIz8biyF9UYwmB39G0kaxwtoq3XGcEvzuwtmAz+Q0Uu1oyp2h25Cr1kVsU92ydFIqbkMtY8bshv/5rmduXjI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780456973; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=d+ZrUF5QiDAqJMi43LG3mwd5iMGaAwMF/E106IU4/XI=; b=UKsKZ343u+VA7ORLatjCCBM0P26Aigd1PgL6crgUSA2RzSM7cdRPVmMONCSXpk2AwpIu31lJnURBJAvnfE1xPvX5Ow1pr/b3e9vMw5Ztd0Su8GjtGqbwwZHc/LW9VUPNLp+riBPaLfLAL+RMQXHgdjl+5UP0+fbeaaTo170faEQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780456973750851.1046696438303; Tue, 2 Jun 2026 20:22:53 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcBb-0000Aq-4f; Tue, 02 Jun 2026 23:22:31 -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 1wUcBY-0000AB-9f for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:28 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUcBW-0002Ok-PO for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:28 -0400 Received: from mx-prod-mc-06.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-645-UBn-pHWAPqWBHeXNS6Jk5g-1; Tue, 02 Jun 2026 23:22:21 -0400 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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 0144918011FF; Wed, 3 Jun 2026 03:22:20 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 6ED5730001A1; Wed, 3 Jun 2026 03:22:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456945; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=d+ZrUF5QiDAqJMi43LG3mwd5iMGaAwMF/E106IU4/XI=; b=Pl4iGAhdvuZh4XakKOUhu0bDaXQ7NMXwvQbjd2hhBPtS/tRpv6dyCgw6Tk0JspQ4/d4gFk jtv6fJ7fsz0vsWuRIJLO5KTHawK1ofcaEXpe7o1rYZ3HaxG3OgQaCtyIyfSfCvUEwiyEZ0 n4X6QfPBkyN0+ukXgSkifKKEHJ4TsVU= X-MC-Unique: UBn-pHWAPqWBHeXNS6Jk5g-1 X-Mimecast-MFC-AGG-ID: UBn-pHWAPqWBHeXNS6Jk5g_1780456940 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 03/16] qapi/docs: remove unused QAPIDoc subsection members Date: Tue, 2 Jun 2026 23:21:48 -0400 Message-ID: <20260603032201.993015-4-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780456975779154100 Content-Type: text/plain; charset="utf-8" All users of the QAPIDoc object should be iterating over all_sections and not grabbing arbitrary subsections, if possible. Remove the 'body' and 'sections' members, as they are no longer used. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- scripts/qapi/parser.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index c3cf33904ef..b33edbba74f 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -732,8 +732,6 @@ def __init__(self, info: QAPISourceInfo, symbol: Option= al[str] =3D None): self.all_sections: List[QAPIDoc.Section] =3D [ QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) ] - # the body section - self.body: Optional[QAPIDoc.Section] =3D self.all_sections[0] # dicts mapping parameter/feature names to their description self.args: Dict[str, QAPIDoc.ArgSection] =3D {} self.features: Dict[str, QAPIDoc.ArgSection] =3D {} @@ -742,8 +740,6 @@ def __init__(self, info: QAPISourceInfo, symbol: Option= al[str] =3D None): self.errors: Optional[QAPIDoc.Section] =3D None # "Since" section self.since: Optional[QAPIDoc.Section] =3D None - # sections other than .body, .args, .features - self.sections: List[QAPIDoc.Section] =3D [] =20 def end(self) -> None: for section in self.all_sections: @@ -766,7 +762,6 @@ def ensure_untagged_section(self, info: QAPISourceInfo)= -> None: =20 # start new section section =3D self.Section(info, kind) - self.sections.append(section) self.all_sections.append(section) =20 def new_tagged_section( @@ -790,7 +785,6 @@ def new_tagged_section( raise QAPISemError( info, "duplicated '%s' section" % kind) self.since =3D section - self.sections.append(section) self.all_sections.append(section) =20 def _new_description( --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780456990; cv=none; d=zohomail.com; s=zohoarc; b=Uj17aMyK/VnUnGIBhLcrAtx0Q33r0uXtkEgcHmG1d5/3mKfFotL8xoWqHt8zw9TuALqCVtxTGvYZyG6jHNSHMawNkTyrcP+fR7fe+y3vVbY7ror0EZ5hGFKABz0ZltD0vp8cJO5xGli9tgt7jx06MJTKhWV+k9H5hXIOK1FP+ZA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780456990; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=eD93VbLNcb0i8xKYOQN6HBmq0xjc5UHNJ/CSbLRm+fI=; b=grWpsGOs2+NQY3BRxmsXUFlRWbTFZs9Hc2StDCWDPxHmh78OrphpKZg7WvKCmPUlfmQtM3vA5ZpPaP5UoZRovoZ5XCGDdSHv0vSuYOLbRnCF6u16VxU/Z8EJcG5FwaDEYBthEhPkhmQMDbkcUsZIdFTRxAJ6dLU8T3OEyqO6eQM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780456990116932.5919294844371; Tue, 2 Jun 2026 20:23:10 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcBc-0000BZ-Mt; Tue, 02 Jun 2026 23:22:32 -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 1wUcBb-0000Ay-Gm for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:31 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUcBa-0002Ov-6D for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:31 -0400 Received: from mx-prod-mc-06.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-329-rd_0QzmwMoObrbOlYuTP6Q-1; Tue, 02 Jun 2026 23:22:26 -0400 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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 3F58F1801238; Wed, 3 Jun 2026 03:22:24 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 572BC3000203; Wed, 3 Jun 2026 03:22:20 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456949; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=eD93VbLNcb0i8xKYOQN6HBmq0xjc5UHNJ/CSbLRm+fI=; b=XZl8j05ghuARzEYwpX2jW+4ulfo47M8reB4t41DsRt1WPaFFBmpmfuscR5z2HrmFCGA9Am enm4YyxrN21VDj6/4ZFh4Lxw999sSr0BsSkbPrhDCWKlf2bRyGz8EJKxt2M8hW739gTzY8 rt7dZBaxXJdtzc8qN5hexPuf2D2n3I4= X-MC-Unique: rd_0QzmwMoObrbOlYuTP6Q-1 X-Mimecast-MFC-AGG-ID: rd_0QzmwMoObrbOlYuTP6Q_1780456944 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 04/16] qapi/docs: add has_features property Date: Tue, 2 Jun 2026 23:21:49 -0400 Message-ID: <20260603032201.993015-5-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780456991496154100 Content-Type: text/plain; charset="utf-8" Begin preparing to remove public access to the .features member by introducing a semantic "has features" property instead. Signed-off-by: John Snow --- scripts/qapi/parser.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index b33edbba74f..dcc58170bd5 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -555,7 +555,7 @@ def get_doc(self) -> 'QAPIDoc': break # Non-blank line, first of a section if line =3D=3D 'Features:': - if doc.features: + if doc.has_features: raise QAPIParseError( self, "duplicated 'Features:' line") self.accept(False) @@ -570,7 +570,7 @@ def get_doc(self) -> 'QAPIDoc': if text: doc.append_line(text) line =3D self.get_doc_indented(doc) - if not doc.features: + if not doc.has_features: raise QAPIParseError( self, 'feature descriptions expected') no_more_args =3D True @@ -741,6 +741,10 @@ def __init__(self, info: QAPISourceInfo, symbol: Optio= nal[str] =3D None): # "Since" section self.since: Optional[QAPIDoc.Section] =3D None =20 + @property + def has_features(self) -> bool: + return bool(self.features) + def end(self) -> None: for section in self.all_sections: section.text =3D section.text.strip('\n') --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457033; cv=none; d=zohomail.com; s=zohoarc; b=WBhysjW/L/uKQlf8Gf9UvLWLbPVTGltAU0v2VyRteJNSaF20vtkEZCkxukE5ZUCXnkRN9UxywxNw6zkprFJTLyTcC78ZRz9MSM02MJFvERCBHowwhukEPAu8IM5esEzphTfZEt4lg4z5EUFLJQJWe+u4er5a1q2WLPZcEQkDho0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457033; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=i/8BRod6YgBNjBQ1A4fmjvtc3BSkD+yn4td3noauUX8=; b=i6JuXXzfG5ozSePKtV1O2S3JZd7el9xN7tr8W0ayG5PXRYwiWOlXJeYVWVYu1r0x2qpq2bBXyKWNaoGzW7TFN5uMs+AUp5ZvYwZJDgvkmZlAGGy87nT79eQOXnwml5RwgXb8y8J/avAxACwgc/uIaTRZQVOAg8uJj0dEGPu8+YM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780457033529153.5590773105423; Tue, 2 Jun 2026 20:23:53 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcBg-0000CK-Bu; Tue, 02 Jun 2026 23:22:36 -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 1wUcBe-0000Bu-D4 for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:34 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUcBc-0002PY-IP for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:34 -0400 Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-335-CBJ5ZysbPzST3Kn1Md9j_A-1; Tue, 02 Jun 2026 23:22:30 -0400 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-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B515A195609D; Wed, 3 Jun 2026 03:22:28 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 7612230001A1; Wed, 3 Jun 2026 03:22:24 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456951; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=i/8BRod6YgBNjBQ1A4fmjvtc3BSkD+yn4td3noauUX8=; b=QXNEC6UxeESacl7KNh3OpSeitSGqFQQlTTy7Jis+GQLaVTQO9HJmITwvvFGpMF7GDAI4zK 17SL/fpzgqTNxWtM8NQU+JS+j6LotFCbNemaMnlo0v4try7/zDldKdrU6RHvHwQYf4YR6J B8HViqsO7TCzg77P5QhEj/iHLoslZpI= X-MC-Unique: CBJ5ZysbPzST3Kn1Md9j_A-1 X-Mimecast-MFC-AGG-ID: CBJ5ZysbPzST3Kn1Md9j_A_1780456948 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 05/16] qapi/docs: make remaining subsection members "private" Date: Tue, 2 Jun 2026 23:21:50 -0400 Message-ID: <20260603032201.993015-6-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457035507158500 Content-Type: text/plain; charset="utf-8" These fields are used to provide error checking and internal logistics and should not be used by a user of the library to directly access documentation sections, so make them private. The "since" field alone is left public, as the qapidoc generator does use this field to pull that section out of the regular flow of the document. Signed-off-by: John Snow --- scripts/qapi/parser.py | 48 +++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index dcc58170bd5..da4756a7424 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -733,17 +733,17 @@ def __init__(self, info: QAPISourceInfo, symbol: Opti= onal[str] =3D None): QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) ] # dicts mapping parameter/feature names to their description - self.args: Dict[str, QAPIDoc.ArgSection] =3D {} - self.features: Dict[str, QAPIDoc.ArgSection] =3D {} + self._args: Dict[str, QAPIDoc.ArgSection] =3D {} + self._features: Dict[str, QAPIDoc.ArgSection] =3D {} # a command's "Returns" and "Errors" section - self.returns: Optional[QAPIDoc.Section] =3D None - self.errors: Optional[QAPIDoc.Section] =3D None + self._returns: Optional[QAPIDoc.Section] =3D None + self._errors: Optional[QAPIDoc.Section] =3D None # "Since" section self.since: Optional[QAPIDoc.Section] =3D None =20 @property def has_features(self) -> bool: - return bool(self.features) + return bool(self._features) =20 def end(self) -> None: for section in self.all_sections: @@ -775,15 +775,15 @@ def new_tagged_section( ) -> None: section =3D self.Section(info, kind) if kind =3D=3D QAPIDoc.Kind.RETURNS: - if self.returns: + if self._returns: raise QAPISemError( info, "duplicated '%s' section" % kind) - self.returns =3D section + self._returns =3D section elif kind =3D=3D QAPIDoc.Kind.ERRORS: - if self.errors: + if self._errors: raise QAPISemError( info, "duplicated '%s' section" % kind) - self.errors =3D section + self._errors =3D section elif kind =3D=3D QAPIDoc.Kind.SINCE: if self.since: raise QAPISemError( @@ -807,16 +807,16 @@ def _new_description( desc[name] =3D section =20 def new_argument(self, info: QAPISourceInfo, name: str) -> None: - self._new_description(info, name, QAPIDoc.Kind.MEMBER, self.args) + self._new_description(info, name, QAPIDoc.Kind.MEMBER, self._args) =20 def new_feature(self, info: QAPISourceInfo, name: str) -> None: - self._new_description(info, name, QAPIDoc.Kind.FEATURE, self.featu= res) + self._new_description(info, name, QAPIDoc.Kind.FEATURE, self._feat= ures) =20 def append_line(self, line: str) -> None: self.all_sections[-1].append_line(line) =20 def connect_member(self, member: 'QAPISchemaMember') -> None: - if member.name not in self.args: + if member.name not in self._args: assert member.info if self.symbol not in member.info.pragma.documentation_excepti= ons: raise QAPISemError(member.info, @@ -827,7 +827,7 @@ def connect_member(self, member: 'QAPISchemaMember') ->= None: =20 section =3D QAPIDoc.ArgSection( self.info, QAPIDoc.Kind.MEMBER, member.name) - self.args[member.name] =3D section + self._args[member.name] =3D section =20 # Determine where to insert stub doc - it should go at the # end of the members section(s), if any. Note that index 0 @@ -839,14 +839,14 @@ def connect_member(self, member: 'QAPISchemaMember') = -> None: index +=3D 1 self.all_sections.insert(index, section) =20 - self.args[member.name].connect(member) + self._args[member.name].connect(member) =20 def connect_feature(self, feature: 'QAPISchemaFeature') -> None: - if feature.name not in self.features: + if feature.name not in self._features: raise QAPISemError(feature.info, "feature '%s' lacks documentation" % feature.name) - self.features[feature.name].connect(feature) + self._features[feature.name].connect(feature) =20 def ensure_returns(self, info: QAPISourceInfo) -> None: =20 @@ -887,18 +887,18 @@ def _insert_near_kind( =20 def check_expr(self, expr: QAPIExpression) -> None: if 'command' in expr: - if self.returns and 'returns' not in expr: + if self._returns and 'returns' not in expr: raise QAPISemError( - self.returns.info, + self._returns.info, "'Returns' section, but command doesn't return anythin= g") else: - if self.returns: + if self._returns: raise QAPISemError( - self.returns.info, + self._returns.info, "'Returns' section is only valid for commands") - if self.errors: + if self._errors: raise QAPISemError( - self.errors.info, + self._errors.info, "'Errors' section is only valid for commands") =20 def check(self) -> None: @@ -918,5 +918,5 @@ def check_args_section( "do" if len(bogus) > 1 else "does" )) =20 - check_args_section(self.args, 'member') - check_args_section(self.features, 'feature') + check_args_section(self._args, 'member') + check_args_section(self._features, 'feature') --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457011; cv=none; d=zohomail.com; s=zohoarc; b=OKiZI1Ayr61XHqjHgsCHfnwV8j/QnEejPBkERI37JqxxMnKBl0A4FabW5MiQLBzUpqhLfvvbH7rS4VIdsl87vJdhgX6YN+BtTEACgPStxeVMUgXKGnVr99n/PGlSV4QkitpyLY8vc2GqvlmYqyMZiBI7gffAD8hMFhVfzhf/z1c= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457011; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=d6doVMe7e1Q7JlWfRBYUrZgsyQrjHY+nvl3g1E7JrqM=; b=KFsJ0BrEyAvO9bFFUhwhb69B1YoCegjVE4POQjBOF6t5RsQIFsPRqniUncgtWk4Ce9nTXOHx+ve+/i0dj1FoTXWsK8wWlfL/iJ+Jo8fJI8j3mUFMaBygliG5hD2mHd9Ig9ZLw7rpZ46tVmQ8xsEVrqNc0Khrwyi0FwC1wYqGgpA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780457011727552.4250392396214; Tue, 2 Jun 2026 20:23:31 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcBm-0000Gn-Qk; Tue, 02 Jun 2026 23:22:42 -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 1wUcBk-0000Di-HO for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:40 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUcBj-0002Qq-0G for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:40 -0400 Received: from mx-prod-mc-06.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-63-t31tBrUOMdCLX6G2jRVeoQ-1; Tue, 02 Jun 2026 23:22:34 -0400 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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id F38741801238; Wed, 3 Jun 2026 03:22:32 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 2724F3000233; Wed, 3 Jun 2026 03:22:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456958; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=d6doVMe7e1Q7JlWfRBYUrZgsyQrjHY+nvl3g1E7JrqM=; b=YcBo3J5Zmxbvee1ueOcHQSrc3jMNRGi7FLWsSgPYonlWPNgCQBsaVb3pnXIlot5PxYll13 Z/8cP7AmWw//Nzki6rPF+/Lj8vDONDC1i/m12p2BHUpvmqr3tmnfUiRWWMW6nXY2bl69jI OVSoBDbmbLLxYAe8uiifcZYqa7mCYdY= X-MC-Unique: t31tBrUOMdCLX6G2jRVeoQ-1 X-Mimecast-MFC-AGG-ID: t31tBrUOMdCLX6G2jRVeoQ_1780456953 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 06/16] qapi/docs: fix comment phrasing Date: Tue, 2 Jun 2026 23:21:51 -0400 Message-ID: <20260603032201.993015-7-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457013460158500 Content-Type: text/plain; charset="utf-8" Plaintext sections can be one or more paragraphs, the original comment was a mistake. Signed-off-by: John Snow --- scripts/qapi/parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index da4756a7424..d8068bb1bf6 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -631,7 +631,7 @@ def get_doc(self) -> 'QAPIDoc': line =3D self.get_doc_indented(doc) no_more_args =3D True else: - # plain paragraph + # plain paragraph(s) doc.ensure_untagged_section(self.info) doc.append_line(line) line =3D self.get_doc_paragraph(doc) --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457066; cv=none; d=zohomail.com; s=zohoarc; b=J/+rQB/A3vlmM/sRBtTqJaRKstkfaz5jrTU6RpZAsMJonoiDZtb94iaIx+WLaF+BhyDoNbvNYvhnSDMKv3SRjLelA316J2zU0iexHZaI6y2rYrqgTpEYHa+XDRFT9qMoOsx6o/aldxe45eZ9qub3eXHQ5b5cZcxSTRIJXfgcgLk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457066; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=Q6G8ieSNPc0xcSVEK59e57gLX+A/vEMuKvzW9P7RxR8=; b=FCEckOUYzemL1dmeQQWDFliPmaf4jkQRraYTRoS73u28IgM3Gw1bR7htfCTsNeKU8lvY7YK/rvNf+Vp0Jaw5M5sM8WSXlrgP322s7Ag2l2oSO2hY5y3gez9Ok4qyjEbU3Ui7UKsnLHXDTAJolgDUa0b1JLx0AIF6tFpA+RqcWDs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780457066045579.6117276658238; Tue, 2 Jun 2026 20:24:26 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcBp-0000HG-Nn; Tue, 02 Jun 2026 23:22:45 -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 1wUcBo-0000Gz-5P for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:44 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUcBm-0002RG-Jr for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:43 -0400 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-209-EkwrgxI3PXma3pggyeOchw-1; Tue, 02 Jun 2026 23:22:38 -0400 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 53E6D1805A1E; Wed, 3 Jun 2026 03:22:37 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 7EE5C3000232; Wed, 3 Jun 2026 03:22:33 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456962; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Q6G8ieSNPc0xcSVEK59e57gLX+A/vEMuKvzW9P7RxR8=; b=SnTav6Z0vR9o6CZQYk4qMBFcg0u2MjxG26AvA0/5NeJT0yAExkD5MFvFYcKXSA6nscwh/z 78y3J/kH686Au9rJRYjfFhopPyKrqJFS00NT2CtWnA8MQ9v+rWAMoMK1Xhk0zfCgYfkGFq SjlrsB/uHbTVug6sMcXD3UwSi72GoWM= X-MC-Unique: EkwrgxI3PXma3pggyeOchw-1 X-Mimecast-MFC-AGG-ID: EkwrgxI3PXma3pggyeOchw_1780456957 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 07/16] qapi/docs: add "Intro" section Date: Tue, 2 Jun 2026 23:21:52 -0400 Message-ID: <20260603032201.993015-8-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457068503154100 Content-Type: text/plain; charset="utf-8" This patch adds an "Intro" doc section, intended to eventually replace the "Plain" doc section alongside a forthcoming "Details" section. For now, this section is not actually instantiated or used, but subsequent patches will slowly convert the leading introductory sections of QAPIDoc documentation to use this new section. A main motivation of this series of changes is to more explicitly delineate the "Introductory" documentation for each QAPI definition for the sake of the inliner. When inlining members, examples, and details from multiple QAPIDoc sections, we will want to omit the "Introductory" text from inlined definitions while keeping notes, caution boxes, examples, and so on. This new section facilitates that. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 2 +- scripts/qapi/parser.py | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index c2f09bac16c..1f7c15b7075 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -368,7 +368,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> = None: for i, section in enumerate(sections): section.text =3D self.reformat_arobase(section.text) =20 - if section.kind =3D=3D QAPIDoc.Kind.PLAIN: + if section.kind.name in ("PLAIN", "INTRO"): self.visit_paragraph(section) elif section.kind =3D=3D QAPIDoc.Kind.MEMBER: assert isinstance(section, QAPIDoc.ArgSection) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index d8068bb1bf6..97e7dacb0fd 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -681,6 +681,7 @@ class Kind(enum.Enum): ERRORS =3D 4 SINCE =3D 5 TODO =3D 6 + INTRO =3D 7 =20 @staticmethod def from_string(kind: str) -> 'QAPIDoc.Kind': @@ -748,7 +749,7 @@ def has_features(self) -> bool: def end(self) -> None: for section in self.all_sections: section.text =3D section.text.strip('\n') - if section.kind !=3D QAPIDoc.Kind.PLAIN and section.text =3D= =3D '': + if not (section.kind.name in ("INTRO", "PLAIN") or section.tex= t): raise QAPISemError( section.info, "text required after '%s:'" % section.ki= nd) =20 --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457003; cv=none; d=zohomail.com; s=zohoarc; b=TsyEHcAJIrYKo7fo0PlBJ1w8XM+gVdQ3Pg5o0GMnshacaoFCsZdNzA03VGxcllJ9prKS0IwgHB15avMAd7rKmihD8w61Acbzy7fV1Smdd0cCzjnJ/7arT0qgAnrDDhz3yNbDIUjZz/FkJVJjYdH7AU+G0VkrludnJ0GsAA8OUuU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457003; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=AQ9gxAk0ZVxirQ/nsQerUhE6EQtniOZuya0ID+1Nzys=; b=Q8d5VVXchIFBLXGE8SMLzlPy6SDcz8gC93xAojHwbn1u98zjgQu2mHuXry9KeCsNIwQU38dfV4lRhBsn+fX3bBp0rySIN+IeRbHaIIBEi3Ug4HvUhENLr+GLY3ZOqMTPNPJw2nNtTgun89RcgDNJLYbw5u0ye02bOkHbTLUjnfo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 178045700388347.55654684992055; Tue, 2 Jun 2026 20:23:23 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcBs-0000I1-Cd; Tue, 02 Jun 2026 23:22:48 -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 1wUcBr-0000Hq-Km for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:47 -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 1wUcBq-0002Rr-5p for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:47 -0400 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-612-aWCrBmcdPd-UAwC4WslHFQ-1; Tue, 02 Jun 2026 23:22:43 -0400 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-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8D5D61956080; Wed, 3 Jun 2026 03:22:41 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D4BF630001A1; Wed, 3 Jun 2026 03:22:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456965; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=AQ9gxAk0ZVxirQ/nsQerUhE6EQtniOZuya0ID+1Nzys=; b=dYOwv+RhHVWY+L2eW330+aIJGn1bMu7YUmWU4GXruXILYEQHUpEDwjN3hY1beqx4nay4Zk pfo9wi8ZRQfF3PjfkE4v9AUyu6t2GU0daNgF/a+4NeFbLLbl4cCFr1m4WjICjaMo+DeW2M RTEnU3XbtG5ih4RGcwC5rQEOb2HHE3s= X-MC-Unique: aWCrBmcdPd-UAwC4WslHFQ-1 X-Mimecast-MFC-AGG-ID: aWCrBmcdPd-UAwC4WslHFQ_1780456961 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 08/16] qapi/parser: move _insert_near_kind() method Date: Tue, 2 Jun 2026 23:21:53 -0400 Message-ID: <20260603032201.993015-9-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457005548158500 Content-Type: text/plain; charset="utf-8" Move this function out from underneath `ensure_returns` and make it available for general purpose use as an object method instead. This is purely a scope-level patch with no functional changes. Signed-off-by: John Snow --- scripts/qapi/parser.py | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 97e7dacb0fd..261f8ba9f8b 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -816,6 +816,22 @@ def new_feature(self, info: QAPISourceInfo, name: str)= -> None: def append_line(self, line: str) -> None: self.all_sections[-1].append_line(line) =20 + def _insert_near_kind( + self, + kind: 'QAPIDoc.Kind', + new_sect: 'QAPIDoc.Section', + after: bool =3D False, + ) -> bool: + """Insert or append a new doc section at a specific point.""" + for idx, sect in enumerate(reversed(self.all_sections)): + if sect.kind =3D=3D kind: + pos =3D len(self.all_sections) - idx - 1 + if after: + pos +=3D 1 + self.all_sections.insert(pos, new_sect) + return True + return False + def connect_member(self, member: 'QAPISchemaMember') -> None: if member.name not in self._args: assert member.info @@ -850,28 +866,13 @@ def connect_feature(self, feature: 'QAPISchemaFeature= ') -> None: self._features[feature.name].connect(feature) =20 def ensure_returns(self, info: QAPISourceInfo) -> None: - - def _insert_near_kind( - kind: QAPIDoc.Kind, - new_sect: QAPIDoc.Section, - after: bool =3D False, - ) -> bool: - for idx, sect in enumerate(reversed(self.all_sections)): - if sect.kind =3D=3D kind: - pos =3D len(self.all_sections) - idx - 1 - if after: - pos +=3D 1 - self.all_sections.insert(pos, new_sect) - return True - return False - if any(s.kind =3D=3D QAPIDoc.Kind.RETURNS for s in self.all_sectio= ns): return =20 # Stub "Returns" section for undocumented returns value stub =3D QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) =20 - if any(_insert_near_kind(kind, stub, after) for kind, after in ( + if any(self._insert_near_kind(kind, stub, after) for kind, after i= n ( # 1. If arguments, right after those. (QAPIDoc.Kind.MEMBER, True), # 2. Elif errors, right *before* those. --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457013; cv=none; d=zohomail.com; s=zohoarc; b=S5h0xKItQ0sDDtC5xR5MFT96/ZLDXqzlL7510BxpfJwKl70+V80K3W0Qdd2Y2ABFNvQUdR5hh+ajiWJjhVuznEcMfevS6xKGpbsiWuwwSp5odvolpEiXRmQgODSxWDD925/SCs3i2vulxVDrWB2YHqqAM6wqx2qd9NqkbeUGwvU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457013; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=+hD1Dsfeq3wbpu+XarOy5/xB10detZhBbaziffW8q5I=; b=joC+KksYgRZykci89taZXrnbsBS2hZV4qP3MvdQnhXD1E3lqChkkAYUEkHCLJZO6vgSAntnrbCe8A0Mg4B4dnDE8Mah1M/z5C1TkS95HjLXxJiNyZL1Fv/2GcBqT+OMOHLjoweZy8Oagmc5M4LJqbcKW7BdhCgibQSbJJf9nWdA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780457013849895.671869060301; Tue, 2 Jun 2026 20:23:33 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcC0-0000lb-BX; Tue, 02 Jun 2026 23:22:56 -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 1wUcBy-0000e3-7L for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:54 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUcBv-0002SU-Pm for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:53 -0400 Received: from mx-prod-mc-06.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-259-NqggjbLmMyiLB_On5y6-qA-1; Tue, 02 Jun 2026 23:22:47 -0400 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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 0C6C8180044D; Wed, 3 Jun 2026 03:22:46 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id C227D3000203; Wed, 3 Jun 2026 03:22:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456971; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=+hD1Dsfeq3wbpu+XarOy5/xB10detZhBbaziffW8q5I=; b=dQROwjKcI30OwQSBG5mjrzJk+DBsH0LSz/Yh1GCbTTM9OR8xYBEUM0+uHqWIIXh34alFUB jK5KPon4EK77M1JVmYOqnLoQtnWiC/L0zr3NeRQQeDyJJ9oMxXvaxiVDKxDgM2yKnyJTby Sb+jIrnpTTy7m2GO2/oz72dSj791h/Y= X-MC-Unique: NqggjbLmMyiLB_On5y6-qA-1 X-Mimecast-MFC-AGG-ID: NqggjbLmMyiLB_On5y6-qA_1780456966 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 09/16] qapi/docs: adjust stub member insertion algorithm Date: Tue, 2 Jun 2026 23:21:54 -0400 Message-ID: <20260603032201.993015-10-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457015409158500 Content-Type: text/plain; charset="utf-8" A forthcoming patch removes the implicit PLAIN section that always starts a QAPIDoc section list. Further future changes begin converting "PLAIN" sections to "INTRO" sections. To accommodate this, the insertion algorithm that places stub and dummy members must be adjusted to cope with not only the finished state, but temporary intermediate states while the series is merged. This algorithm can handle zero-or-more PLAIN *or* INTRO sections at the beginning of a QAPIDoc object, in contrast to the previous algorithm which assumed and relied upon there being always one PLAIN section at the beginning of every QAPIDoc section list. In other words: (PLAIN | INTRO)* This does not impact what the parser itself will actually produce. As of this patch, the parser will still always generate QAPIDoc section lists that start with precisely one PLAIN section (whether or not it is empty), followed by the remaining sections. Those remaining sections may or may not include additional PLAIN sections, but never two such sections contiguously as the parser will always treat that layout as one PLAIN section consisting of multiple paragraph(s). In other other words: This insertion algorithm is more lenient than the parser, but this is on purpose for flexibility mid-stream as we convert QAPI to using explicit introductory sections. The allowed order of sections will eventually become strictly enforced in the parser, which will in turn allow dramatic simplifications to the insertion algorithm. This only exists as transitory code until we are able to enforce that order. Fear not: the intermediate rest output before and after this patch are byte identical, so failing all else, we at least know it doesn't make anything worse. Lastly, because we have three places in the code that need to insert stub/dummy sections, we take the opportunity to consolidate this code to handle all three cases with one function. This winds up necessitating the qapidoc.py generator actually modify the section list to insert a "dummy" member that acts as a placeholder for "The members of ..." text. While it looks like a code smell to modify the caller's argument, it is ultimately safe because the QAPI Schema object is re-parsed and re-constructed in memory for each individual process that needs to operate on it. In other words, the Sphinx document generator already does have "its own copy" of the section lists, so it is "safe" to modify here without regards to other consumers of the QAPIDoc objects. It only *looks* like it smells bad. Ultimately, this code will also be removed once the inliner is merged, so it is only a temporary aesthetic issue regardless. That's my story and I'm sticking to it. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 42 ++++++++++++++++-------------- scripts/qapi/parser.py | 58 +++++++++++++++++++++++++++++------------- 2 files changed, 64 insertions(+), 36 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 1f7c15b7075..16ad15fe94f 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -349,30 +349,38 @@ def _get_target( ) =20 def visit_sections(self, ent: QAPISchemaDefinition) -> None: + # Generate a placeholder right after the member section(s) which + # may be used to generate documentation for "The members of..." + # pointers in the rendered document. + # + # This is a temporary hack until the inliner is merged. Note + # that although we modify the caller's section list, the + # Sphinx document generator has its own copy of the parsed + # schema in memory, so this action does not interfere with + # other users of the QAPISchema or QAPIDoc objects outside of + # the document generator. Fishy, but not harmful. + if ent.doc: + ent.doc.append_member_stub( + QAPIDoc.ArgSection( + ent.doc.info, QAPIDoc.Kind.MEMBER, "q_dummy" + ) + ) + sections =3D ent.doc.all_sections if ent.doc else [] =20 - # Determine the index location at which we should generate - # documentation for "The members of ..." pointers. This should - # go at the end of the members section(s) if any. Note that - # index 0 is assumed to be a plain intro section, even if it is - # empty; and that a members section if present will always - # immediately follow the opening PLAIN section. - gen_index =3D 1 - if len(sections) > 1: - while sections[gen_index].kind =3D=3D QAPIDoc.Kind.MEMBER: - gen_index +=3D 1 - if gen_index >=3D len(sections): - break - # Add sections in source order: - for i, section in enumerate(sections): + for section in sections: section.text =3D self.reformat_arobase(section.text) =20 if section.kind.name in ("PLAIN", "INTRO"): self.visit_paragraph(section) elif section.kind =3D=3D QAPIDoc.Kind.MEMBER: assert isinstance(section, QAPIDoc.ArgSection) - self.visit_member(section) + if section.name =3D=3D "q_dummy": + # Generate "The members of ..." entries if necessary + self._insert_member_pointer(ent) + else: + self.visit_member(section) elif section.kind =3D=3D QAPIDoc.Kind.FEATURE: assert isinstance(section, QAPIDoc.ArgSection) self.visit_feature(section) @@ -386,10 +394,6 @@ def visit_sections(self, ent: QAPISchemaDefinition) ->= None: else: assert False =20 - # Generate "The members of ..." entries if necessary: - if i =3D=3D gen_index - 1: - self._insert_member_pointer(ent) - self.ensure_blank_line() =20 # Transmogrification core methods diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 261f8ba9f8b..406edf6aa9d 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -832,6 +832,42 @@ def _insert_near_kind( return True return False =20 + def _insert_after_intro( + self, + section: 'QAPIDoc.Section', + ) -> None: + """ + Insert a section immediately after the intro section. + + While we convert PLAIN sections to INTRO sections, all + contiguous INTRO/PLAIN sections at the start of a QAPIDoc + section list are treated as "the intro". + + Once INTRO conversion is complete, this helper will no longer be + needed and ``_insert_near_kind(QAPIDoc.Kind.INTRO, ...)`` will + be sufficient. + """ + index =3D 0 + for index, ref_section in enumerate(self.all_sections): + if ref_section.kind.name in ("PLAIN", "INTRO"): + continue + break + else: + index +=3D 1 + + self.all_sections.insert(index, section) + + def append_member_stub(self, stub: 'QAPIDoc.Section') -> None: + + """ + Append a stub section after any Member sections. + """ + if self._insert_near_kind(QAPIDoc.Kind.MEMBER, stub, True): + return + + # No MEMBER sections present. Insert after INTRO/PLAIN sections. + self._insert_after_intro(stub) + def connect_member(self, member: 'QAPISchemaMember') -> None: if member.name not in self._args: assert member.info @@ -841,20 +877,10 @@ def connect_member(self, member: 'QAPISchemaMember') = -> None: % (member.role, member.name)) # Insert stub documentation section for missing member docs. # TODO: drop when undocumented members are outlawed - - section =3D QAPIDoc.ArgSection( + stub_section =3D QAPIDoc.ArgSection( self.info, QAPIDoc.Kind.MEMBER, member.name) - self._args[member.name] =3D section - - # Determine where to insert stub doc - it should go at the - # end of the members section(s), if any. Note that index 0 - # is assumed to be an untagged intro section, even if it is - # empty. - index =3D 1 - if len(self.all_sections) > 1: - while self.all_sections[index].kind =3D=3D QAPIDoc.Kind.ME= MBER: - index +=3D 1 - self.all_sections.insert(index, section) + self._args[member.name] =3D stub_section + self.append_member_stub(stub_section) =20 self._args[member.name].connect(member) =20 @@ -882,10 +908,8 @@ def ensure_returns(self, info: QAPISourceInfo) -> None: )): return =20 - # Otherwise, it should go right after the intro. The intro - # is always the first section and is always present (even - # when empty), so we can insert directly at index=3D1 blindly. - self.all_sections.insert(1, stub) + # Otherwise, it should go right after the intro. + self._insert_after_intro(stub) =20 def check_expr(self, expr: QAPIExpression) -> None: if 'command' in expr: --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780456988; cv=none; d=zohomail.com; s=zohoarc; b=eiFvbaVrWi13WyYZyNuaEgLT5vDOua6mva5bPui+dXx5mrMchShfDFs1cpH7Hira0cV3eHTOu34NjtMviFtuhgGYjRZAL5W9gCFk2RhLma0cRznrRRPniYw7cyPSUpaN2tLCQY92vYaM9DbAy1XUonXvDo8KgkbrPJRgXjkRUdk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780456988; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=LcOyyMvF31+cUE24n3jEGHkdEH2/+jIBhFBTj92e3UY=; b=L6ifcjsfutkifuobK2VFNnqd8LThvhXN/yaYNtlARMf9ScGZbf4NPiuihZKjemfYvK/pD+ZXFDogwNoE06Ie7BeIEci0241CxkchOlszdPpan1KXbVwxL5A/hPBzhlTJJPu8abFhlKMC9YaV9jVU00qnaj75FYOjXSJEvXgl4qY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780456988407710.3010088432461; Tue, 2 Jun 2026 20:23:08 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcC2-0000t5-Uc; Tue, 02 Jun 2026 23:22: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 1wUcC1-0000mz-0q for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22: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 1wUcBz-0002T1-Fn for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:22:56 -0400 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-696-Kq0itHC5OQWClD1o2AoIRQ-1; Tue, 02 Jun 2026 23:22:51 -0400 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 3E90F1800635; Wed, 3 Jun 2026 03:22:50 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id A103C30001A1; Wed, 3 Jun 2026 03:22:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456974; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=LcOyyMvF31+cUE24n3jEGHkdEH2/+jIBhFBTj92e3UY=; b=C72/bIZceT4DbfbCLYhBlWVtzSZ4UeaKjAwiWU1WogUGa1BDGbdPCBgLFYbL+fqAgwLI8a BVslLOOLi/bmrtZUbou6rHf97rJbwaohJ6LRvuA8cIM4F71YFusyPznu8LdwfXwaX5r97B YPJY6WbqyNDePYXsJdfGNcjp7uhYByY= X-MC-Unique: Kq0itHC5OQWClD1o2AoIRQ-1 X-Mimecast-MFC-AGG-ID: Kq0itHC5OQWClD1o2AoIRQ_1780456970 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 10/16] qapi/docs: remove implicit Plain section Date: Tue, 2 Jun 2026 23:21:55 -0400 Message-ID: <20260603032201.993015-11-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H5=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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780456989273158500 Content-Type: text/plain; charset="utf-8" Prior to this patch, we always create an empty Plain section. Removing this allows us to gradually phase out the "Plain" section in favor of "Intro" and "Details" sections while keeping "Plain" around for the interim churn during the series - meaning that we don't actually know at __init__ time which type of section we'll have first. Signed-off-by: John Snow --- scripts/qapi/parser.py | 4 +--- tests/qapi-schema/doc-good.out | 14 -------------- 2 files changed, 1 insertion(+), 17 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 406edf6aa9d..4beec4f9eda 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -730,9 +730,7 @@ def __init__(self, info: QAPISourceInfo, symbol: Option= al[str] =3D None): # definition doc's symbol, None for free-form doc self.symbol: Optional[str] =3D symbol # the sections in textual order - self.all_sections: List[QAPIDoc.Section] =3D [ - QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) - ] + self.all_sections: List[QAPIDoc.Section] =3D [] # dicts mapping parameter/feature names to their description self._args: Dict[str, QAPIDoc.ArgSection] =3D {} self._features: Dict[str, QAPIDoc.ArgSection] =3D {} diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index b9829e2f841..16f44221771 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -106,8 +106,6 @@ Examples: - *verbatim* - {braces} doc symbol=3DEnum - Plain - Member=3Done The _one_ {and only}, description on the same line Member=3Dtwo @@ -119,8 +117,6 @@ a member feature Plain @two is undocumented doc symbol=3DBase - Plain - Member=3Dbase1 description starts on a new line, minimally indented @@ -138,16 +134,10 @@ a feature Feature=3Dmember-feat a member feature doc symbol=3DVariant2 - Plain - doc symbol=3DObject - Plain - Feature=3Dunion-feat1 a feature doc symbol=3DAlternate - Plain - Member=3Di description starts on the same line remainder indented the same @@ -161,8 +151,6 @@ doc freeform Another subsection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D doc symbol=3Dcmd - Plain - Member=3Darg1 description starts on a new line, indented @@ -223,7 +211,5 @@ another feature =20 <- ... has no title ... doc symbol=3DEVT_BOXED - Plain - Feature=3Dfeat3 a feature --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780456997; cv=none; d=zohomail.com; s=zohoarc; b=MWTV1zAA5/dlnrilHJGn6ErqJIUVSUvSu8CKy845Pq1xgE7r2lQPODP81OSQOol/D9LmavtxJCDMdw5upCehZZUqaGScgbDc9H+yFGysl+j+l/Z684wqveEDWpxiPlMx9KiaOkfAUMAlOOd4+TKiu8xbkDZh1yWNQZXbg2F1ct4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780456997; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=kX3FxRPn/1GMTvTitODOSutiU72JvTg6Lqj0zxSzIL8=; b=YUyJDMsR8uaI0xFFrodrhIRjevALNrNjn/Fxamrok2w1fLZNyyII//DgbJJWuJzbFjRrUThQ8MtZNmsge+pDbZCOb72XjLtsk6s0GC3xunGPG2rNOuGkH3Gvou/jrhSlB4hm0Oa+PeP0hxV/gdCJy4wSEnaMvarKynPp0A41XlQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780456997250154.8029308745298; Tue, 2 Jun 2026 20:23:17 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcC9-00016e-83; Tue, 02 Jun 2026 23:23:05 -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 1wUcC7-0000zq-8E for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:03 -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 1wUcC5-0002Vi-Lc for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:02 -0400 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-172-fCV2as8tNsqRsInm4xreDQ-1; Tue, 02 Jun 2026 23:22:57 -0400 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 464F51805A10; Wed, 3 Jun 2026 03:22:56 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id CE5F830001A1; Wed, 3 Jun 2026 03:22:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456981; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=kX3FxRPn/1GMTvTitODOSutiU72JvTg6Lqj0zxSzIL8=; b=ZjkBL03J44XeNUbZ4XFhm1L614DQJBVUoMyuiKCo7vA13uBpj7EAvkW5Do4lUR//8BKqf4 bD9/IdJfuaN2x7ClNpF+UMJn5A/BKb+BC+yOcHB+cWHxuLVPPKoNpfZRyiqZEwocadjD3r JkEjyrUnaLuvGrCVB2m68wKrca//J+Y= X-MC-Unique: fCV2as8tNsqRsInm4xreDQ-1 X-Mimecast-MFC-AGG-ID: fCV2as8tNsqRsInm4xreDQ_1780456976 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 11/16] qapi/docs: add rendering for INTRO sections Date: Tue, 2 Jun 2026 23:21:56 -0400 Message-ID: <20260603032201.993015-12-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H5=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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780456999468158500 Content-Type: text/plain; charset="utf-8" Amend the qapidoc generator to handle and render INTRO sections. The only real difference here from other sections is that we need to dedent the text so it renders correctly. Members and Features are also indented, but do not require a dedent() because they are always used in tandem with an rST construct that forms the start of a new indented block; there is coincidental harmony. Plaintext sections, however, do not start their own block and thus need to be dedented to prevent accidentally rendering them as a blockquote or a syntax error. This dedent transformation on the text does not reflow the text, so source line information remains accurate, and the "blame" chain of custody for sphinx rST parsing error messages continues to be correct even through this transformation. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 16ad15fe94f..317dc44b1b8 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -35,6 +35,7 @@ from pathlib import Path import re import sys +import textwrap from typing import TYPE_CHECKING =20 from docutils import nodes @@ -150,8 +151,15 @@ def add_lines( self, content: str, info: QAPISourceInfo, + dedent: bool =3D False, ) -> None: lines =3D content.splitlines(True) + + if dedent: + lines =3D textwrap.dedent(content).splitlines(True) + else: + lines =3D content.splitlines(True) + for i, line in enumerate(lines): self.add_line_raw(line, info.fname, info.line + i) =20 @@ -223,13 +231,14 @@ def reformat_arobase(text: str) -> str: =20 # Transmogrification helpers =20 - def visit_paragraph(self, section: QAPIDoc.Section) -> None: + def visit_plaintext(self, section: QAPIDoc.Section) -> None: # Squelch empty paragraphs. if not section.text: return =20 + dedent =3D bool(section.kind =3D=3D QAPIDoc.Kind.INTRO) self.ensure_blank_line() - self.add_lines(section.text, section.info) + self.add_lines(section.text, section.info, dedent) self.ensure_blank_line() =20 def visit_member(self, section: QAPIDoc.ArgSection) -> None: @@ -373,7 +382,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> = None: section.text =3D self.reformat_arobase(section.text) =20 if section.kind.name in ("PLAIN", "INTRO"): - self.visit_paragraph(section) + self.visit_plaintext(section) elif section.kind =3D=3D QAPIDoc.Kind.MEMBER: assert isinstance(section, QAPIDoc.ArgSection) if section.name =3D=3D "q_dummy": --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457019; cv=none; d=zohomail.com; s=zohoarc; b=Nwo+AitNeEtlCuNkS5WiAv/YF1EMAxDMjuRMnvrN5/UbDHsxYFrllfCoNFNpWoexVf+o6q5Ak9GPm2IPYFzM1V14QO+mouG2Oo7Y00XAjh2CpP6r7MNeN8h4ISg7FIK0EgVXLdogmdyoTVZymvvVPJ5U9E6b8pPt2US9fQWlRwA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457019; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=znQw9jpRWqjwZVYhsNI4Yox1/+J7o4qsUJvcg4/0PIM=; b=lCTePASjKxGXaDCR6D4jxUj7D4NO+Vz6D+9kOoB8A0IiAZ0PiMDs4MmH/Xc2Vika/WYphGaqNYh0luBbY2WARHitWV+3oFRYea5aB/Wg7vv5ZckiSG5z3PN78efD1eS+AZmbR5VN1IbwuBtx7/dcFeibTaUEQ2uBS9d8tBk4fTw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780457019635809.1575301778931; Tue, 2 Jun 2026 20:23:39 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcCE-0001Q9-QF; Tue, 02 Jun 2026 23:23:10 -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 1wUcCD-0001KZ-EZ for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:09 -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 1wUcCB-0002XF-JL for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:09 -0400 Received: from mx-prod-mc-06.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-610-RGZPcKPjP1ifyK6m0sQj-A-1; Tue, 02 Jun 2026 23:23:02 -0400 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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id F422F1800870; Wed, 3 Jun 2026 03:23:00 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id A51853000233; Wed, 3 Jun 2026 03:22:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456986; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=znQw9jpRWqjwZVYhsNI4Yox1/+J7o4qsUJvcg4/0PIM=; b=Nfrk+knOw95hiqwa1oOFAFV1lbNxrGYG4drcNfPcEAaQtzaUa1//xIEOMxzMtLC2RUEVYg sUmtfvNG6JohhhppOpPvs9VJrCQzUbHRnPztCHWexe1K9gy93/hXPKStQk/chlC5PBzBU7 4xvs2A7Bl3b0XNPYJBOl+d3fxDXsru0= X-MC-Unique: RGZPcKPjP1ifyK6m0sQj-A-1 X-Mimecast-MFC-AGG-ID: RGZPcKPjP1ifyK6m0sQj-A_1780456981 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 12/16] qapi/docs: add "Intro" section parsing Date: Tue, 2 Jun 2026 23:21:57 -0400 Message-ID: <20260603032201.993015-13-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H5=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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457021421158500 Content-Type: text/plain; charset="utf-8" Add parsing for explicit Intro section syntax. A side effect of this patch is that we will (currently) always create an empty Intro section, similar to how we used to have an empty Plain section. The tests are adjusted accordingly, rendered document output does not change at all. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 16 +++++++--------- scripts/qapi/parser.py | 4 ++-- tests/qapi-schema/doc-good.out | 18 ++++++++++++++++++ 3 files changed, 27 insertions(+), 11 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 3a632b4a648..b1cc5b5f0db 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -984,11 +984,11 @@ definition it documents. When documentation is required (see pragma_ 'doc-required'), every definition must have documentation. =20 -Definition documentation starts with a line naming the definition, -followed by an optional overview, a description of each argument (for -commands and events), member (for structs and unions), branch (for -alternates), or value (for enums), a description of each feature (if -any), and finally optional tagged sections. +Definition documentation starts with a description naming the +definition with an optional indented overview, a description of each +argument (for commands and events), member (for structs and unions), +branch (for alternates), or value (for enums), a description of each +feature (if any), and finally optional tagged sections. =20 Descriptions start with '\@name:'. The description text must be indented like this:: @@ -1093,8 +1093,7 @@ Examples of complete definition documentation:: =20 ## # @BlockStats: - # - # Statistics of a virtual block device or a block backing device. + # Statistics of a virtual block device or a block backing device. # # @device: If the stats are for a virtual block device, the name # corresponding to the virtual block device. @@ -1111,8 +1110,7 @@ Examples of complete definition documentation:: =20 ## # @query-blockstats: - # - # Query the @BlockStats for all virtual block devices. + # Query the @BlockStats for all virtual block devices. # # @query-nodes: If true, the command will query all the block nodes # ... explain, explain ... diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 4beec4f9eda..2afbf6a9c81 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -542,8 +542,8 @@ def get_doc(self) -> 'QAPIDoc': if not symbol: raise QAPIParseError(self, "name required after '@'") doc =3D QAPIDoc(info, symbol) - self.accept(False) - line =3D self.get_doc_line() + doc.all_sections.append(QAPIDoc.Section(info, QAPIDoc.Kind.INT= RO)) + line =3D self.get_doc_indented(doc) no_more_args =3D False =20 while line is not None: diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 16f44221771..371dd25ffc7 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -106,6 +106,8 @@ Examples: - *verbatim* - {braces} doc symbol=3DEnum + Intro + Member=3Done The _one_ {and only}, description on the same line Member=3Dtwo @@ -117,10 +119,14 @@ a member feature Plain @two is undocumented doc symbol=3DBase + Intro + Member=3Dbase1 description starts on a new line, minimally indented doc symbol=3DVariant1 + Intro + Plain A paragraph =20 @@ -134,10 +140,16 @@ a feature Feature=3Dmember-feat a member feature doc symbol=3DVariant2 + Intro + doc symbol=3DObject + Intro + Feature=3Dunion-feat1 a feature doc symbol=3DAlternate + Intro + Member=3Di description starts on the same line remainder indented the same @@ -151,6 +163,8 @@ doc freeform Another subsection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D doc symbol=3Dcmd + Intro + Member=3Darg1 description starts on a new line, indented @@ -198,6 +212,8 @@ Note:: Since 2.10 doc symbol=3Dcmd-boxed + Intro + Plain If you're bored enough to read this, go see a video of boxed cats Feature=3Dcmd-feat1 @@ -211,5 +227,7 @@ another feature =20 <- ... has no title ... doc symbol=3DEVT_BOXED + Intro + Feature=3Dfeat3 a feature --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457034; cv=none; d=zohomail.com; s=zohoarc; b=FfQmTz2O1wTLsnpFbYV1NDYTla8LgBU6jWyt8sQVPOvKZ56rLoLa/hJYv1/1ShOkPzWA3/P3Ys1RflCVyH3xdXbTDuYQjuDxx0g0ktHxAKsbcvhIVA/OwCNbV74qLtvqCkMhVvjyPuP24HszHlg6hRalElECMAVKC3JfyK2akCs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457034; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=nvqj62ChjUbf5S0H0WqS9HcGif8t3al8v8FsPHFDyGE=; b=P/D5tdn4sXHesfMFX2ur9mwPvumnm+Hx4kUPpM/llufPHOaUaEHlYJK9RYxU0RQlkPFPOcaClKBoCFmA/FPcKIiCii3VUsmOKib0YrSo7VrJzFMK/X2hU7EMjQRqFFg8tCEdjLABtZRh4DXaxSObt9xUR7xfZBwhhx0P3dsWbPk= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780457034435689.1006449614853; Tue, 2 Jun 2026 20:23:54 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcCO-0001ZS-N7; Tue, 02 Jun 2026 23:23:22 -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 1wUcCG-0001RQ-5l for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:12 -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 1wUcCE-0002Ze-Qn for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:11 -0400 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-378-bE5vYHWiNkSbzvyhas89Bg-1; Tue, 02 Jun 2026 23:23:06 -0400 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 47E231805A16; Wed, 3 Jun 2026 03:23:05 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 4492130001A1; Wed, 3 Jun 2026 03:23:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456990; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=nvqj62ChjUbf5S0H0WqS9HcGif8t3al8v8FsPHFDyGE=; b=WHgYxlob8EY5IZmwUt9EwBR77NcbiF/kulymsPugSevLjiBiy4Tb4t5cGgG0XZs+UCrb2f OtekAh+tXY2skgpHJepL3IoEhnAzU/gY2jV9hHLdkMRCmvbrm3bkjdFqmO2ba7AXWeAnl1 nOjkKNpmo0H7xkVIMkyx+aHYMhmv3rc= X-MC-Unique: bE5vYHWiNkSbzvyhas89Bg-1 X-Mimecast-MFC-AGG-ID: bE5vYHWiNkSbzvyhas89Bg_1780456985 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 13/16] qapi: convert intro sections for accelerator.json Date: Tue, 2 Jun 2026 23:21:58 -0400 Message-ID: <20260603032201.993015-14-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H5=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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457035434158500 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow --- qapi/accelerator.json | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/qapi/accelerator.json b/qapi/accelerator.json index b59df378664..efc0fa81418 100644 --- a/qapi/accelerator.json +++ b/qapi/accelerator.json @@ -13,8 +13,7 @@ =20 ## # @KvmInfo: -# -# Information about support for KVM acceleration +# Information about support for KVM acceleration # # @enabled: true if KVM acceleration is active # @@ -26,8 +25,7 @@ =20 ## # @query-kvm: -# -# Return information about KVM acceleration +# Return information about KVM acceleration # # Features: # @@ -46,8 +44,7 @@ =20 ## # @x-accel-stats: -# -# Query accelerator statistics +# Query accelerator statistics # # Features: # @@ -63,8 +60,7 @@ =20 ## # @Accelerator: -# -# Information about support for MSHV acceleration +# Information about support for MSHV acceleration # # @hvf: Apple Hypervisor.framework # @@ -88,8 +84,7 @@ =20 ## # @AcceleratorInfo: -# -# Information about support for various accelerators +# Information about support for various accelerators # # @enabled: the accelerator that is in use # @@ -102,8 +97,7 @@ =20 ## # @query-accelerators: -# -# Return information about accelerators +# Return information about accelerators # # Returns: @AcceleratorInfo # --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457028; cv=none; d=zohomail.com; s=zohoarc; b=GjZREDRLC3fS+WzRfesRySgwws6xLIvjrHZG9Mq3uu0GTMhPwLB5EqtZx1sfBXptyYuFoylV4hHrnRAoCy+3KH2VLPl1QuLn7N5RNnnfXYywUYDrYy0ty0ivNg7nU87oigGrlCqi98lIMC4voaMUBw7P6jBThZr45R2qb9ACNFE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457028; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=VM1rLFGjColtnWu6GvZAwBXS6W0rnnyuFBdpHvgA9sQ=; b=OJp5d1PHlsgY+ZLJLqjLcFZ0MVc0O6vO2XstF/ealiXRsJKjmE6whlEz/S8zO5Sa9zRhskVh+NAtwiq+5dcf/Asu1WJgeCJQvE7dqJZ8gwbZwNbpMbOZ7VFa15FUa3oIfr4uk9jKm07/C5u8lEt2XI+M7umGnsdOc4dEh4+2J7g= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780457028950775.7228968154269; Tue, 2 Jun 2026 20:23:48 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcCS-0001ez-Oj; Tue, 02 Jun 2026 23:23:24 -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 1wUcCK-0001Yd-Jc for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:16 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wUcCJ-0002aK-Aq for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:16 -0400 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-591-Vtb4d3M7OhWiaDnzWarhVw-1; Tue, 02 Jun 2026 23:23:11 -0400 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-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 9C5101956096; Wed, 3 Jun 2026 03:23:09 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 7ED0230001A1; Wed, 3 Jun 2026 03:23:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456994; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=VM1rLFGjColtnWu6GvZAwBXS6W0rnnyuFBdpHvgA9sQ=; b=Yxaen3QuVy3jfDQAk2kaHSPgdW91FLPxM9P6V8WFlPw9hw77Gh1g9Z9J9RAqljr76ey6wk us6r9oZCf+Ga3DagFitlvhu0FBrajx7Q1yfvhe3+WQwlH8Y/BA9cUzpkk2bjZ/1a+8e6jM A7bjshmBTCJQnxUwkbU5QvrcKstnQzk= X-MC-Unique: Vtb4d3M7OhWiaDnzWarhVw-1 X-Mimecast-MFC-AGG-ID: Vtb4d3M7OhWiaDnzWarhVw_1780456989 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 14/16] qapi: convert intro sections for acpi-hest.json Date: Tue, 2 Jun 2026 23:21:59 -0400 Message-ID: <20260603032201.993015-15-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457031967154100 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow --- qapi/acpi-hest.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/qapi/acpi-hest.json b/qapi/acpi-hest.json index a01f1dee095..8db804df197 100644 --- a/qapi/acpi-hest.json +++ b/qapi/acpi-hest.json @@ -13,8 +13,8 @@ =20 ## # @inject-ghes-v2-error: -# -# Inject an error with additional ACPI 6.1 GHESv2 error information +# Inject an error with additional ACPI 6.1 GHESv2 error +# information # # @cper: contains a base64 encoded string with raw data for a single # CPER record with Generic Error Status Block, Generic Error Data --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457067; cv=none; d=zohomail.com; s=zohoarc; b=Ctf0zqO7iFW1rcwKF5/EjjJBrK9qkpe0NHSIFjTzF7uvls0Ed+2LuOJqmHhW9Zu+SU3YtFwkDlki0RRHG8yELJt/gcAqCI0eM6xd4ucpZzN4uIt+yB6LvaGc09J67209rEAwQE81Vmbbpp4rzTgtwb3XpLVEI4iUMdr4FFyaYTo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457067; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=Fjt0nKIoMX/lOpK/Cw8uE3rBIm1wNU+6Z3KCnX7JfPg=; b=daMihQGJik5xpP6np7Ze3Qlki9gCHc9DYfnPb7F6VRV9s0qAuQJQn6U7EHVc8cKIUCrjeOEBQwLnj9gwtsuT3Bzzis/9LTuGP2ry+FvPWFYC7puaHjQQzMJTszEBcPcMh5a0Tirk2D5EljskKy6rmIsmpl/H6IuM+0TetOD2HWs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1780457067192303.6925007238965; Tue, 2 Jun 2026 20:24:27 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcCX-0001m2-58; Tue, 02 Jun 2026 23:23:29 -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 1wUcCP-0001dh-Vt for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:22 -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 1wUcCO-0002c8-C2 for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:21 -0400 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-210-LFN77XXwONWJWLgt0xFzUg-1; Tue, 02 Jun 2026 23:23:15 -0400 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-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id D76C2195608A; Wed, 3 Jun 2026 03:23:13 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D117630001A1; Wed, 3 Jun 2026 03:23:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780456999; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Fjt0nKIoMX/lOpK/Cw8uE3rBIm1wNU+6Z3KCnX7JfPg=; b=L/Tev6F1cN5dmiMgbDb/fVVseZgwdY3qygyXRgcwCk6l+LIPM/SxYS5EzMVap48nq56ETS MbV7Qko32QLIUNriCjm+qvhyTB6tT6Or8if4Lby8CFVsu5dOr5tmKSgBZhoaGXYnd0rqgp VLv/EaAzYj5oqyZO6Tq2kO4b2AGjN6U= X-MC-Unique: LFN77XXwONWJWLgt0xFzUg-1 X-Mimecast-MFC-AGG-ID: LFN77XXwONWJWLgt0xFzUg_1780456994 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 15/16] qapi: convert intro sections for acpi.json Date: Tue, 2 Jun 2026 23:22:00 -0400 Message-ID: <20260603032201.993015-16-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457067579158500 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow --- qapi/acpi.json | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/qapi/acpi.json b/qapi/acpi.json index 906b3687a55..82e82d7cf89 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -13,8 +13,7 @@ =20 ## # @AcpiTableOptions: -# -# Specify an ACPI table on the command line to load. +# Specify an ACPI table on the command line to load. # # At most one of @file and @data can be specified. The list of files # specified by any one of them is loaded and concatenated in order. @@ -81,10 +80,9 @@ =20 ## # @ACPIOSTInfo: -# -# OSPM Status Indication for a device. For description of possible -# values of @source and @status fields see "_OST (OSPM Status -# Indication)" chapter of ACPI5.0 spec. +# OSPM Status Indication for a device. For description +# of possible values of @source and @status fields see "_OST (OSPM +# Status Indication)" chapter of ACPI5.0 spec. # # @device: device ID associated with slot # @@ -107,9 +105,8 @@ =20 ## # @query-acpi-ospm-status: -# -# Return a list of `ACPIOSTInfo` for devices that support status -# reporting via ACPI _OST method. +# Return a list of `ACPIOSTInfo` for devices +# that support status reporting via ACPI _OST method. # # Since: 2.1 # @@ -126,8 +123,7 @@ =20 ## # @ACPI_DEVICE_OST: -# -# Emitted when guest executes ACPI _OST method. +# Emitted when guest executes ACPI _OST method. # # @info: OSPM Status Indication # --=20 2.54.0 From nobody Mon Jun 8 06:38:14 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1780457047; cv=none; d=zohomail.com; s=zohoarc; b=LZSh4MbsgvvhDIRrFanBU612wmaRFapDO41zhM0YCqst/AN9ZKUYB8gWMln274xpID+nvuUuiEK6JMplslTzN2rG6UvUECQ5S1HaGSlbFw7gp+ccqgEe9V9i01tZOt0Y7XbVgb6VrgU4npky1qwOvJG5v/JtnJE//+HNvMJPT/w= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1780457047; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=Z31RfUFoOPTVXn0OWibG2S+bAOrVagBG2khh+ZxyXL0=; b=mC5oHCiDfYUPYd/EC0IiMAT1U2Tcg8V2S9sW85hyiOhH4/jRX62suag4+phsSzVMGTsTqhTYj1mA6B02wOWg3O663/xpse2cMuFrLldIcWZMP7GTRxp3UTw0kvkecTKmIZq6uz3O97seyivAyjeDznHZ+QjtE3h3BdDSZc4O2qw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 17804570472461009.4730947669041; Tue, 2 Jun 2026 20:24:07 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wUcCa-0001zH-3P; Tue, 02 Jun 2026 23:23:32 -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 1wUcCT-0001jQ-96 for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:26 -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 1wUcCR-0002cv-H0 for qemu-devel@nongnu.org; Tue, 02 Jun 2026 23:23:25 -0400 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-316-N59WQh1bMXW_Qq8VVXmKGA-1; Tue, 02 Jun 2026 23:23:18 -0400 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-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 2BEFD195608A; Wed, 3 Jun 2026 03:23:17 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.74]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 1850030001A1; Wed, 3 Jun 2026 03:23:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1780457002; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Z31RfUFoOPTVXn0OWibG2S+bAOrVagBG2khh+ZxyXL0=; b=KrPC+EBcqyI8iEAwmgQFkwden0/vKJAzLm1hKknmxPAZ4Oz1lvRh8EXEHG/4v/tkqEfQJo TF1Asj0fudrdpHgD9tV8VaDN8K7Yjep7fTuNmCSEVpEV7Jun5qQw6nDwPIeFcNDJ2soLGP C96vpX9yda2NNCuwjmidH2cLr3uq3R8= X-MC-Unique: N59WQh1bMXW_Qq8VVXmKGA-1 X-Mimecast-MFC-AGG-ID: N59WQh1bMXW_Qq8VVXmKGA_1780456997 From: John Snow To: qemu-devel@nongnu.org Cc: Ani Sinha , Michael Roth , Igor Mammedov , John Snow , Peter Maydell , Eric Blake , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Markus Armbruster , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , Pierrick Bouvier , Richard Henderson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , linux-edac@vger.kernel.org, Cleber Rosa Subject: [PATCH v3 16/16] qapi: convert intro sections for audio.json Date: Tue, 2 Jun 2026 23:22:01 -0400 Message-ID: <20260603032201.993015-17-jsnow@redhat.com> In-Reply-To: <20260603032201.993015-1-jsnow@redhat.com> References: <20260603032201.993015-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1780457050302154100 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow --- qapi/audio.json | 88 ++++++++++++++++++------------------------------- 1 file changed, 32 insertions(+), 56 deletions(-) diff --git a/qapi/audio.json b/qapi/audio.json index 2df87b97101..72190f20993 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -14,9 +14,8 @@ =20 ## # @AudiodevPerDirectionOptions: -# -# General audio backend options that are used for both playback and -# recording. +# General audio backend options that are used for both playback +# and recording. # # @mixing-engine: use QEMU's mixing engine to mix all streams inside # QEMU and convert audio formats when not supported by the @@ -53,8 +52,7 @@ =20 ## # @AudiodevGenericOptions: -# -# Generic driver-specific options. +# Generic driver-specific options. # # @in: options of the capture stream # @@ -69,8 +67,7 @@ =20 ## # @AudiodevDBusOptions: -# -# Options of the D-Bus audio backend. +# Options of the D-Bus audio backend. # # @in: options of the capture stream # @@ -89,9 +86,8 @@ =20 ## # @AudiodevAlsaPerDirectionOptions: -# -# Options of the ALSA backend that are used for both playback and -# recording. +# Options of the ALSA backend that are used for both playback and +# recording. # # @dev: the name of the ALSA device to use (default 'default') # @@ -111,8 +107,7 @@ =20 ## # @AudiodevAlsaOptions: -# -# Options of the ALSA audio backend. +# Options of the ALSA audio backend. # # @in: options of the capture stream # @@ -130,8 +125,7 @@ =20 ## # @AudiodevSndioOptions: -# -# Options of the sndio audio backend. +# Options of the sndio audio backend. # # @in: options of the capture stream # @@ -152,9 +146,8 @@ =20 ## # @AudiodevCoreaudioPerDirectionOptions: -# -# Options of the Core Audio backend that are used for both playback -# and recording. +# Options of the Core Audio backend that are used for both +# playback and recording. # # @buffer-count: number of buffers # @@ -167,8 +160,7 @@ =20 ## # @AudiodevCoreaudioOptions: -# -# Options of the coreaudio audio backend. +# Options of the coreaudio audio backend. # # @in: options of the capture stream # @@ -183,8 +175,7 @@ =20 ## # @AudiodevDsoundOptions: -# -# Options of the DirectSound audio backend. +# Options of the DirectSound audio backend. # # @in: options of the capture stream # @@ -203,9 +194,8 @@ =20 ## # @AudiodevJackPerDirectionOptions: -# -# Options of the JACK backend that are used for both playback and -# recording. +# Options of the JACK backend that are used for both playback and +# recording. # # @server-name: select from among several possible concurrent server # instances (default: environment variable $JACK_DEFAULT_SERVER if @@ -237,8 +227,7 @@ =20 ## # @AudiodevJackOptions: -# -# Options of the JACK audio backend. +# Options of the JACK audio backend. # # @in: options of the capture stream # @@ -253,9 +242,8 @@ =20 ## # @AudiodevOssPerDirectionOptions: -# -# Options of the OSS backend that are used for both playback and -# recording. +# Options of the OSS backend that are used for both playback and +# recording. # # @dev: file name of the OSS device (default '/dev/dsp') # @@ -275,8 +263,7 @@ =20 ## # @AudiodevOssOptions: -# -# Options of the OSS audio backend. +# Options of the OSS audio backend. # # @in: options of the capture stream # @@ -305,9 +292,8 @@ =20 ## # @AudiodevPaPerDirectionOptions: -# -# Options of the Pulseaudio backend that are used for both playback -# and recording. +# Options of the Pulseaudio backend that are used for both +# playback and recording. # # @name: name of the sink/source to use # @@ -330,8 +316,7 @@ =20 ## # @AudiodevPaOptions: -# -# Options of the PulseAudio audio backend. +# Options of the PulseAudio audio backend. # # @in: options of the capture stream # @@ -349,9 +334,8 @@ =20 ## # @AudiodevPipewirePerDirectionOptions: -# -# Options of the PipeWire backend that are used for both playback and -# recording. +# Options of the PipeWire backend that are used for both playback +# and recording. # # @name: name of the sink/source to use # @@ -374,8 +358,7 @@ =20 ## # @AudiodevPipewireOptions: -# -# Options of the PipeWire audio backend. +# Options of the PipeWire audio backend. # # @in: options of the capture stream # @@ -390,9 +373,8 @@ =20 ## # @AudiodevSdlPerDirectionOptions: -# -# Options of the SDL audio backend that are used for both playback and -# recording. +# Options of the SDL audio backend that are used for both playback +# and recording. # # @buffer-count: number of buffers (default 4) # @@ -405,8 +387,7 @@ =20 ## # @AudiodevSdlOptions: -# -# Options of the SDL audio backend. +# Options of the SDL audio backend. # # @in: options of the recording stream # @@ -421,8 +402,7 @@ =20 ## # @AudiodevWavOptions: -# -# Options of the wav audio backend. +# Options of the wav audio backend. # # @in: options of the capture stream # @@ -440,8 +420,7 @@ =20 ## # @AudioFormat: -# -# An enumeration of possible audio formats. +# An enumeration of possible audio formats. # # @u8: unsigned 8 bit integer # @@ -464,8 +443,7 @@ =20 ## # @AudiodevDriver: -# -# An enumeration of possible audio backend drivers. +# An enumeration of possible audio backend drivers. # # @jack: JACK audio backend (since 5.1) # @@ -488,8 +466,7 @@ =20 ## # @Audiodev: -# -# Options of an audio backend. +# Options of an audio backend. # # @id: identifier of the backend # @@ -534,8 +511,7 @@ =20 ## # @query-audiodevs: -# -# Return information about audiodev configuration +# Return information about audiodev configuration # # Since: 8.0 ## --=20 2.54.0