From nobody Sun Dec 14 01:57:44 2025 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=1752210766; cv=none; d=zohomail.com; s=zohoarc; b=ZRrnp63jnftG25m3gzzn6qL58hJvVZnxw3uBBqi/zIFds1dA8XJlsyrR3ADNMquD8dL+ZBBh3uX46HZ4mkp/g90Es6623ckrp6H96YCZYv4zDTDgDqVqUvZXvr4myO8WWi17cEIXlElhw148D4kdQEe8X0ysjVyeq8QCkil2xuU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1752210766; 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=xa077rVFvzC/zL3iOmNcf/FeXENytQE3nonaVEmrN+E=; b=eWIDlcB42DWjmIYLwkwFbW5lTBUI9hvrzU+DDTrvc8M84ulx1qW3S8kXr9ycwE2kmlc7hVUysc3g7ztdR/Q50n+gCffFlSh4r1PERSepZi/NFD2zX+ml+HNVLezdqT8AVMtkQelwY1rvdCeIpJTRxFXgCRKS8PKjAVQSyzsOFdQ= 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 1752210766309447.35936387996526; Thu, 10 Jul 2025 22:12:46 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ua62h-0008Nv-0V; Fri, 11 Jul 2025 01:11: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 1ua62e-0008Eq-2U for qemu-devel@nongnu.org; Fri, 11 Jul 2025 01:11: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 1ua62b-0000Em-UX for qemu-devel@nongnu.org; Fri, 11 Jul 2025 01:11:23 -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-607-5GWakjI2P6--NNkB4Y021g-1; Fri, 11 Jul 2025 01:11: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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 881AC1800366; Fri, 11 Jul 2025 05:11:11 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.46]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 344713000221; Fri, 11 Jul 2025 05:11:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1752210679; 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=xa077rVFvzC/zL3iOmNcf/FeXENytQE3nonaVEmrN+E=; b=OpX0bTdFJQJ3H2/ct6SQ4IeWvQs5aG82Th0bARNllH7uhF7nANl4jjrBeKOkIugS/llpdi RQuRl+zN4nyjxnQ7kQk3NhkGbV1gIJFw5z0HKMvr2Asfth4qHL3K0u0eVdO0Q/RZP3l9Sc Qa2Dj2gcJK1GTbhuMDPgqTDsbAGuGPc= X-MC-Unique: 5GWakjI2P6--NNkB4Y021g-1 X-Mimecast-MFC-AGG-ID: 5GWakjI2P6--NNkB4Y021g_1752210673 From: John Snow To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , "Michael S. Tsirkin" , Eduardo Habkost , Jiri Pirko , Markus Armbruster , Peter Maydell , Ani Sinha , Zhao Liu , Peter Xu , Gerd Hoffmann , Fabiano Rosas , qemu-block@nongnu.org, "Gonglei (Arei)" , Laurent Vivier , Jason Wang , Yanan Wang , qemu-trivial@nongnu.org, Stefan Hajnoczi , Mads Ynddal , Lukas Straub , Marcel Apfelbaum , Kevin Wolf , Vladimir Sementsov-Ogievskiy , Michael Tokarev , Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eric Blake , Hanna Reitz , Zhenwei Pi , Stefan Berger , Michael Roth , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH v6 1/4] docs/qapi-domain: add return-nodesc Date: Fri, 11 Jul 2025 01:10:42 -0400 Message-ID: <20250711051045.51110-2-jsnow@redhat.com> In-Reply-To: <20250711051045.51110-1-jsnow@redhat.com> References: <20250711051045.51110-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=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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_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=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: 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: 1752210766990116600 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: Markus Armbruster --- 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.50.0 From nobody Sun Dec 14 01:57:44 2025 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=1752210783; cv=none; d=zohomail.com; s=zohoarc; b=XJxuArEUyMScT76SPz0ggelb+FBP22xhXrjiJkyCRvd9APoXLEo038haKfOlmUIChfTGXFtFkj9fQ9qoEO7xfUEXfiCqjdPMmH/soCc1x4QgSo9YIgEsUwo7uTr/gVQBbWj5ahPQCGTWWz1dEzyLOVKSYWie1bvPOjDYBES9FQ4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1752210783; 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=A+c8yf1Q9Vf+WIIkpOlmgGLVhW/zsYOfbr5N0Z/epRY=; b=Fq0VViQDZrPhOmIlyVign04t0UXkeKZ5SXH4Cff0B0gTcWYWaraLWdNETBsgH3kd8IUwpttpLWHU5FDStRpENA42GzfNH+t+WqxmsBnv43s9bs878sKXtp6lP53vemFJaQyepsflAa6afMEKQDW2LZW0uBxL5Lr+gXApm2iaGWg= 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 175221078369928.38407135110151; Thu, 10 Jul 2025 22:13:03 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ua62p-0000G5-Cm; Fri, 11 Jul 2025 01:11:35 -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 1ua62m-0000Al-Jf for qemu-devel@nongnu.org; Fri, 11 Jul 2025 01:11:33 -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 1ua62j-0000GZ-VD for qemu-devel@nongnu.org; Fri, 11 Jul 2025 01:11:31 -0400 Received: from mx-prod-mc-04.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-380-YpImRccMMHWX1jpPXVkTvw-1; Fri, 11 Jul 2025 01:11:25 -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-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 1395019560BB; Fri, 11 Jul 2025 05:11:22 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.46]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id E066A30001A1; Fri, 11 Jul 2025 05:11:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1752210688; 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=A+c8yf1Q9Vf+WIIkpOlmgGLVhW/zsYOfbr5N0Z/epRY=; b=IGav8LadelsxiUoXa3KtNV1sR+Z8l07owmcQyjx6KfZPdEFnQT0GmrNOXU5H/Hxb335jXZ ECCIm/sgybjfD5cIFh0f5GSDTPr1QyEdSt/DuxlTO16fweq9rbBYz46Fe+2YZ/SUxgYtaC W0Ny6NFounkdGOIXAAkg/LArVswePwg= X-MC-Unique: YpImRccMMHWX1jpPXVkTvw-1 X-Mimecast-MFC-AGG-ID: YpImRccMMHWX1jpPXVkTvw_1752210682 From: John Snow To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , "Michael S. Tsirkin" , Eduardo Habkost , Jiri Pirko , Markus Armbruster , Peter Maydell , Ani Sinha , Zhao Liu , Peter Xu , Gerd Hoffmann , Fabiano Rosas , qemu-block@nongnu.org, "Gonglei (Arei)" , Laurent Vivier , Jason Wang , Yanan Wang , qemu-trivial@nongnu.org, Stefan Hajnoczi , Mads Ynddal , Lukas Straub , Marcel Apfelbaum , Kevin Wolf , Vladimir Sementsov-Ogievskiy , Michael Tokarev , Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eric Blake , Hanna Reitz , Zhenwei Pi , Stefan Berger , Michael Roth , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH v6 2/4] docs, qapi: generate undocumented return sections Date: Fri, 11 Jul 2025 01:10:43 -0400 Message-ID: <20250711051045.51110-3-jsnow@redhat.com> In-Reply-To: <20250711051045.51110-1-jsnow@redhat.com> References: <20250711051045.51110-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=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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_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: 1752210785148116600 Content-Type: text/plain; charset="utf-8" This patch changes the qapidoc parser to generate stub Return value documentation for any command that has a return value but does not have a "Returns:" doc section. The stubs include just the type name, which will be rendered with a cross-reference link in the HTML output. The algorithm for where return sections are placed is as follows: 1. If we have arguments, return goes right after them. 2. Else if we have errors, return goes right before them. 3. Else if we have features, return goes right before them. 4. Else return goes right after the intro To facilitate this algorithm, a "TODO:" hack line is used to separate the intro from the remainder of the documentation block in cases where there are no other sections to separate the intro from e.g. examples and additional detail meant to appear below the key sections of interest. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 14 ++++++++------ qapi/machine.json | 2 ++ scripts/qapi/parser.py | 35 +++++++++++++++++++++++++++++++++++ scripts/qapi/schema.py | 3 +++ 4 files changed, 48 insertions(+), 6 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 8011ac9efaf..77e28a65cfc 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 rtype 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/qapi/machine.json b/qapi/machine.json index f712e7da6d6..e3e0505a4b4 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1301,6 +1301,8 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # +# TODO: This line is a hack to separate the example from the body +# # .. qmp-example:: # # -> { "execute": "query-memory-size-summary" } diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 949d9e8bff7..aa8f1852c50 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -815,6 +815,41 @@ def connect_feature(self, feature: 'QAPISchemaFeature'= ) -> None: % feature.name) 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 sect in filter(lambda sect: sect.kind =3D=3D kind, reverse= d( + self.all_sections)): + idx =3D self.all_sections.index(sect) + (1 if after else 0) + self.all_sections.insert(idx, new_sect) + return True + return False + + if any(s.kind =3D=3D QAPIDoc.Kind.RETURNS for s in self.all_sectio= ns): + return + + # Stub "Returns" section for undocumented returns value + stub =3D QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) + + if any(_insert_near_kind(kind, stub, after) for kind, after in ( + # 1. If arguments, right after those. + (QAPIDoc.Kind.MEMBER, True), + # 2. Elif errors, right *before* those. + (QAPIDoc.Kind.ERRORS, False), + # 3. Elif features, right *before* those. + (QAPIDoc.Kind.FEATURE, False), + )): + return + + # 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) + 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.50.0 From nobody Sun Dec 14 01:57:44 2025 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=1752210768; cv=none; d=zohomail.com; s=zohoarc; b=Zj6PttS81JLFIzRfsE8k8jeZFmLuIxUC6q46xqnh3/AyWGSajlRErwSnLzYK0wWGcIMehwIjyplwVOTQpcmukUejYCPXXEL85bhKxMOrIdipGxB7/I+HuLJ6GVoHH8FsX2w0IX9EeJ3ELTgfM85evKBkcRxjS+oOzqNzhtue4/Q= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1752210768; 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=D8CKJZCT0DA9UWpXbjPd98IwiuYkj5ENa3pOYyLRZYc=; b=WJGf6C+DGAtTpFnFpD/USW5DyXvEjhz3NgoNKAk+ASURR/R/5D1+ojq0+YczqDXMTp0IPKeAS3LhYvQk85u0nnihOi5SyTb35BNJVkFf/xmeHHIkoeL5QZ451LkD0drziEiOXJrS7nA5FtBJpt5HjQaYbub114DC14ZmsD7OcuE= 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 1752210768786533.1168793459877; Thu, 10 Jul 2025 22:12:48 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ua630-0000dj-Qz; Fri, 11 Jul 2025 01:11:47 -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 1ua62v-0000Z5-Rp for qemu-devel@nongnu.org; Fri, 11 Jul 2025 01:11:41 -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 1ua62s-0000Ie-GA for qemu-devel@nongnu.org; Fri, 11 Jul 2025 01:11: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-47-7S6m4M6JOcaCxz-9U1A3dg-1; Fri, 11 Jul 2025 01:11:35 -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 B44491801211; Fri, 11 Jul 2025 05:11:32 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.46]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 7F449300022A; Fri, 11 Jul 2025 05:11:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1752210697; 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=D8CKJZCT0DA9UWpXbjPd98IwiuYkj5ENa3pOYyLRZYc=; b=VW0l95R87nmHWrT66Oy1iVwvNCf/fw1bxkmU4MUj0eChXgxFaorQVMm9TFDfl4jkVjbHbC 6h2JyRH6XA+TZeI/oGee2O/Mv5CnoNJ9sx99mAcvT6kN8XE3rnxkBc6DQpnoaQp54bjvd+ 9a/KnxxcktdRfSod4jtub3fWcdAGbac= X-MC-Unique: 7S6m4M6JOcaCxz-9U1A3dg-1 X-Mimecast-MFC-AGG-ID: 7S6m4M6JOcaCxz-9U1A3dg_1752210693 From: John Snow To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , "Michael S. Tsirkin" , Eduardo Habkost , Jiri Pirko , Markus Armbruster , Peter Maydell , Ani Sinha , Zhao Liu , Peter Xu , Gerd Hoffmann , Fabiano Rosas , qemu-block@nongnu.org, "Gonglei (Arei)" , Laurent Vivier , Jason Wang , Yanan Wang , qemu-trivial@nongnu.org, Stefan Hajnoczi , Mads Ynddal , Lukas Straub , Marcel Apfelbaum , Kevin Wolf , Vladimir Sementsov-Ogievskiy , Michael Tokarev , Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eric Blake , Hanna Reitz , Zhenwei Pi , Stefan Berger , Michael Roth , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH v6 3/4] qapi: remove trivial "Returns:" sections Date: Fri, 11 Jul 2025 01:10:44 -0400 Message-ID: <20250711051045.51110-4-jsnow@redhat.com> In-Reply-To: <20250711051045.51110-1-jsnow@redhat.com> References: <20250711051045.51110-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=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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_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=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: 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: 1752210770956116600 Content-Type: text/plain; charset="utf-8" The new qapidoc.py 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 is fairly "gentle" and doesn't aggressively touch other "Returns" lines that could be rephrased to omit repeating type information; it only removes lines that appear appropriate to wholly remove. To help facilitate auto-generated placement, several doc blocks have a "TODO:" line inserted to help the placement algorithm differentiate the introductory paragraph(s) from the rest of the documentation. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- qapi/audio.json | 2 -- qapi/block-core.json | 8 -------- qapi/char.json | 8 -------- qapi/cryptodev.json | 2 -- qapi/machine.json | 22 ---------------------- qapi/migration.json | 12 ++---------- qapi/misc-i386.json | 10 ---------- 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 | 2 +- 14 files changed, 3 insertions(+), 90 deletions(-) diff --git a/qapi/audio.json b/qapi/audio.json index 16de231f6d8..e8c469f3452 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -535,8 +535,6 @@ # # Return 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 1df6644f0de..d64f482d9bd 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1950,8 +1950,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 @@ -6202,9 +6197,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 df6e325e2e1..c189f629c1c 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -36,8 +36,6 @@ # # Return information about current character devices. # -# Returns: a list of @ChardevInfo -# # Since: 0.14 # # .. qmp-example:: @@ -82,8 +80,6 @@ # # Return 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 b13db264034..b028abf927b 100644 --- a/qapi/cryptodev.json +++ b/qapi/cryptodev.json @@ -96,8 +96,6 @@ # # Return information about current crypto devices. # -# Returns: a list of @QCryptodevInfo -# # Since: 8.0 ## { 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']} diff --git a/qapi/machine.json b/qapi/machine.json index e3e0505a4b4..b2062f21088 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -101,8 +101,6 @@ # # Return 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 @@ # # Return information about KVM acceleration # -# Returns: @KvmInfo -# # Since: 0.14 # # .. qmp-example:: @@ -932,8 +920,6 @@ # # Return 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 @@ # Return 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 e8a7d3b2a95..59a213aeb6c 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 @@ # # Return information about the current migration capabilities status # -# Returns: @MigrationCapabilityStatus -# # Since: 1.2 # # .. qmp-example:: @@ -1324,8 +1320,6 @@ # # Return information about the current migration parameters # -# Returns: @MigrationParameters -# # Since: 2.4 # # .. qmp-example:: @@ -1906,7 +1900,7 @@ # # Query replication status while the vm is running. # -# Returns: A @ReplicationStatus object showing the status. +# TODO: This line is a hack to separate the example from the body # # .. qmp-example:: # @@ -1960,7 +1954,7 @@ # # Query COLO status while the vm is running. # -# Returns: A @COLOStatus object showing the status. +# TODO: This line is a hack to separate the example from the body # # .. qmp-example:: # @@ -2335,8 +2329,6 @@ # # @deprecated: This command is deprecated with no replacement yet. # -# Returns: @MigrationThreadInfo -# # Since: 7.2 ## { 'command': 'query-migrationthreads', diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json index 5fefa0a4840..5b3bf597a2f 100644 --- a/qapi/misc-i386.json +++ b/qapi/misc-i386.json @@ -132,8 +132,6 @@ # @enabled field is set to 'false' and the state of all other fields # is unspecified. # -# Returns: @SevInfo -# # Since: 2.12 # # .. qmp-example:: @@ -214,8 +212,6 @@ # # This is only supported on AMD X86 platforms with KVM enabled. # -# Returns: SevCapability objects. -# # Errors: # - If SEV is not available on the platform, GenericError # @@ -281,8 +277,6 @@ # @mnonce: a random 16 bytes value encoded in base64 (it will be # included in report) # -# Returns: SevAttestationReport objects. -# # Errors: # - This will return an error if the attestation report is # unavailable, either due to an invalid guest configuration @@ -345,8 +339,6 @@ # # Return information about configured SGX capabilities of guest # -# Returns: @SgxInfo -# # Since: 6.2 # # .. qmp-example:: @@ -364,8 +356,6 @@ # # Return information about SGX capabilities of host # -# Returns: @SgxInfo -# # Since: 6.2 # # .. qmp-example:: diff --git a/qapi/misc.json b/qapi/misc.json index 4b9e601cfa5..8c98fb569a9 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 fd09beb35cb..759f8730059 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 514fa159b10..ff52ca5a1ce 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -325,8 +325,6 @@ # # Return information about the current SPICE server # -# Returns: @SpiceInfo -# # Since: 0.14 # # .. qmp-example:: @@ -656,8 +654,6 @@ # # Return information about the current VNC server # -# Returns: @VncInfo -# # Since: 0.14 # # .. qmp-example:: @@ -687,8 +683,6 @@ # # Return 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 @@ # # Return information about display configuration # -# Returns: @DisplayOptions -# # Since: 3.1 ## { 'command': 'query-display-options', diff --git a/qapi/virtio.json b/qapi/virtio.json index 73df718a261..28feadcd4bc 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..5f26d6c0149 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -102,7 +102,7 @@ # # Query yank instances. See @YankInstance for more information. # -# Returns: list of @YankInstance +# TODO: This line is a hack to separate the example from the body # # .. qmp-example:: # --=20 2.50.0 From nobody Sun Dec 14 01:57:44 2025 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=1752210754; cv=none; d=zohomail.com; s=zohoarc; b=J6SZGyMvZcuILLwZXEDda6ZGERe2abkp6PM8ks8HQAXjtiFu6/PSM4LKcTahvUnXJw50g3n7YnCVsFVThFR3HnfWQyLCZmUlaF1zSvQreP/4XuE2wN6G3w/+IBZiKoM5auzUDkXxn1eo5EhMDEUaTvdFqJmih2Gx2ygsYrWOXxQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1752210754; 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=XjXV7/RmcrW/MhrAfiHCZfzDGeRyg6WHPOWyP4CHAWc=; b=g+QXmQ4rWePv5Qu48wDt+17K7JNi92bQxweEqS0H1QGMyTRe3qAiEQpfZrqTgKA78JAk6+8lKNUBxTvgTNpzWQIeSESJY5pUPltWO3lTQZ/Iutwevdlxb6+IoYF6FzFBitwUDVVKpLnRoNN+PYa4Fkl26zvxVPpmPQne/fTf3Hk= 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 1752210754213173.61768527536583; Thu, 10 Jul 2025 22:12:34 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ua63K-0000tL-90; Fri, 11 Jul 2025 01:12:07 -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 1ua639-0000n2-8r for qemu-devel@nongnu.org; Fri, 11 Jul 2025 01:11:56 -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 1ua635-0000K0-LG for qemu-devel@nongnu.org; Fri, 11 Jul 2025 01:11: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-631-xN5mKA_jOH2gciTT3V_D6A-1; Fri, 11 Jul 2025 01:11:46 -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 C553F180120C; Fri, 11 Jul 2025 05:11:42 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.46]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 3E3D730001A1; Fri, 11 Jul 2025 05:11:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1752210710; 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=XjXV7/RmcrW/MhrAfiHCZfzDGeRyg6WHPOWyP4CHAWc=; b=E3ZpDsjqwUe5hGH9ua/QrdWen0paYfsimdJaR9yV+mb6aTvx+J62YadP+Eq03E3dNeXwWj 2hAoQKhvGDLIppyap8SMw2Vc3euHSd8b6k91wRFL0yqeLPLy9R3CyXePg+Jw+QxIyn+x3Q tX8MkTml3PAdwNOkfiGLovyHhCUKZ8g= X-MC-Unique: xN5mKA_jOH2gciTT3V_D6A-1 X-Mimecast-MFC-AGG-ID: xN5mKA_jOH2gciTT3V_D6A_1752210704 From: John Snow To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , "Michael S. Tsirkin" , Eduardo Habkost , Jiri Pirko , Markus Armbruster , Peter Maydell , Ani Sinha , Zhao Liu , Peter Xu , Gerd Hoffmann , Fabiano Rosas , qemu-block@nongnu.org, "Gonglei (Arei)" , Laurent Vivier , Jason Wang , Yanan Wang , qemu-trivial@nongnu.org, Stefan Hajnoczi , Mads Ynddal , Lukas Straub , Marcel Apfelbaum , Kevin Wolf , Vladimir Sementsov-Ogievskiy , Michael Tokarev , Paolo Bonzini , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eric Blake , Hanna Reitz , Zhenwei Pi , Stefan Berger , Michael Roth , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow Subject: [PATCH v6 4/4] qapi: rephrase return docs to avoid type name Date: Fri, 11 Jul 2025 01:10:45 -0400 Message-ID: <20250711051045.51110-5-jsnow@redhat.com> In-Reply-To: <20250711051045.51110-1-jsnow@redhat.com> References: <20250711051045.51110-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=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: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_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: 1752210754827116600 Content-Type: text/plain; charset="utf-8" Well, I tried. Maybe not very hard. Sorry! Signed-off-by: John Snow Acked-by: Markus Armbruster --- 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/misc-i386.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 +++--- 17 files changed, 28 insertions(+), 34 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index d64f482d9bd..f18db3149a3 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 ed4deb54db2..3edbc5436a3 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 1490a1a17f8..d288344c648 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -86,7 +86,7 @@ # Return 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 34b733f63b6..3aeb8f4f6fb 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -93,8 +93,7 @@ # # Return 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 d0ba1f0596f..3a9b67efb1b 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 @@ # # Return 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 e9e02972821..a5340268d13 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 126fa5ce602..c1ddae9c0fe 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -295,7 +295,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/misc-i386.json b/qapi/misc-i386.json index 5b3bf597a2f..c0c57f9ab25 100644 --- a/qapi/misc-i386.json +++ b/qapi/misc-i386.json @@ -163,7 +163,7 @@ # 'sev-guest' confidential virtualization object. The launch # measurement for SEV-SNP guests is only available within the guest. # -# Returns: The @SevLaunchMeasureInfo for the guest +# Returns: The guest's SEV guest launch measurement info # # Errors: # - If the launch measurement is unavailable, either due to an diff --git a/qapi/misc.json b/qapi/misc.json index 8c98fb569a9..70dbcb0aecf 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 97ea1839813..371ade0dc6a 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 b133b064471..c6fdce7f7bc 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 ff52ca5a1ce..7136c985c38 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -816,7 +816,7 @@ # # Return 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 28feadcd4bc..d1556dbf24a 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.50.0