From patchwork Tue Feb 27 11:39:09 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573588 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id A999FC54E4A for ; Tue, 27 Feb 2024 11:40:13 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revo5-0008VP-CV; Tue, 27 Feb 2024 06:39:33 -0500 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 1revo3-0008UV-Kf for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:31 -0500 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 1revnz-0005U8-O5 for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:31 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033966; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=dfkfeCekOpiBbqF1vw9bRJ3FmUFlUsJAOUcShjB7iyg=; b=GCvSYXj4hMskIbpZiDuwp7TtjwB1gcLml8Whmy0nNGcUY+1g3naff9c4oyoH5+zNvaTtWh ihGw5AlfeEl+2G1O6mqo5qx2QI12Vy+ddxSXX8mpISemv3nRNKyOyDn62sEZyiAmUbFabC CJCEDFkO2+gfMfab2wHAEJFBXaK62S4= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-652-nF1kyZmBODa1Z46u4U77ZQ-1; Tue, 27 Feb 2024 06:39:22 -0500 X-MC-Unique: nF1kyZmBODa1Z46u4U77ZQ-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 6613A800074; Tue, 27 Feb 2024 11:39:22 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 41874C04254; Tue, 27 Feb 2024 11:39:22 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 2AFC821E66FB; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 01/13] qapi: Memorize since & returns sections Date: Tue, 27 Feb 2024 12:39:09 +0100 Message-ID: <20240227113921.236097-2-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.8 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org This is chiefly to make code that looks up these sections easier to read. Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 11707418fb..bfc47cf3cb 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -639,6 +639,10 @@ def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None): # dicts mapping parameter/feature names to their description self.args: Dict[str, QAPIDoc.ArgSection] = {} self.features: Dict[str, QAPIDoc.ArgSection] = {} + # a command's "Returns" section + self.returns: Optional[QAPIDoc.Section] = None + # "Since" section + self.since: Optional[QAPIDoc.Section] = None # sections other than .body, .args, .features self.sections: List[QAPIDoc.Section] = [] @@ -660,14 +664,17 @@ def ensure_untagged_section(self, info: QAPISourceInfo) -> None: self.all_sections.append(section) def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None: - if tag in ('Returns', 'Since'): - for section in self.all_sections: - if isinstance(section, self.ArgSection): - continue - if section.tag == tag: - raise QAPISemError( - info, "duplicated '%s' section" % tag) section = self.Section(info, tag) + if tag == 'Returns': + if self.returns: + raise QAPISemError( + info, "duplicated '%s' section" % tag) + self.returns = section + elif tag == 'Since': + if self.since: + raise QAPISemError( + info, "duplicated '%s' section" % tag) + self.since = section self.sections.append(section) self.all_sections.append(section) @@ -708,13 +715,9 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: self.features[feature.name].connect(feature) def check_expr(self, expr: QAPIExpression) -> None: - if 'command' not in expr: - sec = next((sec for sec in self.sections - if sec.tag == 'Returns'), - None) - if sec: - raise QAPISemError(sec.info, - "'Returns:' is only valid for commands") + if self.returns and 'command' not in expr: + raise QAPISemError(self.returns.info, + "'Returns:' is only valid for commands") def check(self) -> None: From patchwork Tue Feb 27 11:39:10 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573587 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id B1E62C54E55 for ; Tue, 27 Feb 2024 11:40:13 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revo6-0008Vo-CQ; Tue, 27 Feb 2024 06:39:34 -0500 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 1revo4-0008Uv-Ik for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:32 -0500 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 1revnz-0005U9-OT for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:32 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033966; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=wgq5a0s/a7hkcbApiEJx5CPQu9e/pbtW3qPLD2zwL2s=; b=a9ls5ohD5ZaFIKajQ3fhGTqPBz2vkl2q05wjhTTdUCWGGj6KHX3CrXOWsDPGdc/llTzxzc Jb7bjZtvLxVJRiCPMrnWlKaFwplHRgnH9dkXayEVpm4P2F+If/DRTHXD4zHS9HljZbkkLN quUcnQWRs2PMJe6vr2P2kH9dKjm24Xo= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-652-1qIQzdEcMduozLv9LVFcnw-1; Tue, 27 Feb 2024 06:39:22 -0500 X-MC-Unique: 1qIQzdEcMduozLv9LVFcnw-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 656993C02757; Tue, 27 Feb 2024 11:39:22 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 41E832166B33; Tue, 27 Feb 2024 11:39:22 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 2DD6B21E6682; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 02/13] qapi: Slightly clearer error message for invalid "Returns" section Date: Tue, 27 Feb 2024 12:39:10 +0100 Message-ID: <20240227113921.236097-3-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.6 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Change "'Returns:' is only valid for commands" to "'Returns' section is only valid for commands". Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 5 +++-- tests/qapi-schema/doc-invalid-return.err | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index bfc47cf3cb..e4c2259e39 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -716,8 +716,9 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: def check_expr(self, expr: QAPIExpression) -> None: if self.returns and 'command' not in expr: - raise QAPISemError(self.returns.info, - "'Returns:' is only valid for commands") + raise QAPISemError( + self.returns.info, + "'Returns' section is only valid for commands") def check(self) -> None: diff --git a/tests/qapi-schema/doc-invalid-return.err b/tests/qapi-schema/doc-invalid-return.err index 3d9e71c2b3..aafd57b135 100644 --- a/tests/qapi-schema/doc-invalid-return.err +++ b/tests/qapi-schema/doc-invalid-return.err @@ -1 +1 @@ -doc-invalid-return.json:6: 'Returns:' is only valid for commands +doc-invalid-return.json:6: 'Returns' section is only valid for commands From patchwork Tue Feb 27 11:39:11 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573591 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 254B0C5478C for ; Tue, 27 Feb 2024 11:40:25 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revo6-0008VT-No; Tue, 27 Feb 2024 06:39:34 -0500 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 1revo4-0008Uk-D6 for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:32 -0500 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 1revnz-0005UD-Oc for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:32 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033966; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=VIBQF3fqTrEEAplPbUtNZ3udxDodrsm+E5L2NDR5NMk=; b=HXd5wZXjtVPwc4L7yCPBV3mSlYkBgbc90acYK4l8rDOemTp4kerggetp92/4fP6mPYBp8H 42y4UQpWgfKnWkq3W4PZ+2NPrgDGnKzIA2kHhtZp35R81ctneWSPeF1bcLCvYfD7xwZ/FF o9BxF9w0ioj7UvAbyZwQeoPa2Yw9Wuk= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-446-LMxvtdWtNCWoNojHiLDPIA-1; Tue, 27 Feb 2024 06:39:22 -0500 X-MC-Unique: LMxvtdWtNCWoNojHiLDPIA-1 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 80CC610650E1; Tue, 27 Feb 2024 11:39:22 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 417B7492BE2; Tue, 27 Feb 2024 11:39:22 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 30BE821E6691; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 03/13] qapi: New documentation section tag "Errors" Date: Tue, 27 Feb 2024 12:39:11 +0100 Message-ID: <20240227113921.236097-4-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.10 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org We use section "Returns" for documenting both success and error response of commands. I intend to generate better command success response documentation. Easier when "Returns" documents just he success response. Create new section tag "Errors". The next two commits will move error response documentation from "Returns" sections to "Errors" sections. Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.rst | 6 +++++- scripts/qapi/parser.py | 23 +++++++++++++++++------ tests/qapi-schema/doc-good.json | 2 ++ tests/qapi-schema/doc-good.out | 2 ++ tests/qapi-schema/doc-good.txt | 6 ++++++ 5 files changed, 32 insertions(+), 7 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 6804a4b596..f453bd3546 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -996,7 +996,8 @@ line "Features:", like this:: A tagged section begins with a paragraph that starts with one of the following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:", -"Returns:", "TODO:". It ends with the start of a new section. +"Returns:", "Errors:", "TODO:". It ends with the start of a new +section. The second and subsequent lines of tagged sections must be indented like this:: @@ -1007,6 +1008,9 @@ like this:: # Duis aute irure dolor in reprehenderit in voluptate velit esse # cillum dolore eu fugiat nulla pariatur. +"Returns" and "Errors" sections are only valid for commands. They +document the success and the error response, respectively. + A "Since: x.y.z" tagged section lists the release that introduced the definition. diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index e4c2259e39..a32b2c7e7f 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -543,7 +543,7 @@ def get_doc(self) -> 'QAPIDoc': line = self.get_doc_indented(doc) no_more_args = True elif match := re.match( - r'(Returns|Since|Notes?|Examples?|TODO): *', + r'(Returns|Errors|Since|Notes?|Examples?|TODO): *', line): # tagged section doc.new_tagged_section(self.info, match.group(1)) @@ -639,8 +639,9 @@ def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None): # dicts mapping parameter/feature names to their description self.args: Dict[str, QAPIDoc.ArgSection] = {} self.features: Dict[str, QAPIDoc.ArgSection] = {} - # a command's "Returns" section + # a command's "Returns" and "Errors" section self.returns: Optional[QAPIDoc.Section] = None + self.errors: Optional[QAPIDoc.Section] = None # "Since" section self.since: Optional[QAPIDoc.Section] = None # sections other than .body, .args, .features @@ -670,6 +671,11 @@ def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None: raise QAPISemError( info, "duplicated '%s' section" % tag) self.returns = section + elif tag == 'Errors': + if self.errors: + raise QAPISemError( + info, "duplicated '%s' section" % tag) + self.errors = section elif tag == 'Since': if self.since: raise QAPISemError( @@ -715,10 +721,15 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: self.features[feature.name].connect(feature) def check_expr(self, expr: QAPIExpression) -> None: - if self.returns and 'command' not in expr: - raise QAPISemError( - self.returns.info, - "'Returns' section is only valid for commands") + if 'command' not in expr: + if self.returns: + raise QAPISemError( + self.returns.info, + "'Returns' section is only valid for commands") + if self.errors: + raise QAPISemError( + self.returns.info, + "'Errors' section is only valid for commands") def check(self) -> None: diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 5bb2b69071..de38a386e8 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -159,6 +159,8 @@ # # Returns: @Object # +# Errors: some +# # TODO: frobnicate # # Notes: diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 34ee74af4b..716a9a4102 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -173,6 +173,8 @@ another feature @arg3 is undocumented section=Returns @Object + section=Errors +some section=TODO frobnicate section=Notes diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index 879f6ff50a..847db70412 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -206,6 +206,12 @@ Returns "Object" +Errors +~~~~~~ + +some + + Notes ~~~~~ From patchwork Tue Feb 27 11:39:12 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573590 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id A98D4C54798 for ; Tue, 27 Feb 2024 11:40:13 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revoA-00006n-UL; Tue, 27 Feb 2024 06:39:38 -0500 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 1revo6-0008Vy-Ua for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:34 -0500 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 1revnz-0005UB-Se for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:34 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033966; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=hApo3bP8JAl36Ec2KBYwXYppV1B+zlAZrfGQOhuCsXE=; b=DgnoUeKef5E895asdYtP/9VwMzOXjO29JskBMSYJMS9+hnfhB3sXr3uXxNT3lO/qhWjvq3 3PLRZklc0xjO1V9Q2pstI/oQjuWlo2W4pdwRgQzpbdRH/5+0CK96kZj4TZAfsjhoh4PU1I yBr3NtB5lC/KSi/VsLUyw8qWUst8FT0= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-568-ByjFKczgOiqH_Nni-5Gr0w-1; Tue, 27 Feb 2024 06:39:22 -0500 X-MC-Unique: ByjFKczgOiqH_Nni-5Gr0w-1 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 9F160381D4C4; Tue, 27 Feb 2024 11:39:22 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 428C0492BE3; Tue, 27 Feb 2024 11:39:22 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 33BEA21E66A3; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 04/13] qapi: Move error documentation to new "Errors" sections Date: Tue, 27 Feb 2024 12:39:12 +0100 Message-ID: <20240227113921.236097-5-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.10 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Signed-off-by: Markus Armbruster --- qapi/block-core.json | 44 ++++++++++++++++++++++++++++++++++++++++ qapi/block-export.json | 23 ++++++++++++--------- qapi/block.json | 8 ++++++-- qapi/machine-target.json | 35 ++++++++++++++++++++------------ qapi/machine.json | 6 ++++++ qapi/misc.json | 10 +++++++-- qapi/net.json | 14 ++++++++++--- qapi/qdev.json | 2 ++ qapi/qom.json | 4 ++++ qapi/transaction.json | 3 ++- qapi/ui.json | 6 ++++++ qapi/yank.json | 2 ++ 12 files changed, 126 insertions(+), 31 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 22b8634422..cea46b4668 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1458,6 +1458,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, DeviceNotFound # # Since: 0.14 @@ -1676,6 +1678,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, DeviceNotFound # # Since: 0.14 @@ -1756,6 +1760,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If "device" does not exist or cannot be determined, # DeviceNotFound # @@ -1856,6 +1862,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @device does not exist, DeviceNotFound # - Any other error returns a GenericError. # @@ -1896,6 +1904,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, GenericError # # Since: 1.6 @@ -1923,6 +1933,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, DeviceNotFound # # Since: 2.3 @@ -2129,6 +2141,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, GenericError # # Since: 1.3 @@ -2306,6 +2320,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device or node, DeviceNotFound # - If @name is already taken, GenericError with an explanation # @@ -2330,6 +2346,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device or node, DeviceNotFound # - If @name is not found, GenericError with an explanation # - if @name is frozen by an operation, GenericError @@ -2355,6 +2373,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation # @@ -2377,6 +2397,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation # @@ -2399,6 +2421,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation # @@ -2429,6 +2453,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @node is not a valid block device, DeviceNotFound # - If any bitmap in @bitmaps or @target is not found, # GenericError @@ -2471,6 +2497,8 @@ # # Returns: # - BlockDirtyBitmapSha256 on success +# +# Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found or if hashing has failed, GenericError # with an explanation @@ -2868,6 +2896,8 @@ # # Returns: # - Nothing on success. +# +# Errors: # - If @device does not exist, DeviceNotFound. # # Since: 1.1 @@ -2907,6 +2937,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If no background operation is active on this device, # DeviceNotActive # @@ -2952,6 +2984,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If no background operation is active on this device, # DeviceNotActive # @@ -2979,6 +3013,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If no background operation is active on this device, # DeviceNotActive # @@ -3004,6 +3040,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If no background operation is active on this device, # DeviceNotActive # @@ -3036,6 +3074,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If no background operation is active on this device, # DeviceNotActive # @@ -6072,6 +6112,8 @@ # # Returns: # - nothing on success +# +# Errors: # - If @device is not a valid block device, GenericError # - If any snapshot matching @name exists, or @name is empty, # GenericError @@ -6109,6 +6151,8 @@ # # Returns: # - SnapshotInfo on success +# +# Errors: # - If @device is not a valid block device, GenericError # - If snapshot not found, GenericError # - If the format of the image used does not support it, diff --git a/qapi/block-export.json b/qapi/block-export.json index d9bd376b48..3919a2d5b9 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -65,7 +65,8 @@ # server from advertising multiple client support (since 5.2; # default: 0). # -# Returns: error if the server is already running. +# Errors: +# - if the server is already running # # Since: 1.3 ## @@ -247,8 +248,9 @@ # @deprecated: This command is deprecated. Use @block-export-add # instead. # -# Returns: error if the server is not running, or export with the same -# name already exists. +# Errors: +# - if the server is not running +# - if an export with the same name already exists # # Since: 1.3 ## @@ -294,11 +296,10 @@ # @deprecated: This command is deprecated. Use @block-export-del # instead. # -# Returns: error if -# -# - the server is not running -# - export is not found -# - mode is 'safe' and there are existing connections +# Errors: +# - if the server is not running +# - if export is not found +# - if mode is 'safe' and there are existing connections # # Since: 2.12 ## @@ -415,8 +416,10 @@ # @mode: Mode of command operation. See @BlockExportRemoveMode # description. Default is 'safe'. # -# Returns: Error if the export is not found or @mode is 'safe' and the -# export is still in use (e.g. by existing client connections) +# Errors: +# - if the export is not found +# - if @mode is 'safe' and the export is still in use (e.g. by +# existing client connections) # # Since: 5.2 ## diff --git a/qapi/block.json b/qapi/block.json index 79a0bcc208..dab616799a 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -112,6 +112,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @device is not a valid block device, DeviceNotFound # # Notes: Ejecting a device with no media results in success @@ -461,6 +463,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @device is not a valid block device, DeviceNotFound # # Since: 1.1 @@ -540,8 +544,8 @@ # @boundaries-flush: list of interval boundary values for flush # latency histogram. # -# Returns: error if device is not found or any boundary arrays are -# invalid. +# Errors: +# - if device is not found or any boundary arrays are invalid. # # Since: 4.0 # diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 2c5dda735e..db6c0fae98 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -154,10 +154,13 @@ # Some architectures may not support comparing CPU models. s390x # supports comparing CPU models. # -# Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU -# models is not supported, if a model cannot be used, if a model -# contains an unknown cpu definition name, unknown properties or -# properties with wrong types. +# Returns: a CpuModelBaselineInfo +# +# Errors: +# - if comparing CPU models is not supported +# - if a model cannot be used +# - if a model contains an unknown cpu definition name, unknown +# properties or properties with wrong types. # # Note: this command isn't specific to s390x, but is only implemented # on this architecture currently. @@ -201,10 +204,13 @@ # Some architectures may not support baselining CPU models. s390x # supports baselining CPU models. # -# Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU -# models is not supported, if a model cannot be used, if a model -# contains an unknown cpu definition name, unknown properties or -# properties with wrong types. +# Returns: a CpuModelBaselineInfo +# +# Errors: +# - if baselining CPU models is not supported +# - if a model cannot be used +# - if a model contains an unknown cpu definition name, unknown +# properties or properties with wrong types. # # Note: this command isn't specific to s390x, but is only implemented # on this architecture currently. @@ -263,11 +269,14 @@ # Some architectures may not support all expansion types. s390x # supports "full" and "static". Arm only supports "full". # -# Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU -# models is not supported, if the model cannot be expanded, if the -# model contains an unknown CPU definition name, unknown -# properties or properties with a wrong type. Also returns an -# error if an expansion type is not supported. +# Returns: a CpuModelExpansionInfo +# +# Errors: +# - if expanding CPU models is not supported +# - if the model cannot be expanded +# - if the model contains an unknown CPU definition name, unknown +# properties or properties with a wrong type +# - if an expansion type is not supported # # Since: 2.8 ## diff --git a/qapi/machine.json b/qapi/machine.json index 93b4677286..0985c61740 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1062,6 +1062,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If the balloon driver is enabled but not functional because # the KVM kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive @@ -1100,6 +1102,8 @@ # # Returns: # - @BalloonInfo on success +# +# Errors: # - If the balloon driver is enabled but not functional because # the KVM kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive @@ -1164,6 +1168,8 @@ # # Returns: # - @HvBalloonInfo on success +# +# Errors: # - If no hv-balloon device is present, guest memory status # reporting is not enabled or no guest memory status report # received yet, GenericError diff --git a/qapi/misc.json b/qapi/misc.json index 11c55c2b6c..578f574a68 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -345,6 +345,8 @@ # # Returns: # - @AddfdInfo on success +# +# Errors: # - If file descriptor was not received, GenericError # - If @fdset-id is a negative value, GenericError # @@ -376,6 +378,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @fdset-id or @fd is not found, GenericError # # Since: 1.2 @@ -528,8 +532,10 @@ # @option: option name # # Returns: list of @CommandLineOptionInfo for all options (or for the -# given @option). Returns an error if the given @option doesn't -# exist. +# given @option). +# +# Errors: +# - if the given @option doesn't exist # # Since: 1.5 # diff --git a/qapi/net.json b/qapi/net.json index 1374caac64..09e644a742 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -19,6 +19,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @name is not a valid network device, DeviceNotFound # # Since: 0.14 @@ -46,6 +48,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @type is not a valid network backend, DeviceNotFound # # Example: @@ -67,6 +71,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @id is not a valid network backend, DeviceNotFound # # Since: 0.14 @@ -828,9 +834,11 @@ # @name: net client name # # Returns: list of @RxFilterInfo for all NICs (or for the given NIC). -# Returns an error if the given @name doesn't exist, or given NIC -# doesn't support rx-filter querying, or given net client isn't a -# NIC. +# +# Errors: +# - if the given @name doesn't exist +# - if the given NIC doesn't support rx-filter querying +# - if the given net client isn't a NIC # # Since: 1.6 # diff --git a/qapi/qdev.json b/qapi/qdev.json index 32ffaee644..cc72c55a99 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -91,6 +91,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @id is not a valid device, DeviceNotFound # # Notes: When this command completes, the device may not be removed diff --git a/qapi/qom.json b/qapi/qom.json index 2a6e49365a..33aa30bb41 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -1058,6 +1058,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - Error if @qom-type is not a valid class name # # Since: 2.0 @@ -1081,6 +1083,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - Error if @id is not a valid id for a QOM object # # Since: 2.0 diff --git a/qapi/transaction.json b/qapi/transaction.json index 45233ddd2a..78cc21800d 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -236,7 +236,8 @@ # # Returns: nothing on success # -# Errors depend on the operations of the transaction +# Errors: +# Any errors from commands in the transaction # # Note: The transaction aborts on the first failure. Therefore, there # will be information on only one failed operation returned in an diff --git a/qapi/ui.json b/qapi/ui.json index e3999b7c07..199a412c5a 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -80,6 +80,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If Spice is not enabled, DeviceNotFound # # Since: 0.14 @@ -142,6 +144,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If @protocol is 'spice' and Spice is not active, # DeviceNotFound # @@ -1038,6 +1042,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - If key is unknown or redundant, GenericError # # Since: 1.3 diff --git a/qapi/yank.json b/qapi/yank.json index b7aeb9ceef..a457284b45 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -80,6 +80,8 @@ # # Returns: # - Nothing on success +# +# Errors: # - @DeviceNotFound error, if any of the YankInstances doesn't exist # # Example: From patchwork Tue Feb 27 11:39:13 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573594 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 57A8BC54798 for ; Tue, 27 Feb 2024 11:41:14 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revoG-0000Am-J1; Tue, 27 Feb 2024 06:39:44 -0500 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 1revoA-00006l-La for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:38 -0500 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 1revo0-0005Uq-4I for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:38 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033967; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=ld+Fq/GHqBiyK8aoPwEyt/lB3jn9PlXWzKRN180aSV8=; b=RRUek+00jr0oil0FHXdZKyZ9YWyU7ZUg8UUlfeh+cRegQStMGqxT4B52QnrzdU0XbT2abN GqmZHckORmmFDLNj7NC5EdsJ+Qa9Jl/AUZFRWQwQgMeQfjogC+K4ue/wTJBVKP3H5iuTzA sLl8XydO9zvvOPT6HNQYWIzvOeYk454= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-629-a7zVmkp5PROOGD1NdSVw-Q-1; Tue, 27 Feb 2024 06:39:24 -0500 X-MC-Unique: a7zVmkp5PROOGD1NdSVw-Q-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id B67A5835155; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 58798111D3E3; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 36E6F21E660C; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 05/13] qapi: Delete useless "Returns" sections Date: Tue, 27 Feb 2024 12:39:13 +0100 Message-ID: <20240227113921.236097-6-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.3 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Signed-off-by: Markus Armbruster --- qapi/block-core.json | 66 ---------------------------------------- qapi/block.json | 6 ---- qapi/char.json | 6 ---- qapi/dump.json | 2 -- qapi/machine-target.json | 2 -- qapi/machine.json | 11 ------- qapi/migration.json | 26 ---------------- qapi/misc-target.json | 3 -- qapi/misc.json | 15 --------- qapi/net.json | 9 ------ qapi/qdev.json | 3 -- qapi/qom.json | 6 ---- qapi/run-state.json | 5 +-- qapi/tpm.json | 2 -- qapi/transaction.json | 2 -- qapi/ui.json | 17 ----------- qapi/yank.json | 3 -- 17 files changed, 1 insertion(+), 183 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index cea46b4668..94b01deffc 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1456,9 +1456,6 @@ # # @size: new image size in bytes # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, DeviceNotFound # @@ -1676,9 +1673,6 @@ # # For the arguments, see the documentation of BlockdevSnapshotSync. # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, DeviceNotFound # @@ -1758,9 +1752,6 @@ # is not validated, so care should be taken when specifying the # string or the image chain may not be able to be reopened again. # -# Returns: -# - Nothing on success -# # Errors: # - If "device" does not exist or cannot be determined, # DeviceNotFound @@ -1860,9 +1851,6 @@ # @deprecated: Members @base and @top are deprecated. Use @base-node # and @top-node instead. # -# Returns: -# - Nothing on success -# # Errors: # - If @device does not exist, DeviceNotFound # - Any other error returns a GenericError. @@ -1902,9 +1890,6 @@ # @deprecated: This command is deprecated. Use @blockdev-backup # instead. # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, GenericError # @@ -1931,9 +1916,6 @@ # 'backup'. The operation can be stopped before it has completed using # the block-job-cancel command. # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, DeviceNotFound # @@ -2139,9 +2121,6 @@ # specifies the format of the mirror image, default is to probe if # mode='existing', else the format of the source. # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, GenericError # @@ -2318,9 +2297,6 @@ # Create a dirty bitmap with a name on the node, and start tracking # the writes. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device or node, DeviceNotFound # - If @name is already taken, GenericError with an explanation @@ -2344,9 +2320,6 @@ # with block-dirty-bitmap-add. If the bitmap is persistent, remove it # from its storage too. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device or node, DeviceNotFound # - If @name is not found, GenericError with an explanation @@ -2371,9 +2344,6 @@ # backup from this point in time forward will only backup clusters # modified after this clear operation. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation @@ -2395,9 +2365,6 @@ # # Enables a dirty bitmap so that it will begin tracking disk changes. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation @@ -2419,9 +2386,6 @@ # # Disables a dirty bitmap so that it will stop tracking disk changes. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found, GenericError with an explanation @@ -2451,9 +2415,6 @@ # dirty in any of the source bitmaps. This can be used to achieve # backup checkpoints, or in simpler usages, to copy bitmaps. # -# Returns: -# - nothing on success -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If any bitmap in @bitmaps or @target is not found, @@ -2570,8 +2531,6 @@ # disappear from the query list without user intervention. # Defaults to true. (Since 3.1) # -# Returns: nothing on success. -# # Since: 2.6 # # Example: @@ -2894,9 +2853,6 @@ # disappear from the query list without user intervention. # Defaults to true. (Since 3.1) # -# Returns: -# - Nothing on success. -# # Errors: # - If @device does not exist, DeviceNotFound. # @@ -2935,9 +2891,6 @@ # @speed: the maximum speed, in bytes per second, or 0 for unlimited. # Defaults to 0. # -# Returns: -# - Nothing on success -# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -2982,9 +2935,6 @@ # paused) instead of waiting for the destination to complete its # final synchronization (since 1.3) # -# Returns: -# - Nothing on success -# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -3011,9 +2961,6 @@ # the name of the parameter), but since QEMU 2.7 it can have other # values. # -# Returns: -# - Nothing on success -# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -3038,9 +2985,6 @@ # the name of the parameter), but since QEMU 2.7 it can have other # values. # -# Returns: -# - Nothing on success -# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -3072,9 +3016,6 @@ # the name of the parameter), but since QEMU 2.7 it can have other # values. # -# Returns: -# - Nothing on success -# # Errors: # - If no background operation is active on this device, # DeviceNotActive @@ -3099,8 +3040,6 @@ # # @id: The job identifier. # -# Returns: Nothing on success -# # Since: 2.12 ## { 'command': 'block-job-dismiss', 'data': { 'id': 'str' }, @@ -3118,8 +3057,6 @@ # # @id: The job identifier. # -# Returns: Nothing on success -# # Since: 2.12 ## { 'command': 'block-job-finalize', 'data': { 'id': 'str' }, @@ -6110,9 +6047,6 @@ # For the arguments, see the documentation of # BlockdevSnapshotInternal. # -# Returns: -# - nothing on success -# # Errors: # - If @device is not a valid block device, GenericError # - If any snapshot matching @name exists, or @name is empty, diff --git a/qapi/block.json b/qapi/block.json index dab616799a..65d9804bdf 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -110,9 +110,6 @@ # # @deprecated: Member @device is deprecated. Use @id instead. # -# Returns: -# - Nothing on success -# # Errors: # - If @device is not a valid block device, DeviceNotFound # @@ -461,9 +458,6 @@ # the device will be removed from its group and the rest of its # members will not be affected. The 'group' parameter is ignored. # -# Returns: -# - Nothing on success -# # Errors: # - If @device is not a valid block device, DeviceNotFound # diff --git a/qapi/char.json b/qapi/char.json index 4873bc635a..777dde55d9 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -139,8 +139,6 @@ # - data itself is always Unicode regardless of format, like any # other string. # -# Returns: Nothing on success -# # Since: 1.4 # # Example: @@ -772,8 +770,6 @@ # # @id: the chardev's ID, must exist and not be in use # -# Returns: Nothing on success -# # Since: 1.4 # # Example: @@ -791,8 +787,6 @@ # # @id: the chardev's ID, must exist # -# Returns: Nothing on success -# # Since: 2.10 # # Example: diff --git a/qapi/dump.json b/qapi/dump.json index f82dd6a1af..4c021dd53c 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -92,8 +92,6 @@ # # Note: All boolean arguments default to false # -# Returns: nothing on success -# # Since: 1.2 # # Example: diff --git a/qapi/machine-target.json b/qapi/machine-target.json index db6c0fae98..519adf3220 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -414,8 +414,6 @@ # # @unstable: This command is experimental. # -# Returns: Nothing on success. -# # Since: 8.2 ## { 'command': 'set-cpu-topology', diff --git a/qapi/machine.json b/qapi/machine.json index 0985c61740..7d3ca33683 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -326,8 +326,6 @@ # # Since: 1.1 # -# Returns: nothing. -# # Note: prior to 4.0, this command does nothing in case the guest # isn't suspended. # @@ -377,8 +375,6 @@ # all CPUs (ppc64). The command fails when the guest doesn't support # injecting. # -# Returns: If successful, nothing -# # Since: 0.14 # # Note: prior to 2.1, this command was only supported for x86 and s390 @@ -778,8 +774,6 @@ # @cpu-index: the index of the virtual CPU to use for translating the # virtual address (defaults to CPU 0) # -# Returns: Nothing on success -# # Since: 0.14 # # Notes: Errors were not reliably returned until 1.1 @@ -806,8 +800,6 @@ # # @filename: the file to save the memory to as binary data # -# Returns: Nothing on success -# # Since: 0.14 # # Notes: Errors were not reliably returned until 1.1 @@ -1060,9 +1052,6 @@ # # From it we have: balloon_size = vm_ram_size - @value # -# Returns: -# - Nothing on success -# # Errors: # - If the balloon driver is enabled but not functional because # the KVM kernel module cannot support it, KVMMissingCap diff --git a/qapi/migration.json b/qapi/migration.json index 7303e57e8e..facdb28bbc 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1555,8 +1555,6 @@ # # Cancel the current executing migration process. # -# Returns: nothing on success -# # Notes: This command succeeds even if there is no migration process # running. # @@ -1576,8 +1574,6 @@ # # @state: The state the migration is currently expected to be in # -# Returns: nothing on success -# # Since: 2.11 # # Example: @@ -1699,8 +1695,6 @@ # @deprecated: Members @inc and @blk are deprecated. Use # blockdev-mirror with NBD instead. # -# Returns: nothing on success -# # Since: 0.14 # # Notes: @@ -1782,8 +1776,6 @@ # @channels: list of migration stream channels with each stream in the # list connected to a destination interface endpoint. # -# Returns: nothing on success -# # Since: 2.3 # # Notes: @@ -1851,8 +1843,6 @@ # @live: Optional argument to ask QEMU to treat this command as part # of a live migration. Default to true. (since 2.11) # -# Returns: Nothing on success -# # Since: 1.1 # # Example: @@ -1871,8 +1861,6 @@ # # @enable: true to enable, false to disable. # -# Returns: nothing -# # Since: 1.3 # # Example: @@ -1915,8 +1903,6 @@ # @failover: true to do failover, false to stop. but cannot be # specified if 'enable' is true. default value is false. # -# Returns: nothing. -# # Example: # # -> { "execute": "xen-set-replication", @@ -1968,8 +1954,6 @@ # # Xen uses this command to notify replication to trigger a checkpoint. # -# Returns: nothing. -# # Example: # # -> { "execute": "xen-colo-do-checkpoint" } @@ -2026,8 +2010,6 @@ # # @uri: the URI to be used for the recovery of migration stream. # -# Returns: nothing. -# # Example: # # -> { "execute": "migrate-recover", @@ -2045,8 +2027,6 @@ # # Pause a migration. Currently it only supports postcopy. # -# Returns: nothing. -# # Example: # # -> { "execute": "migrate-pause" } @@ -2415,8 +2395,6 @@ # # If @tag already exists, an error will be reported # -# Returns: nothing -# # Example: # # -> { "execute": "snapshot-save", @@ -2487,8 +2465,6 @@ # device nodes that can have changed since the original @snapshot-save # command execution. # -# Returns: nothing -# # Example: # # -> { "execute": "snapshot-load", @@ -2550,8 +2526,6 @@ # to determine completion and to fetch details of any errors that # arise. # -# Returns: nothing -# # Example: # # -> { "execute": "snapshot-delete", diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 542a3e42f2..4e0a6492a9 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -472,9 +472,6 @@ # # @port: The port number # -# Returns: -# - Nothing on success. -# # Since: 8.0 # # Example: diff --git a/qapi/misc.json b/qapi/misc.json index 578f574a68..015388aa3e 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -28,8 +28,6 @@ # # @tls: whether to perform TLS. Only applies to the "spice" protocol # -# Returns: nothing on success. -# # Since: 0.14 # # Example: @@ -160,8 +158,6 @@ # # Since: 0.14 # -# Returns: If successful, nothing -# # Notes: This command will succeed if the guest is currently running. # It will also succeed if the guest is in the "inmigrate" state; # in this case, the effect of the command is to make sure the @@ -196,8 +192,6 @@ # # Since: 3.0 # -# Returns: nothing -# # Example: # # -> { "execute": "x-exit-preconfig" } @@ -256,8 +250,6 @@ # # @fdname: file descriptor name # -# Returns: Nothing on success -# # Since: 0.14 # # Notes: If @fdname already exists, the file descriptor assigned to it @@ -285,8 +277,6 @@ # # @fdname: file descriptor name # -# Returns: Nothing on success -# # Since: 8.0 # # Notes: If @fdname already exists, the file descriptor assigned to it @@ -309,8 +299,6 @@ # # @fdname: file descriptor name # -# Returns: Nothing on success -# # Since: 0.14 # # Example: @@ -376,9 +364,6 @@ # # @fd: The file descriptor that is to be removed. # -# Returns: -# - Nothing on success -# # Errors: # - If @fdset-id or @fd is not found, GenericError # diff --git a/qapi/net.json b/qapi/net.json index 09e644a742..417b61a321 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -17,9 +17,6 @@ # # @up: true to set the link status to be up # -# Returns: -# - Nothing on success -# # Errors: # - If @name is not a valid network device, DeviceNotFound # @@ -46,9 +43,6 @@ # # Since: 0.14 # -# Returns: -# - Nothing on success -# # Errors: # - If @type is not a valid network backend, DeviceNotFound # @@ -69,9 +63,6 @@ # # @id: the name of the network backend to remove # -# Returns: -# - Nothing on success -# # Errors: # - If @id is not a valid network backend, DeviceNotFound # diff --git a/qapi/qdev.json b/qapi/qdev.json index cc72c55a99..facaa0bc6a 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -89,9 +89,6 @@ # # @id: the device's ID or QOM path # -# Returns: -# - Nothing on success -# # Errors: # - If @id is not a valid device, DeviceNotFound # diff --git a/qapi/qom.json b/qapi/qom.json index 33aa30bb41..032c6fa037 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -1056,9 +1056,6 @@ # # Create a QOM object. # -# Returns: -# - Nothing on success -# # Errors: # - Error if @qom-type is not a valid class name # @@ -1081,9 +1078,6 @@ # # @id: the name of the QOM object to remove # -# Returns: -# - Nothing on success -# # Errors: # - Error if @id is not a valid id for a QOM object # diff --git a/qapi/run-state.json b/qapi/run-state.json index dd0770b379..789fc34559 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -395,10 +395,7 @@ # # @panic: @PanicAction action taken on guest panic. # -# @watchdog: @WatchdogAction action taken when watchdog timer expires -# . -# -# Returns: Nothing on success. +# @watchdog: @WatchdogAction action taken when watchdog timer expires. # # Since: 6.0 # diff --git a/qapi/tpm.json b/qapi/tpm.json index 07a73e5f2b..1577b5c259 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -166,8 +166,6 @@ # # Return information about the TPM device # -# Returns: @TPMInfo on success -# # Since: 1.5 # # Example: diff --git a/qapi/transaction.json b/qapi/transaction.json index 78cc21800d..5749c133d4 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -234,8 +234,6 @@ # execution of the transaction. See @TransactionProperties for # additional detail. # -# Returns: nothing on success -# # Errors: # Any errors from commands in the transaction # diff --git a/qapi/ui.json b/qapi/ui.json index 199a412c5a..1726f15429 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -78,9 +78,6 @@ # # Set the password of a remote display server. # -# Returns: -# - Nothing on success -# # Errors: # - If Spice is not enabled, DeviceNotFound # @@ -142,9 +139,6 @@ # # Expire the password of a remote display server. # -# Returns: -# - Nothing on success -# # Errors: # - If @protocol is 'spice' and Spice is not active, # DeviceNotFound @@ -191,8 +185,6 @@ # # @format: image format for screendump. (default: ppm) (Since 7.1) # -# Returns: Nothing on success -# # Since: 0.14 # # Example: @@ -1040,9 +1032,6 @@ # @hold-time: time to delay key up events, milliseconds. Defaults to # 100 # -# Returns: -# - Nothing on success -# # Errors: # - If key is unknown or redundant, GenericError # @@ -1265,8 +1254,6 @@ # # @events: List of InputEvent union. # -# Returns: Nothing on success. -# # Since: 2.6 # # Note: The consoles are visible in the qom tree, under @@ -1611,8 +1598,6 @@ # # Reload display configuration. # -# Returns: Nothing on success. -# # Since: 6.0 # # Example: @@ -1670,8 +1655,6 @@ # # Update display configuration. # -# Returns: Nothing on success. -# # Since: 7.1 # # Example: diff --git a/qapi/yank.json b/qapi/yank.json index a457284b45..fffb39a397 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -78,9 +78,6 @@ # # @instances: the instances to be yanked # -# Returns: -# - Nothing on success -# # Errors: # - @DeviceNotFound error, if any of the YankInstances doesn't exist # From patchwork Tue Feb 27 11:39:14 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573599 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 25FD3C54798 for ; Tue, 27 Feb 2024 11:41:37 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revoN-0000Dl-0c; Tue, 27 Feb 2024 06:39:51 -0500 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 1revoH-0000BZ-5T for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:45 -0500 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 1revo0-0005U3-7N for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:43 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033965; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=PB5/0Iw/Gaz6NFYOrNywdhK6UvD4Tt2ZmhVytaTsAzc=; b=Pp13yxh+XMxevqomOibDUGQqVmBXaiWEK5WANsVWu6UgiS72d8nYOaH7uCmR6HG0kNadnj 5sOxWgfWQKNPLdarKZEsu83WENVExBG0/I2Kjr7oRcdgpFWmdmgQ76Mt93TFDS55c+MEwY amOagFHfK5ghsGPV+gzKEmRmCUY/AVI= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-78-Kg_FPme3P-2xjPXujBEenw-1; Tue, 27 Feb 2024 06:39:23 -0500 X-MC-Unique: Kg_FPme3P-2xjPXujBEenw-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 79E43381D4A7; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 583D21803; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 39EB721E60F3; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 06/13] qapi: Clean up "Returns" sections Date: Tue, 27 Feb 2024 12:39:14 +0100 Message-ID: <20240227113921.236097-7-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Drop list markup, since there's just one item left. Drop "on success" where it is redundant with "Returns:". Signed-off-by: Markus Armbruster --- qapi/block-core.json | 4 ++-- qapi/machine.json | 4 ++-- qapi/misc.json | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 94b01deffc..1874f880a8 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -2457,7 +2457,7 @@ # @unstable: This command is meant for debugging. # # Returns: -# - BlockDirtyBitmapSha256 on success +# BlockDirtyBitmapSha256 # # Errors: # - If @node is not a valid block device, DeviceNotFound @@ -6084,7 +6084,7 @@ # @name: optional the snapshot's name to be deleted # # Returns: -# - SnapshotInfo on success +# SnapshotInfo # # Errors: # - If @device is not a valid block device, GenericError diff --git a/qapi/machine.json b/qapi/machine.json index 7d3ca33683..bb5a178909 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1090,7 +1090,7 @@ # Return information about the balloon device. # # Returns: -# - @BalloonInfo on success +# @BalloonInfo # # Errors: # - If the balloon driver is enabled but not functional because @@ -1156,7 +1156,7 @@ # message from the guest. # # Returns: -# - @HvBalloonInfo on success +# @HvBalloonInfo # # Errors: # - If no hv-balloon device is present, guest memory status diff --git a/qapi/misc.json b/qapi/misc.json index 015388aa3e..1b0c5dad88 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -332,7 +332,7 @@ # @opaque: A free-form string that can be used to describe the fd. # # Returns: -# - @AddfdInfo on success +# @AddfdInfo # # Errors: # - If file descriptor was not received, GenericError From patchwork Tue Feb 27 11:39:15 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573595 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 51754C54E4A for ; Tue, 27 Feb 2024 11:41:25 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revoC-00008P-9Z; Tue, 27 Feb 2024 06:39:40 -0500 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 1revo7-0008WG-6p for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:35 -0500 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 1revnz-0005Ub-TU for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:34 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033967; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=QqSlooSzFPn2Ejlr0CJ6VUNx+7tJPc2BMa29RAvjesI=; b=Ldy5hwUGW1w2mYQkrD+BN+W956iEKoRcBSNPtffMz+sxyN1MdLqr0JUzXXl/M+8V6bIOqN +EkvC1EhdiVGdlZOszDBXzJ3bt8vLRG7SZIKdRFsZfznARH9Z4k+SGXB/ZGEMGJVaTtkr1 p2u94PUKWwOmEq2JaNh60cxp/pD7ekk= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-631-pbq_T78jN4OaKQW9pdLLPA-1; Tue, 27 Feb 2024 06:39:23 -0500 X-MC-Unique: pbq_T78jN4OaKQW9pdLLPA-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 7D30C88B769; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 594EE20169D6; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 3D8FB21E60F4; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 07/13] qapi/yank: Tweak @yank's error description for consistency Date: Tue, 27 Feb 2024 12:39:15 +0100 Message-ID: <20240227113921.236097-8-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.4 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Phrase it like "If , ", like we do elsewhere. Signed-off-by: Markus Armbruster --- qapi/yank.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/yank.json b/qapi/yank.json index fffb39a397..89f2f4d199 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -79,7 +79,7 @@ # @instances: the instances to be yanked # # Errors: -# - @DeviceNotFound error, if any of the YankInstances doesn't exist +# - If any of the YankInstances doesn't exist, DeviceNotFound # # Example: # From patchwork Tue Feb 27 11:39:16 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573589 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id AE2E4C54E51 for ; Tue, 27 Feb 2024 11:40:13 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revoA-00006h-Th; Tue, 27 Feb 2024 06:39:38 -0500 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 1revo8-000064-TT for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:36 -0500 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 1revo0-0005Ud-3x for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:36 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033967; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=yP+4dHnTw39PPS2vNQeNibBeQst0CddquIapG5UlmEc=; b=FV/PwWWOuVwCCyiV09/BLuUH4ngJY524+iTvOFPA8q8RKSNPlRgNw/+SzCVpLdI3lZmaiS YQvQw9byXcJuy0TpY/qrv6zOyl+AKZu02jskMLX/YKt361xJnb9dmtcBm0m6FNtbFx0Ofe w50xNovtD4IXhMta+XFwex/cnOj5N+I= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-631-qTiXllKVM8KF1jzPaStIGQ-1; Tue, 27 Feb 2024 06:39:23 -0500 X-MC-Unique: qTiXllKVM8KF1jzPaStIGQ-1 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 7FE021C05AAB; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 5D46C40166A5; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 40AF421E60F5; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 08/13] qga/qapi-schema: Move error documentation to new "Errors" sections Date: Tue, 27 Feb 2024 12:39:16 +0100 Message-ID: <20240227113921.236097-9-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.2 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Signed-off-by: Markus Armbruster Reviewed-by: Konstantin Kostiuk --- qga/qapi-schema.json | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index b8efe31897..c5f2ac8f59 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -561,9 +561,8 @@ # could also exit (or set its status to "shutdown") due to other # reasons. # -# The following errors may be returned: -# -# - If suspend to disk is not supported, Unsupported +# Errors: +# - If suspend to disk is not supported, Unsupported # # Notes: It's strongly recommended to issue the guest-sync command # before sending commands when the guest resumes @@ -598,9 +597,8 @@ # 2. Issue the query-status QMP command to confirm the VM status is # "suspended" # -# The following errors may be returned: -# -# - If suspend to ram is not supported, Unsupported +# Errors: +# - If suspend to ram is not supported, Unsupported # # Notes: It's strongly recommended to issue the guest-sync command # before sending commands when the guest resumes @@ -634,9 +632,8 @@ # 2. Issue the query-status QMP command to confirm the VM status is # "suspended" # -# The following errors may be returned: -# -# - If hybrid suspend is not supported, Unsupported +# Errors: +# - If hybrid suspend is not supported, Unsupported # # Notes: It's strongly recommended to issue the guest-sync command # before sending commands when the guest resumes @@ -796,9 +793,6 @@ # - 0: # if the @vcpus list was empty on input. Guest state has not # been changed. Otherwise, -# - Error: -# processing the first node of @vcpus failed for the reason -# returned. Guest state has not been changed. Otherwise, # - < length(@vcpus): # more than zero initial nodes have been processed, but not the # entire @vcpus list. Guest state has changed accordingly. To @@ -808,6 +802,10 @@ # - length(@vcpus): # call successful. # +# Errors: +# - If the reconfiguration of the first node in @vcpus failed. +# Guest state has not been changed. +# # Since: 1.5 ## { 'command': 'guest-set-vcpus', From patchwork Tue Feb 27 11:39:17 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573598 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 9B89BC54798 for ; Tue, 27 Feb 2024 11:41:29 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revoH-0000B7-3D; Tue, 27 Feb 2024 06:39:45 -0500 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 1revoC-00008b-V8 for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:40 -0500 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 1revo0-0005Uf-Nh for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:40 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033967; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=BS5qxS6Y7vFDvl65GsGPtJ391Xu6yhC+wlpLeqZvGwI=; b=gKCsKqLUtLkfITbUqVijNyXYStYIWC2HLEYGm/5TPk4BS7Nhwoq1SwIqTFJeH7wYKnWtdt yLEKx2eF55CGgJk9SfZk/olggDd9Ir84JN/Cd1uFV0HwKzNJ30kwhSP0U90LoZxiU3sZEa 3vsP82ge8u45UKSvySyNVBdH8hwduMc= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-612-AvOQ1olJPxCgarJB0U79uw-1; Tue, 27 Feb 2024 06:39:23 -0500 X-MC-Unique: AvOQ1olJPxCgarJB0U79uw-1 Received: from smtp.corp.redhat.com (int-mx09.intmail.prod.int.rdu2.redhat.com [10.11.54.9]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 882DF3C02762; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 658A7492BCF; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 43CEF21E5A40; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 09/13] qga/qapi-schema: Delete useless "Returns" sections Date: Tue, 27 Feb 2024 12:39:17 +0100 Message-ID: <20240227113921.236097-10-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.9 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Signed-off-by: Markus Armbruster Reviewed-by: Konstantin Kostiuk --- qga/qapi-schema.json | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index c5f2ac8f59..636c2c5697 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -153,8 +153,6 @@ # @time: time of nanoseconds, relative to the Epoch of 1970-01-01 in # UTC. # -# Returns: Nothing on success. -# # Since: 1.5 ## { 'command': 'guest-set-time', @@ -245,8 +243,6 @@ # # @handle: filehandle returned by guest-file-open # -# Returns: Nothing on success. -# # Since: 0.15.0 ## { 'command': 'guest-file-close', @@ -399,8 +395,6 @@ # # @handle: filehandle returned by guest-file-open # -# Returns: Nothing on success. -# # Since: 0.15.0 ## { 'command': 'guest-file-flush', @@ -1077,8 +1071,6 @@ # transmission, even if already crypt()d, to ensure it is 8-bit safe # when passed as JSON. # -# Returns: Nothing on success. -# # Since: 2.3 ## { 'command': 'guest-set-user-password', @@ -1602,8 +1594,6 @@ # # @reset: ignore the existing content, set it with the given keys only # -# Returns: Nothing on success. -# # Since: 5.2 ## { 'command': 'guest-ssh-add-authorized-keys', @@ -1622,8 +1612,6 @@ # @keys: the public keys to remove (in OpenSSH/sshd(8) authorized_keys # format) # -# Returns: Nothing on success. -# # Since: 5.2 ## { 'command': 'guest-ssh-remove-authorized-keys', From patchwork Tue Feb 27 11:39:18 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573593 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 748EEC54798 for ; Tue, 27 Feb 2024 11:40:40 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revoC-00008W-Qv; Tue, 27 Feb 2024 06:39:40 -0500 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 1revoA-00006R-0L for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:38 -0500 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 1revo0-0005UC-2l for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:37 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033966; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=hLW16ULpgIlSW/cqpVfRJAq3Ma72L+DbkYr6s0ZmzHc=; b=IDMAr/703ga+0o/dV8vBWXkfZ7/S1sip65EKBaDoOTKdIY38/smrXZRINsZiCJBbb8qWhJ Dl0RbiSQ+QZR5UGVAJuAwjnqsDkVo0oxdGcME3Zo/M9utlBJ6Z74de/6Cd9QQE+htGbVn5 4Clb0lmLBW7TTBzXZfb0a1hGr7ZrrbM= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-683-16SPenSXPP24ZLNY3CaJ9g-1; Tue, 27 Feb 2024 06:39:24 -0500 X-MC-Unique: 16SPenSXPP24ZLNY3CaJ9g-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 8F92F88B768; Tue, 27 Feb 2024 11:39:24 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 6D8932166B5E; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 46F2B21E5A41; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 10/13] qga/qapi-schema: Clean up "Returns" sections Date: Tue, 27 Feb 2024 12:39:18 +0100 Message-ID: <20240227113921.236097-11-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.6 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Drop "on success" where it is redundant with "Returns:". Signed-off-by: Markus Armbruster Reviewed-by: Konstantin Kostiuk --- qga/qapi-schema.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 636c2c5697..326d324901 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -228,7 +228,7 @@ # # @mode: open mode, as per fopen(), "r" is the default. # -# Returns: Guest file handle on success. +# Returns: Guest file handle # # Since: 0.15.0 ## @@ -277,7 +277,7 @@ # @count: maximum number of bytes to read (default is 4KB, maximum is # 48MB) # -# Returns: @GuestFileRead on success. +# Returns: @GuestFileRead # # Since: 0.15.0 ## @@ -312,7 +312,7 @@ # @count: bytes to write (actual bytes, after base64-decode), default # is all content in buf-b64 buffer after base64 decoding # -# Returns: @GuestFileWrite on success. +# Returns: @GuestFileWrite # # Since: 0.15.0 ## @@ -379,7 +379,7 @@ # # @whence: Symbolic or numeric code for interpreting offset # -# Returns: @GuestFileSeek on success. +# Returns: @GuestFileSeek # # Since: 0.15.0 ## @@ -723,7 +723,7 @@ # # Get list of guest IP addresses, MAC addresses and netmasks. # -# Returns: List of GuestNetworkInterface on success. +# Returns: List of GuestNetworkInterface # # Since: 1.1 ## @@ -1247,7 +1247,7 @@ # # @pid: pid returned from guest-exec # -# Returns: GuestExecStatus on success. +# Returns: GuestExecStatus # # Since: 2.5 ## @@ -1315,7 +1315,7 @@ # @capture-output: bool flag to enable capture of stdout/stderr of # running process. defaults to false. # -# Returns: PID on success. +# Returns: PID # # Since: 2.5 ## @@ -1344,7 +1344,7 @@ # or even present in DNS or some other name service at all. It need # not even be unique on your local network or site, but usually it is. # -# Returns: the host name of the machine on success +# Returns: the host name of the machine # # Since: 2.10 ## From patchwork Tue Feb 27 11:39:19 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573596 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 3BC8FC5478C for ; Tue, 27 Feb 2024 11:41:25 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revoI-0000CD-4o; Tue, 27 Feb 2024 06:39:46 -0500 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 1revo7-0008WE-6P for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:35 -0500 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 1revnz-0005Uj-Vn for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:34 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033967; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=hTSIV2PnHuSPoa1C+gFm8bCyXTRYgB8cCk6z5RHAu/o=; b=SNVOGZgeQSeTNHNA6c6VIlIB3DLHum2krsgN2kpKqTQYVkAgL90VN75pk7gv8/hJXFRCDu IL73K814HqrOy0W4y71KtwtINJLa4Cj7hdE+xVWp4Zrdaasw5Z0tnjjVQsHlIstfHnYvQk A6jkVqonDcnO0VDhy2uy4D189bTt2S4= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-612-QktF-KDpO1-ayMNQhr_pCg-1; Tue, 27 Feb 2024 06:39:23 -0500 X-MC-Unique: QktF-KDpO1-ayMNQhr_pCg-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 95A8528B6982; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 7368814EF; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 49F3521E66D0; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 11/13] qga/qapi-schema: Tweak documentation of fsfreeze commands Date: Tue, 27 Feb 2024 12:39:19 +0100 Message-ID: <20240227113921.236097-12-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org "Returns:" sections of guest-fsfreeze-freeze and guest-fsfreeze-freeze-list describe both command behavior and success response. Move behavior out, so "Returns:" is only about success response. Signed-off-by: Markus Armbruster Reviewed-by: Konstantin Kostiuk --- qga/qapi-schema.json | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 326d324901..2ea1022092 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -437,15 +437,16 @@ # command succeeded, you may call @guest-fsfreeze-thaw later to # unfreeze. # +# On error, all filesystems will be thawed. If no filesystems are +# frozen as a result of this call, then @guest-fsfreeze-status will +# remain "thawed" and calling @guest-fsfreeze-thaw is not necessary. +# +# Returns: Number of file systems currently frozen. +# # Note: On Windows, the command is implemented with the help of a # Volume Shadow-copy Service DLL helper. The frozen state is # limited for up to 10 seconds by VSS. # -# Returns: Number of file systems currently frozen. On error, all -# filesystems will be thawed. If no filesystems are frozen as a -# result of this call, then @guest-fsfreeze-status will remain -# "thawed" and calling @guest-fsfreeze-thaw is not necessary. -# # Since: 0.15.0 ## { 'command': 'guest-fsfreeze-freeze', @@ -457,12 +458,13 @@ # Sync and freeze specified guest filesystems. See also # @guest-fsfreeze-freeze. # +# On error, all filesystems will be thawed. +# # @mountpoints: an array of mountpoints of filesystems to be frozen. # If omitted, every mounted filesystem is frozen. Invalid mount # points are ignored. # -# Returns: Number of file systems currently frozen. On error, all -# filesystems will be thawed. +# Returns: Number of file systems currently frozen. # # Since: 2.2 ## From patchwork Tue Feb 27 11:39:20 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573592 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 12C8BC54E4A for ; Tue, 27 Feb 2024 11:40:26 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revoJ-0000Cl-0S; Tue, 27 Feb 2024 06:39:47 -0500 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 1revoB-00007S-Pa for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:39 -0500 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 1revo0-0005Ua-IL for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:39 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033967; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=iOyKYKqRoPaaHWmBT2bZL36cIPhdyLGP1VWh7u2Hxwg=; b=CYkmilAsf987FQ8wpqLHanzW38NFqxW1r/GJ0OqE4jOfiH36UR3mlkaQf1bzr5w2oorugy g4EX7gZj5YMBpPzoXbvbvuLCwch0USnWJwtcuqXVgwVxcNflcykT6doC/uJVt1wb/L3zwR WrCtFscWvNOCh1YnTRn9bIgVX1XiaoM= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-78-Tke-jfdWOVug7rXdmi7eOA-1; Tue, 27 Feb 2024 06:39:23 -0500 X-MC-Unique: Tke-jfdWOVug7rXdmi7eOA-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 98F6088B773; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 76AE1C0348E; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 4CD5E21E5A47; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 12/13] qga/qapi-schema: Fix guest-set-memory-blocks documentation Date: Tue, 27 Feb 2024 12:39:20 +0100 Message-ID: <20240227113921.236097-13-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.8 Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01, T_SPF_HELO_TEMPERROR=0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Documentation claims the command can "return NULL". "NULL" doesn't exist in JSON. "null" does, but the command returns lists, and null isn't. Correct documentation to "return an empty list". Signed-off-by: Markus Armbruster Reviewed-by: Konstantin Kostiuk --- qga/qapi-schema.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 2ea1022092..9554b566a7 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -1176,9 +1176,9 @@ # @GuestMemoryBlockResponse, which is corresponding to the input # list. # -# Note: it will return NULL if the @mem-blks list was empty on -# input, or there is an error, and in this case, guest state will -# not be changed. +# Note: it will return an empty list if the @mem-blks list was +# empty on input, or there is an error, and in this case, guest +# state will not be changed. # # Since: 2.3 ## From patchwork Tue Feb 27 11:39:21 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13573597 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id CF1A0C54798 for ; Tue, 27 Feb 2024 11:41:25 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1revo7-00004q-Gk; Tue, 27 Feb 2024 06:39:35 -0500 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 1revo4-0008Uz-Kv for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:32 -0500 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 1revnz-0005U5-RB for qemu-devel@nongnu.org; Tue, 27 Feb 2024 06:39:32 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1709033965; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=DCu5W4DZXqoylOpRikofvUiqXc8bi0eLzFPQNwRB3Rw=; b=GVVklKNieYHLF85T1j/zRVCPsDVZAQ8QE6Bc/LS5smh8SE4eKWakrfiX9K4T8gUIW0BVpw HDUr20rO+NF99uYCxSArzUCZ2u+1lpb0gzVDXlkagfjrlX2s8TRlu0wZ32cHO5nyljs33n udMQWXCPB4e7KPl7mCFJjpDekss1rRQ= Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-629-3CusvHN_MDOCmOKTWyjuHg-1; Tue, 27 Feb 2024 06:39:24 -0500 X-MC-Unique: 3CusvHN_MDOCmOKTWyjuHg-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id B3AD329AA384; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.193.4]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 91B0AC0348F; Tue, 27 Feb 2024 11:39:23 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 4FB5A21E5A5A; Tue, 27 Feb 2024 12:39:21 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, jsnow@redhat.com, eblake@redhat.com, kkostiuk@redhat.com Subject: [PATCH 13/13] qapi: Reject "Returns" section when command doesn't return anything Date: Tue, 27 Feb 2024 12:39:21 +0100 Message-ID: <20240227113921.236097-14-armbru@redhat.com> In-Reply-To: <20240227113921.236097-1-armbru@redhat.com> References: <20240227113921.236097-1-armbru@redhat.com> MIME-Version: 1.0 Content-type: text/plain X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.8 Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.014, 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_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 7 ++++++- tests/qapi-schema/doc-invalid-return2.err | 1 + tests/qapi-schema/doc-invalid-return2.json | 7 +++++++ tests/qapi-schema/doc-invalid-return2.out | 0 tests/qapi-schema/meson.build | 1 + 5 files changed, 15 insertions(+), 1 deletion(-) create mode 100644 tests/qapi-schema/doc-invalid-return2.err create mode 100644 tests/qapi-schema/doc-invalid-return2.json create mode 100644 tests/qapi-schema/doc-invalid-return2.out diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index a32b2c7e7f..d8f76060b8 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -721,7 +721,12 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: self.features[feature.name].connect(feature) def check_expr(self, expr: QAPIExpression) -> None: - if 'command' not in expr: + if 'command' in expr: + if self.returns and 'returns' not in expr: + raise QAPISemError( + self.returns.info, + "'Returns' section, but command doesn't return anything") + else: if self.returns: raise QAPISemError( self.returns.info, diff --git a/tests/qapi-schema/doc-invalid-return2.err b/tests/qapi-schema/doc-invalid-return2.err new file mode 100644 index 0000000000..c3d0c7a452 --- /dev/null +++ b/tests/qapi-schema/doc-invalid-return2.err @@ -0,0 +1 @@ +doc-invalid-return2.json:5: 'Returns' section, but command doesn't return anything diff --git a/tests/qapi-schema/doc-invalid-return2.json b/tests/qapi-schema/doc-invalid-return2.json new file mode 100644 index 0000000000..37883d4fea --- /dev/null +++ b/tests/qapi-schema/doc-invalid-return2.json @@ -0,0 +1,7 @@ +# Command doesn't return anything + +## +# @foo: +# Returns: blah +## +{ 'command': 'foo' } diff --git a/tests/qapi-schema/doc-invalid-return2.out b/tests/qapi-schema/doc-invalid-return2.out new file mode 100644 index 0000000000..e69de29bb2 diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 4b8329d070..0f479d9317 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -79,6 +79,7 @@ schemas = [ 'doc-invalid-end.json', 'doc-invalid-end2.json', 'doc-invalid-return.json', + 'doc-invalid-return2.json', 'doc-invalid-section.json', 'doc-invalid-start.json', 'doc-missing-colon.json',