From nobody Mon Feb 9 02:02:30 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=1748024781; cv=none; d=zohomail.com; s=zohoarc; b=GFt1G5Wu1JX03KfWoY4m9Qnum/5sn22ZF5WILW5mDG7fMppGoaTPXN7uAVvMaJHiOl9bC4XiLEi++hnKvtgucSi70mAxWQhR3b412/DG80m6UA2rJj2NeKGxYLGdFI35x8pOFRSrVhswwKREfvfsOh5cINlDWAWYZSOkzynILGg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1748024781; 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=uKODmXhPDHkmnZ7tQP/XsV06+O6RfGOqyeXGqv1TdbY=; b=hb8u1dVBFm6naZ1RVeqHpXZ6c9CA8phXMm11dmgr0tC9WG6ccM6gAbTJfFHq9PiTn/8eUKpufjmQecgcwvs70pe1Woznn42/he5oa2fZ+EDp7J0dJlNJHYGf5U4ieKDI5UoKlyBwULYDytuREarWBlm8Kadaluh+RO1PeXoKC8s= 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 lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1748024781149736.7045742584654; Fri, 23 May 2025 11:26:21 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1uIX5D-0000gm-MO; Fri, 23 May 2025 14:25:27 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uIX5B-0000fn-BN for qemu-devel@nongnu.org; Fri, 23 May 2025 14:25: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 1uIX58-00037g-53 for qemu-devel@nongnu.org; Fri, 23 May 2025 14:25:25 -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-689-AG34uMN9Oragr-Y6CSvlOQ-1; Fri, 23 May 2025 14:25:18 -0400 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (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 49920180048E; Fri, 23 May 2025 18:25:14 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.78]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 9B6511944A8B; Fri, 23 May 2025 18:25:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1748024721; 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=uKODmXhPDHkmnZ7tQP/XsV06+O6RfGOqyeXGqv1TdbY=; b=XWA2bOeUA8qcvjuVW5O0TSVAHK6AfOd6Xz+EGU+Hp854lYQyAg8duKrOj5S3RYIVDrRonv foIdAgSHnR4BS/54SfKnmUP6s34Mgx9UlfChThfZTGJhof6CrFpyrdr/lePsxkTp5cXYTc 1d9WDC0lUmvyaJ3a7k8I4soocjRCl4s= X-MC-Unique: AG34uMN9Oragr-Y6CSvlOQ-1 X-Mimecast-MFC-AGG-ID: AG34uMN9Oragr-Y6CSvlOQ_1748024716 From: John Snow To: qemu-devel@nongnu.org Cc: Kevin Wolf , Peter Maydell , Yanan Wang , Jiri Pirko , Marcel Apfelbaum , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Lukas Straub , Peter Xu , Michael Roth , Jason Wang , Stefan Hajnoczi , Eric Blake , qemu-trivial@nongnu.org, Gerd Hoffmann , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Michael Tokarev , qemu-block@nongnu.org, Mads Ynddal , "Michael S. Tsirkin" , Stefan Berger , Paolo Bonzini , John Snow , Eduardo Habkost , Fabiano Rosas , Zhao Liu , Zhenwei Pi , Ani Sinha , Markus Armbruster , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Hanna Reitz , Vladimir Sementsov-Ogievskiy , "Gonglei (Arei)" , Laurent Vivier Subject: [PATCH v3 1/4] docs/qapi-domain: add return-nodesc Date: Fri, 23 May 2025 14:24:39 -0400 Message-ID: <20250523182442.54469-2-jsnow@redhat.com> In-Reply-To: <20250523182442.54469-1-jsnow@redhat.com> References: <20250523182442.54469-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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=lists.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: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.287, 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_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1748024783486116600 Content-Type: text/plain; charset="utf-8" This form is used to annotate a return type without an accompanying description, for when there is no "Returns:" information in the source doc, but we have a return type we want to generate a cross-reference to. The syntax is: :return-nodesc: TypeName It's primarily necessary because Sphinx always expects both a type and a description for the prior form and will format it accordingly. To have a reasonable rendering when the body is missing, we need to use a different info field list entirely. Signed-off-by: John Snow Acked-by: Michael S. Tsirkin --- docs/devel/qapi-domain.rst | 30 ++++++++++++++++++++++++++++++ docs/sphinx/qapi_domain.py | 8 ++++++++ 2 files changed, 38 insertions(+) diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 11238723c2d..204abb72ff4 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -242,6 +242,36 @@ Example:: } =20 =20 +``:return-nodesc:`` +------------------- + +Document the return type of a QAPI command, without an accompanying descri= ption. + +:availability: This field list is only available in the body of the + Command directive. +:syntax: ``:return-nodesc: type`` +:type: `sphinx.util.docfields.Field + `_ + + +Example:: + + .. qapi:command:: query-replay + :since: 5.2 + + Retrieve the record/replay information. It includes current + instruction count which may be used for ``replay-break`` and + ``replay-seek`` commands. + + :return-nodesc: ReplayInfo + + .. qmp-example:: + + -> { "execute": "query-replay" } + <- { "return": { + "mode": "play", "filename": "log.rr", "icount": 220414 } + } + ``:value:`` ----------- =20 diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index ebc46a72c61..f561dc465f8 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -532,6 +532,14 @@ class QAPICommand(QAPIObject): names=3D("return",), can_collapse=3DTrue, ), + # :return-nodesc: TypeName + CompatField( + "returnvalue", + label=3D_("Return"), + names=3D("return-nodesc",), + bodyrolename=3D"type", + has_arg=3DFalse, + ), ] ) =20 --=20 2.48.1 From nobody Mon Feb 9 02:02:30 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=1748024793; cv=none; d=zohomail.com; s=zohoarc; b=jSx85Lao1spOlRP/fZ5XxhBowQAv356S5gdSRnNGKf8xNEI75S0FCTxPOVdrLaGKrTOkedR0SVJO5Qfw54/LZzMTsNRB/2oCoj2ylQoMtdVvJu2p+iTENWMbjLRV9Jy+Susphmi4fTsFr09E2kctGiDPG0sXpYLZ1IiP9cbLxVU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1748024793; 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=fA8iNN1LwEHSlpRiWf75slmpOQWaEBgpIFanj9juOH8=; b=BcE5dmKQiMkCJaEQRRF7F2ISFWDcIE4eix0M9u/ndKeBRp65LTG5lP6ZDCwneS+SoaBgSzoBIrLLpAuHpynI9Ce6xifWf7gUNqovLbtXc+TTA91B3XRlvc3zmL6LhMyUtYTVmW0k5TUBdpDq6TRrvaTOZ2IogrXF1mksdFASh1Q= 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 lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1748024793625533.4136249543135; Fri, 23 May 2025 11:26:33 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1uIX5a-00015O-4O; Fri, 23 May 2025 14:25:50 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uIX5X-0000vn-2W for qemu-devel@nongnu.org; Fri, 23 May 2025 14:25: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 1uIX5T-0003A3-B7 for qemu-devel@nongnu.org; Fri, 23 May 2025 14:25:46 -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-646-bFJWH64kPG-xvfNPHjseIg-1; Fri, 23 May 2025 14:25:39 -0400 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (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 CB13A18004AD; Fri, 23 May 2025 18:25:25 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.78]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 1EF8D1944A89; Fri, 23 May 2025 18:25:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1748024742; 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=fA8iNN1LwEHSlpRiWf75slmpOQWaEBgpIFanj9juOH8=; b=DLZ6CP8eHdQp1PZ286MM3r59LhQMbBNG6yehZjaSMU/9pGgTry1X18lBhXWPDFeBwdYTFD K6b8WIpek4p3c4JwiNsyqTrD47ebyRnOivtQdx5WXhjA5ZBpP7EfbFZz1lTo6xmlygJSua oLJKnjCYmE4SUoJok1JfK39IpFiDPd8= X-MC-Unique: bFJWH64kPG-xvfNPHjseIg-1 X-Mimecast-MFC-AGG-ID: bFJWH64kPG-xvfNPHjseIg_1748024727 From: John Snow To: qemu-devel@nongnu.org Cc: Kevin Wolf , Peter Maydell , Yanan Wang , Jiri Pirko , Marcel Apfelbaum , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Lukas Straub , Peter Xu , Michael Roth , Jason Wang , Stefan Hajnoczi , Eric Blake , qemu-trivial@nongnu.org, Gerd Hoffmann , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Michael Tokarev , qemu-block@nongnu.org, Mads Ynddal , "Michael S. Tsirkin" , Stefan Berger , Paolo Bonzini , John Snow , Eduardo Habkost , Fabiano Rosas , Zhao Liu , Zhenwei Pi , Ani Sinha , Markus Armbruster , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Hanna Reitz , Vladimir Sementsov-Ogievskiy , "Gonglei (Arei)" , Laurent Vivier Subject: [PATCH v3 2/4] docs, qapi: generate undocumented return sections Date: Fri, 23 May 2025 14:24:40 -0400 Message-ID: <20250523182442.54469-3-jsnow@redhat.com> In-Reply-To: <20250523182442.54469-1-jsnow@redhat.com> References: <20250523182442.54469-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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=lists.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: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.287, 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_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1748024795535116600 Content-Type: text/plain; charset="utf-8" This patch changes the qapidoc transmogrifier to generate Return value documentation for any command that has a return value but hasn't explicitly documented that return value. Signed-off-by: John Snow Acked-by: Michael S. Tsirkin --- docs/sphinx/qapidoc.py | 14 ++++++++------ scripts/qapi/parser.py | 15 +++++++++++++++ scripts/qapi/schema.py | 3 +++ 3 files changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 8011ac9efaf..627d0b5ff1a 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -255,16 +255,18 @@ def visit_feature(self, section: QAPIDoc.ArgSection) = -> None: def visit_returns(self, section: QAPIDoc.Section) -> None: assert isinstance(self.entity, QAPISchemaCommand) rtype =3D self.entity.ret_type - # q_empty can produce None, but we won't be documenting anything - # without an explicit return statement in the doc block, and we - # should not have any such explicit statements when there is no - # return value. + # return statements will not be present (and won't be + # autogenerated) for any command that doesn't return + # *something*, so ret_type will always be defined here. assert rtype =20 typ =3D self.format_type(rtype) assert typ - assert section.text - self.add_field("return", typ, section.text, section.info) + + if section.text: + self.add_field("return", typ, section.text, section.info) + else: + self.add_lines(f":return-nodesc: {typ}", section.info) =20 def visit_errors(self, section: QAPIDoc.Section) -> None: # FIXME: the formatting for errors may be inconsistent and may diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 949d9e8bff7..6db08f82409 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -815,6 +815,21 @@ def connect_feature(self, feature: 'QAPISchemaFeature'= ) -> None: % feature.name) self.features[feature.name].connect(feature) =20 + def ensure_returns(self, info: QAPISourceInfo) -> None: + if not any(s.kind =3D=3D QAPIDoc.Kind.RETURNS for s in self.all_se= ctions): + + stub =3D QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) + + # Stub "Returns" section for undocumented returns value. + # Insert stub after the last non-PLAIN section. + for sect in reversed(self.all_sections): + if sect.kind !=3D QAPIDoc.Kind.PLAIN: + idx =3D self.all_sections.index(sect) + 1 + self.all_sections.insert(idx, stub) + break + else: + self.all_sections.append(stub) + def check_expr(self, expr: QAPIExpression) -> None: if 'command' in expr: if self.returns and 'returns' not in expr: diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index cbe3b5aa91e..3abddea3525 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -1062,6 +1062,9 @@ def connect_doc(self, doc: Optional[QAPIDoc] =3D None= ) -> None: if self.arg_type and self.arg_type.is_implicit(): self.arg_type.connect_doc(doc) =20 + if self.ret_type and self.info: + doc.ensure_returns(self.info) + def visit(self, visitor: QAPISchemaVisitor) -> None: super().visit(visitor) visitor.visit_command( --=20 2.48.1 From nobody Mon Feb 9 02:02:30 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=1748024783; cv=none; d=zohomail.com; s=zohoarc; b=WUCzfGIBF7tHf/2jggdTY8lAPYHqpVVaEZI+WsYfHSAreZXkJtjuXjdg4RY6SkJWi4AvaEp/KJpWxmf7eel1wtpAF/G/S7a0dSFvHfTgWRirPpXGdvpPsplXmyz96mRiCtU9k7ZblqH/60MiXMvDZgxcfmBY1suflBkBWW8N8Lg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1748024783; 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=cTbygMn3ywE+Ces/p27Xolnn9lLMtj9b73kuLQ/0Cfo=; b=DzP+QHGC/Y2B1Fm8AHm1D6v9QlGlGss5Wq1CPyMXTtV+4EHgNMHE40wyqHT4sOxOB2IJDqhr/MjuyY0loWyH6m+1utEBQrETORVTboQXKIPSwZDSHVi4Xk/xVg4S9548CViGjw6+/SctELFWOHgiOUISQsdkbNVW0e6GAk2Aty0= 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 lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1748024783878607.5446656794102; Fri, 23 May 2025 11:26:23 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1uIX5s-0001SG-BN; Fri, 23 May 2025 14:26:08 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uIX5d-0001A6-IT for qemu-devel@nongnu.org; Fri, 23 May 2025 14:25:53 -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 1uIX5a-0003Bs-1K for qemu-devel@nongnu.org; Fri, 23 May 2025 14:25:53 -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-161-pUMH-rHWOpSOwLyFpl5xpQ-1; Fri, 23 May 2025 14:25:42 -0400 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (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 5E93A1955E79; Fri, 23 May 2025 18:25:35 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.78]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 183231944A8B; Fri, 23 May 2025 18:25:25 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1748024749; 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=cTbygMn3ywE+Ces/p27Xolnn9lLMtj9b73kuLQ/0Cfo=; b=VI0mY5Q8ws9H/3sQApOM6U96B4AZP+UQY6o+wmqD648c41y8ttigVYIVbGzU9vGHX4J6pV chlJN8vGrXL01dLgWLE6KmW0PyhuKRuBCJkhc2qMwuMlr60LBrhhyEYA4xGpaB1yxR5Lqs M/abeQ+RX8teba1FOMsSlf7ZuHJA3+E= X-MC-Unique: pUMH-rHWOpSOwLyFpl5xpQ-1 X-Mimecast-MFC-AGG-ID: pUMH-rHWOpSOwLyFpl5xpQ_1748024735 From: John Snow To: qemu-devel@nongnu.org Cc: Kevin Wolf , Peter Maydell , Yanan Wang , Jiri Pirko , Marcel Apfelbaum , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Lukas Straub , Peter Xu , Michael Roth , Jason Wang , Stefan Hajnoczi , Eric Blake , qemu-trivial@nongnu.org, Gerd Hoffmann , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Michael Tokarev , qemu-block@nongnu.org, Mads Ynddal , "Michael S. Tsirkin" , Stefan Berger , Paolo Bonzini , John Snow , Eduardo Habkost , Fabiano Rosas , Zhao Liu , Zhenwei Pi , Ani Sinha , Markus Armbruster , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Hanna Reitz , Vladimir Sementsov-Ogievskiy , "Gonglei (Arei)" , Laurent Vivier Subject: [PATCH v3 3/4] qapi: remove trivial "Returns:" sections Date: Fri, 23 May 2025 14:24:41 -0400 Message-ID: <20250523182442.54469-4-jsnow@redhat.com> In-Reply-To: <20250523182442.54469-1-jsnow@redhat.com> References: <20250523182442.54469-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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=lists.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: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.287, 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_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1748024785528116600 Content-Type: text/plain; charset="utf-8" The new qapidoc transmogrifier can generate "Returns" statements with type information just fine, so we can remove it from the source where it doesn't add anything particularly novel or helpful and just repeats the type info. This patch does not touch Returns: lines that add some information (potentially helpful, potentially not) but repeats the type information to remove that type. Signed-off-by: John Snow Acked-by: Michael S. Tsirkin --- qapi/audio.json | 2 -- qapi/block-core.json | 8 -------- qapi/char.json | 8 -------- qapi/cryptodev.json | 2 -- qapi/machine-target.json | 2 -- qapi/machine.json | 22 ---------------------- qapi/migration.json | 12 ------------ qapi/misc-target.json | 12 ------------ qapi/misc.json | 7 ------- qapi/rocker.json | 4 ---- qapi/run-state.json | 2 -- qapi/tpm.json | 4 ---- qapi/ui.json | 8 -------- qapi/virtio.json | 2 -- qapi/yank.json | 1 - 15 files changed, 96 deletions(-) diff --git a/qapi/audio.json b/qapi/audio.json index dd5a58d13e6..d49ca4cae47 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -535,8 +535,6 @@ # # Returns information about audiodev configuration # -# Returns: array of @Audiodev -# # Since: 8.0 ## { 'command': 'query-audiodevs', diff --git a/qapi/block-core.json b/qapi/block-core.json index b1937780e19..92b2e368b72 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1949,8 +1949,6 @@ # @flat: Omit the nested data about backing image ("backing-image" # key) if true. Default is false (Since 5.0) # -# Returns: the list of BlockDeviceInfo -# # Since: 2.0 # # .. qmp-example:: @@ -2464,9 +2462,6 @@ # # @unstable: This command is meant for debugging. # -# Returns: -# BlockDirtyBitmapSha256 -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found or if hashing has failed, GenericError @@ -6157,9 +6152,6 @@ # # @name: optional the snapshot's name to be deleted # -# Returns: -# SnapshotInfo -# # Errors: # - If @device is not a valid block device, GenericError # - If snapshot not found, GenericError diff --git a/qapi/char.json b/qapi/char.json index dde2f9538f8..6a82db0d156 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -36,8 +36,6 @@ # # Returns information about current character devices. # -# Returns: a list of @ChardevInfo -# # Since: 0.14 # # .. qmp-example:: @@ -82,8 +80,6 @@ # # Returns information about character device backends. # -# Returns: a list of @ChardevBackendInfo -# # Since: 2.0 # # .. qmp-example:: @@ -772,8 +768,6 @@ # # @backend: backend type and parameters # -# Returns: ChardevReturn. -# # Since: 1.4 # # .. qmp-example:: @@ -812,8 +806,6 @@ # # @backend: new backend type and parameters # -# Returns: ChardevReturn. -# # Since: 2.10 # # .. qmp-example:: diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json index 04d0e21d209..e8371b9d950 100644 --- a/qapi/cryptodev.json +++ b/qapi/cryptodev.json @@ -96,8 +96,6 @@ # # Returns information about current crypto devices. # -# Returns: a list of @QCryptodevInfo -# # Since: 8.0 ## { 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']} diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 426ce4ee82d..e4b464eb1a4 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -391,8 +391,6 @@ # # Return a list of supported virtual CPU definitions # -# Returns: a list of CpuDefinitionInfo -# # Since: 1.2 ## { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'], diff --git a/qapi/machine.json b/qapi/machine.json index c8feb9fe17b..5d5b958d1d4 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -101,8 +101,6 @@ # # Returns information about all virtual CPUs. # -# Returns: list of @CpuInfoFast -# # Since: 2.12 # # .. qmp-example:: @@ -218,8 +216,6 @@ # # @unstable: Argument @compat-props is experimental. # -# Returns: a list of MachineInfo -# # Since: 1.2 # # .. qmp-example:: @@ -268,8 +264,6 @@ # # Return information on the current virtual machine. # -# Returns: CurrentMachineParams -# # Since: 4.0 ## { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' } @@ -291,8 +285,6 @@ # # Return information about the target for this QEMU # -# Returns: QemuTargetInfo -# # Since: 1.2 ## { 'command': 'query-target', 'returns': 'QemuTargetInfo' } @@ -316,8 +308,6 @@ # # Query the guest UUID information. # -# Returns: The @UuidInfo for the guest -# # Since: 0.14 # # .. qmp-example:: @@ -469,8 +459,6 @@ # # Returns information about KVM acceleration # -# Returns: @KvmInfo -# # Since: 0.14 # # .. qmp-example:: @@ -932,8 +920,6 @@ # # Returns information for all memory backends. # -# Returns: a list of @Memdev. -# # Since: 2.1 # # .. qmp-example:: @@ -1049,8 +1035,6 @@ # # TODO: Better documentation; currently there is none. # -# Returns: a list of HotpluggableCPU objects. -# # Since: 2.7 # # .. qmp-example:: @@ -1172,9 +1156,6 @@ # # Return information about the balloon device. # -# Returns: -# @BalloonInfo -# # Errors: # - If the balloon driver is enabled but not functional because # the KVM kernel module cannot support it, KVMMissingCap @@ -1238,9 +1219,6 @@ # Returns the hv-balloon driver data contained in the last received # "STATUS" message from the guest. # -# Returns: -# @HvBalloonInfo -# # Errors: # - If no hv-balloon device is present, guest memory status # reporting is not enabled or no guest memory status report diff --git a/qapi/migration.json b/qapi/migration.json index 8b9c53595c4..b0e9452e7fa 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -286,8 +286,6 @@ # is active there will be another json-object with RAM migration # status. # -# Returns: @MigrationInfo -# # Since: 0.14 # # .. qmp-example:: @@ -537,8 +535,6 @@ # # Returns information about the current migration capabilities status # -# Returns: @MigrationCapabilityStatus -# # Since: 1.2 # # .. qmp-example:: @@ -1322,8 +1318,6 @@ # # Returns information about the current migration parameters # -# Returns: @MigrationParameters -# # Since: 2.4 # # .. qmp-example:: @@ -1904,8 +1898,6 @@ # # Query replication status while the vm is running. # -# Returns: A @ReplicationStatus object showing the status. -# # .. qmp-example:: # # -> { "execute": "query-xen-replication-status" } @@ -1958,8 +1950,6 @@ # # Query COLO status while the vm is running. # -# Returns: A @COLOStatus object showing the status. -# # .. qmp-example:: # # -> { "execute": "query-colo-status" } @@ -2333,8 +2323,6 @@ # # @deprecated: This command is deprecated with no replacement yet. # -# Returns: @MigrationThreadInfo -# # Since: 7.2 ## { 'command': 'query-migrationthreads', diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 42e4a7417dc..94624cb45e0 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -129,8 +129,6 @@ # # Returns information about SEV # -# Returns: @SevInfo -# # Since: 2.12 # # .. qmp-example:: @@ -205,8 +203,6 @@ # This command is used to get the SEV capabilities, and is supported # on AMD X86 platforms only. # -# Returns: SevCapability objects. -# # Since: 2.12 # # .. qmp-example:: @@ -259,8 +255,6 @@ # @mnonce: a random 16 bytes value encoded in base64 (it will be # included in report) # -# Returns: SevAttestationReport objects. -# # Since: 6.1 # # .. qmp-example:: @@ -305,8 +299,6 @@ # This command is ARM-only. It will return a list of GICCapability # objects that describe its capability bits. # -# Returns: a list of GICCapability objects. -# # Since: 2.6 # # .. qmp-example:: @@ -363,8 +355,6 @@ # # Returns information about SGX # -# Returns: @SGXInfo -# # Since: 6.2 # # .. qmp-example:: @@ -382,8 +372,6 @@ # # Returns information from host SGX capabilities # -# Returns: @SGXInfo -# # Since: 6.2 # # .. qmp-example:: diff --git a/qapi/misc.json b/qapi/misc.json index 559b66f2017..de5dd531071 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -56,8 +56,6 @@ # # Return the name information of a guest. # -# Returns: @NameInfo of the guest -# # Since: 0.14 # # .. qmp-example:: @@ -332,9 +330,6 @@ # # @opaque: A free-form string that can be used to describe the fd. # -# Returns: -# @AddfdInfo -# # Errors: # - If file descriptor was not received, GenericError # - If @fdset-id is a negative value, GenericError @@ -415,8 +410,6 @@ # # Return information describing all fd sets. # -# Returns: A list of @FdsetInfo -# # Since: 1.2 # # .. note:: The list of fd sets is shared by all monitor connections. diff --git a/qapi/rocker.json b/qapi/rocker.json index 0c7ef1f77c8..2d2ae3bbafc 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -28,8 +28,6 @@ # # @name: switch name # -# Returns: @Rocker information -# # Since: 2.4 # # .. qmp-example:: @@ -98,8 +96,6 @@ # # @name: port name # -# Returns: a list of @RockerPort information -# # Since: 2.4 # # .. qmp-example:: diff --git a/qapi/run-state.json b/qapi/run-state.json index ce95cfa46b7..ff2d694ee2f 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -119,8 +119,6 @@ # # Query the run status of the VM # -# Returns: @StatusInfo reflecting the VM -# # Since: 0.14 # # .. qmp-example:: diff --git a/qapi/tpm.json b/qapi/tpm.json index a16a72edb98..f749e6869df 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -27,8 +27,6 @@ # # Return a list of supported TPM models # -# Returns: a list of TpmModel -# # Since: 1.5 # # .. qmp-example:: @@ -58,8 +56,6 @@ # # Return a list of supported TPM types # -# Returns: a list of TpmType -# # Since: 1.5 # # .. qmp-example:: diff --git a/qapi/ui.json b/qapi/ui.json index c536d4e5241..46843bdbefa 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -325,8 +325,6 @@ # # Returns information about the current SPICE server # -# Returns: @SpiceInfo -# # Since: 0.14 # # .. qmp-example:: @@ -656,8 +654,6 @@ # # Returns information about the current VNC server # -# Returns: @VncInfo -# # Since: 0.14 # # .. qmp-example:: @@ -687,8 +683,6 @@ # # Returns a list of vnc servers. The list can be empty. # -# Returns: a list of @VncInfo2 -# # Since: 2.3 ## { 'command': 'query-vnc-servers', 'returns': ['VncInfo2'], @@ -1564,8 +1558,6 @@ # # Returns information about display configuration # -# Returns: @DisplayOptions -# # Since: 3.1 ## { 'command': 'query-display-options', diff --git a/qapi/virtio.json b/qapi/virtio.json index d351d2166ef..93c576a21da 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -847,8 +847,6 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtioQueueElement information -# # Since: 7.2 # # .. qmp-example:: diff --git a/qapi/yank.json b/qapi/yank.json index 30f46c97c98..9bd8ecce27f 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -102,7 +102,6 @@ # # Query yank instances. See @YankInstance for more information. # -# Returns: list of @YankInstance # # .. qmp-example:: # --=20 2.48.1 From nobody Mon Feb 9 02:02:30 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=1748024792; cv=none; d=zohomail.com; s=zohoarc; b=iC1MyA0mx+EDxI7pLTIBYvfeB6H+3DuNFfyr+cZnOmObroh/opv51Ai9WXIn9Xz5s8EUWvrJk7K7/nAiv52H7/qmRCnSMjM2/AY5AT8cZ/1/YZ/ID7D7YVNozLuReHqTFhAbuVcOhy+BciStnhvBSXCTPPwW4TaEDDfEFqnO/UE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1748024792; 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=vD9Sq0XGFwT8zKvpjpez4T9cyat1cUwlICoLGsQvhgw=; b=ZlQ2xrEwMVGhCwLjCh2EZAvhqhgDbawTKyjh9v9RKNSJmzR7X2g3ECEVYEnUOA9r6M08lb3WybMv2NVVz653sV2OpZC3rqGLS0RNUiwIMsfz+e0Qe3/IbVzDo2bZSwpvZpxoYdQT9UZNrIdSpeqzjVtnu6+BkVrgRMIFYxbnKyY= 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 lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1748024792611165.82153148511372; Fri, 23 May 2025 11:26:32 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1uIX5t-0001ao-TI; Fri, 23 May 2025 14:26:10 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1uIX5g-0001BT-1E for qemu-devel@nongnu.org; Fri, 23 May 2025 14:25:56 -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 1uIX5c-0003C0-0q for qemu-devel@nongnu.org; Fri, 23 May 2025 14:25:54 -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-328-qSi6WVFJMkqG0sVjU3_MCQ-1; Fri, 23 May 2025 14:25:48 -0400 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (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 C07A31956094; Fri, 23 May 2025 18:25:44 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.78]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 853AF1944A89; Fri, 23 May 2025 18:25:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1748024749; 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=vD9Sq0XGFwT8zKvpjpez4T9cyat1cUwlICoLGsQvhgw=; b=QNM/tEUVI/4MsbYsyEah60nMAPV56w1B4Q3Nmbo4F3Bb+PrV/vpuhpzi5DWg9TuIMm+tMg j/9JCC0CClBApFJB3B/hKU4G5ddlleGPNiVxVXf5okLOGzP26Krex7NKqqIXpwEwNF8096 GnQoiTop4um7mlj/2wlzGBSzn1fAqU8= X-MC-Unique: qSi6WVFJMkqG0sVjU3_MCQ-1 X-Mimecast-MFC-AGG-ID: qSi6WVFJMkqG0sVjU3_MCQ_1748024745 From: John Snow To: qemu-devel@nongnu.org Cc: Kevin Wolf , Peter Maydell , Yanan Wang , Jiri Pirko , Marcel Apfelbaum , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Lukas Straub , Peter Xu , Michael Roth , Jason Wang , Stefan Hajnoczi , Eric Blake , qemu-trivial@nongnu.org, Gerd Hoffmann , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Michael Tokarev , qemu-block@nongnu.org, Mads Ynddal , "Michael S. Tsirkin" , Stefan Berger , Paolo Bonzini , John Snow , Eduardo Habkost , Fabiano Rosas , Zhao Liu , Zhenwei Pi , Ani Sinha , Markus Armbruster , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Hanna Reitz , Vladimir Sementsov-Ogievskiy , "Gonglei (Arei)" , Laurent Vivier Subject: [PATCH v3 4/4] qapi: rephrase return docs to avoid type name Date: Fri, 23 May 2025 14:24:42 -0400 Message-ID: <20250523182442.54469-5-jsnow@redhat.com> In-Reply-To: <20250523182442.54469-1-jsnow@redhat.com> References: <20250523182442.54469-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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=lists.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: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.287, 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_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1748024793690116600 Content-Type: text/plain; charset="utf-8" Well, I tried. Maybe not very hard. Sorry! Signed-off-by: John Snow Acked-by: Michael S. Tsirkin --- qapi/block-core.json | 6 +++--- qapi/block-export.json | 2 +- qapi/block.json | 2 +- qapi/control.json | 5 ++--- qapi/dump.json | 5 ++--- qapi/introspect.json | 6 +++--- qapi/job.json | 2 +- qapi/machine-target.json | 7 +++---- qapi/misc-target.json | 2 +- qapi/misc.json | 5 ++--- qapi/net.json | 2 +- qapi/pci.json | 2 +- qapi/qdev.json | 3 +-- qapi/qom.json | 8 +++----- qapi/stats.json | 2 +- qapi/trace.json | 2 +- qapi/ui.json | 2 +- qapi/virtio.json | 6 +++--- 18 files changed, 31 insertions(+), 38 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 92b2e368b72..eb97b70cd80 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -763,7 +763,7 @@ # # Get a list of BlockInfo for all virtual block devices. # -# Returns: a list of @BlockInfo describing each virtual block device. +# Returns: a list describing each virtual block device. # Filter nodes that were created implicitly are skipped over. # # Since: 0.14 @@ -1168,7 +1168,7 @@ # nodes that were created implicitly are skipped over in this # mode. (Since 2.3) # -# Returns: A list of @BlockStats for each virtual block devices. +# Returns: A list of statistics for each virtual block device. # # Since: 0.14 # @@ -1440,7 +1440,7 @@ # # Return information about long-running block device operations. # -# Returns: a list of @BlockJobInfo for each active block job +# Returns: a list of job info for each active block job # # Since: 1.1 ## diff --git a/qapi/block-export.json b/qapi/block-export.json index c783e01a532..84852606e52 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -472,7 +472,7 @@ ## # @query-block-exports: # -# Returns: A list of BlockExportInfo describing all block exports +# Returns: A list describing all block exports # # Since: 5.2 ## diff --git a/qapi/block.json b/qapi/block.json index e66666f5c64..bdbbe78854f 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -86,7 +86,7 @@ # Returns a list of information about each persistent reservation # manager. # -# Returns: a list of @PRManagerInfo for each persistent reservation +# Returns: a list of manager info for each persistent reservation # manager # # Since: 3.0 diff --git a/qapi/control.json b/qapi/control.json index 336386f79e1..2e45bf25df8 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -93,8 +93,7 @@ # # Returns the current version of QEMU. # -# Returns: A @VersionInfo object describing the current version of -# QEMU. +# Returns: An object describing the current version of QEMU. # # Since: 0.14 # @@ -131,7 +130,7 @@ # # Return a list of supported QMP commands by this server # -# Returns: A list of @CommandInfo for all supported commands +# Returns: A list of all supported commands # # Since: 0.14 # diff --git a/qapi/dump.json b/qapi/dump.json index d7826c0e323..1bd6bacc5ce 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -146,7 +146,7 @@ # # Query latest dump status. # -# Returns: A @DumpStatus object showing the dump status. +# Returns: An object showing the dump status. # # Since: 2.6 # @@ -197,8 +197,7 @@ # # Returns the available formats for dump-guest-memory # -# Returns: A @DumpGuestMemoryCapability object listing available -# formats for dump-guest-memory +# Returns: An object listing available formats for dump-guest-memory # # Since: 2.0 # diff --git a/qapi/introspect.json b/qapi/introspect.json index 01bb242947c..7daec5045fb 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -34,10 +34,10 @@ # string into a specific enum or from one specific type into an # alternate that includes the original type alongside something else. # -# Returns: array of @SchemaInfo, where each element describes an -# entity in the ABI: command, event, type, ... +# Returns: an array where each element describes an entity in the ABI: +# command, event, type, ... # -# The order of the various SchemaInfo is unspecified; however, all +# The order of the various elements is unspecified; however, all # names are guaranteed to be unique (no name will be duplicated # with different meta-types). # diff --git a/qapi/job.json b/qapi/job.json index cfc3beedd21..856dd688f95 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -269,7 +269,7 @@ # # Return information about jobs. # -# Returns: a list with a @JobInfo for each active job +# Returns: a list with info for each active job # # Since: 3.0 ## diff --git a/qapi/machine-target.json b/qapi/machine-target.json index e4b464eb1a4..7d306d8fa56 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -162,8 +162,7 @@ # @modelb: description of the second CPU model to compare, referred to # as "model B" in CpuModelCompareResult # -# Returns: a CpuModelCompareInfo describing how both CPU models -# compare +# Returns: An object describing how both CPU models compare # # Errors: # - if comparing CPU models is not supported @@ -218,7 +217,7 @@ # # @modelb: description of the second CPU model to baseline # -# Returns: a CpuModelBaselineInfo describing the baselined CPU model +# Returns: An object describing the baselined CPU model # # Errors: # - if baselining CPU models is not supported @@ -296,7 +295,7 @@ # # @type: expansion type, specifying how to expand the CPU model # -# Returns: a CpuModelExpansionInfo describing the expanded CPU model +# Returns: An object describing the expanded CPU model # # Errors: # - if expanding CPU models is not supported diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 94624cb45e0..799a4ad1ce1 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -158,7 +158,7 @@ # # Query the SEV guest launch information. # -# Returns: The @SevLaunchMeasureInfo for the guest +# Returns: The guest's SEV guest launch measurement info # # Since: 2.12 # diff --git a/qapi/misc.json b/qapi/misc.json index de5dd531071..3d10aeb215c 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -105,7 +105,7 @@ # declared using the ``-object iothread`` command-line option. It # is always the main thread of the process. # -# Returns: a list of @IOThreadInfo for each iothread +# Returns: a list of info for each iothread # # Since: 2.0 # @@ -509,8 +509,7 @@ # # @option: option name # -# Returns: list of @CommandLineOptionInfo for all options (or for the -# given @option). +# Returns: list of objects for all options (or for the given @option). # # Errors: # - if the given @option doesn't exist diff --git a/qapi/net.json b/qapi/net.json index 310cc4fd190..43739fd0259 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -845,7 +845,7 @@ # # @name: net client name # -# Returns: list of @RxFilterInfo for all NICs (or for the given NIC). +# Returns: list of info for all NICs (or for the given NIC). # # Errors: # - if the given @name doesn't exist diff --git a/qapi/pci.json b/qapi/pci.json index dc85a41d28b..29549d94551 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -175,7 +175,7 @@ # # Return information about the PCI bus topology of the guest. # -# Returns: a list of @PciInfo for each PCI bus. Each bus is +# Returns: a list of info for each PCI bus. Each bus is # represented by a json-object, which has a key with a json-array # of all PCI devices attached to it. Each device is represented # by a json-object. diff --git a/qapi/qdev.json b/qapi/qdev.json index 32c7d100463..5d18fb8e0e0 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -17,8 +17,7 @@ # # @typename: the type name of a device # -# Returns: a list of ObjectPropertyInfo describing a devices -# properties +# Returns: a list describing a devices properties # # .. note:: Objects can create properties at runtime, for example to # describe links between different devices and/or objects. These diff --git a/qapi/qom.json b/qapi/qom.json index 04c118e4d61..44f5f25c19e 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -54,8 +54,7 @@ # @path: the path within the object model. See @qom-get for a # description of this parameter. # -# Returns: a list of @ObjectPropertyInfo that describe the properties -# of the object. +# Returns: a list that describe the properties of the object. # # Since: 1.2 # @@ -178,8 +177,7 @@ # # @abstract: if true, include abstract types in the results # -# Returns: a list of @ObjectTypeInfo or an empty list if no results -# are found +# Returns: a list of types, or an empty list if no results are found # # Since: 1.1 ## @@ -199,7 +197,7 @@ # describe links between different devices and/or objects. These # properties are not included in the output of this command. # -# Returns: a list of ObjectPropertyInfo describing object properties +# Returns: a list describing object properties # # Since: 2.12 ## diff --git a/qapi/stats.json b/qapi/stats.json index 8902ef94e08..7e7f1dabbc3 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -186,7 +186,7 @@ # The arguments are a StatsFilter and specify the provider and objects # to return statistics about. # -# Returns: a list of StatsResult, one for each provider and object +# Returns: a list of statistics, one for each provider and object # (e.g., for each vCPU). # # Since: 7.1 diff --git a/qapi/trace.json b/qapi/trace.json index eb5f63f5135..11f0b5c3427 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -47,7 +47,7 @@ # # @name: Event name pattern (case-sensitive glob). # -# Returns: a list of @TraceEventInfo for the matching events +# Returns: a list of info for the matching events # # Since: 2.2 # diff --git a/qapi/ui.json b/qapi/ui.json index 46843bdbefa..a1015801b1b 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -816,7 +816,7 @@ # # Returns information about each active mouse device # -# Returns: a list of @MouseInfo for each device +# Returns: a list of info for each device # # Since: 0.14 # diff --git a/qapi/virtio.json b/qapi/virtio.json index 93c576a21da..cee0e100d44 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -199,7 +199,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtioStatus of the virtio device +# Returns: Status of the virtio device # # Since: 7.2 # @@ -563,7 +563,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtQueueStatus of the VirtQueue +# Returns: Status of the queue # # .. note:: last_avail_idx will not be displayed in the case where the # selected VirtIODevice has a running vhost device and the @@ -698,7 +698,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtVhostQueueStatus of the vhost_virtqueue +# Returns: Status of the vhost_virtqueue # # Since: 7.2 # --=20 2.48.1