From nobody Sat Nov 15 09:24:00 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1752740537; cv=none; d=zohomail.com; s=zohoarc; b=BqiO3072S8YF8qRROb3E2Hz1n5BOeph5ryjd2juqkhDHNYwX4Vj2fVMv2q5WXr7sFySpvDlbyP77jyYwMTtKhpVYEoljRTBZ+bxZOYRBm0Lc3CPN4xdZcODWHTS+WFbq8s/JWgG+2cK3ATk3NRUFwHCdk5kk1PM2MBvt7ixSwKo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1752740537; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=Yj9/HwS3k1M0O5YACAdx/JDck9GGndfhiwLtBfQycmo=; b=LvsL5a36cF2guym/6Oli+5u7Iy1aSloveWiBlLzGasGF2B7RkBDOXUroCE0rXs7cTdl2IwKmv/IFNhDAUeXzGKv23X2Z2WAo9QFoWqcV3WWfhLBpu4+CjsC93dU3sRerhfGIBZUOZqQivLZO1ZgnC36FiA9mHhm4qFCBWBTCCus= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1752740537813790.7827681347741; Thu, 17 Jul 2025 01:22:17 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ucJsU-0005de-2v; Thu, 17 Jul 2025 04:22:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ucJrv-0005D3-8W for qemu-devel@nongnu.org; Thu, 17 Jul 2025 04:21:35 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ucJrr-0000wr-AY for qemu-devel@nongnu.org; Thu, 17 Jul 2025 04:21:30 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-110-Ury0_haMP6ONbePMz1xX5w-1; Thu, 17 Jul 2025 04:21:21 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id F20D51800C37; Thu, 17 Jul 2025 08:21:20 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.45.242.6]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 79F6730001B9; Thu, 17 Jul 2025 08:21:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B07B521E6924; Thu, 17 Jul 2025 10:21:17 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1752740485; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Yj9/HwS3k1M0O5YACAdx/JDck9GGndfhiwLtBfQycmo=; b=BZhG8WU0veOH4YZh3JaPyEAb+NfiS+IkbvAtPJm4lFgRdtgg5dBWAmQRREOcZDDB/0IUee FzvSlFycBuHlLDgDFbIePucqR6BF0+0/Af6zCn1RTx3uIWKhEeQKBCxLTNmbcO2fHYPbkg 79JikmZD6kecGNQIRsCCU3mPnbufbD4= X-MC-Unique: Ury0_haMP6ONbePMz1xX5w-1 X-Mimecast-MFC-AGG-ID: Ury0_haMP6ONbePMz1xX5w_1752740481 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: eblake@redhat.com, michael.roth@amd.com, kkostiuk@redhat.com, jsnow@redhat.com Subject: [PATCH 1/4] qga: Fix guest-network-get-route return value documentation Date: Thu, 17 Jul 2025 10:21:14 +0200 Message-ID: <20250717082117.3767754-2-armbru@redhat.com> In-Reply-To: <20250717082117.3767754-1-armbru@redhat.com> References: <20250717082117.3767754-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1752740539777116600 Content-Type: text/plain; charset="utf-8" Tagged sections are only recognized at the beginning of a paragraph. guest-network-get-route's Returns: isn't, and therefore gets rendered as ordinary text within its paragraph: Retrieve information about route of network. Returns: List of route info of guest. Since there is no (recognized) Returns: section, the doc generator adds Return: [GuestNetworkRoute] Note: only since recent commit 636c96cd77d (qapi: Fix undocumented return values by generating something). Insert the required blank line so that Returns: is recognized. Result: Retrieve information about route of network. Return: [GuestNetworkRoute] -- List of route info of guest. Fixes: commit 8e326d36dd16 (qga/linux: Add new api 'guest-network-get-route= ') Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrang=C3=A9 --- qga/qapi-schema.json | 1 + 1 file changed, 1 insertion(+) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 6d770f7b8e..a569a14b55 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -1966,6 +1966,7 @@ # @guest-network-get-route: # # Retrieve information about route of network. +# # Returns: List of route info of guest. # # Since: 9.1 --=20 2.49.0 From nobody Sat Nov 15 09:24:00 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1752740537; cv=none; d=zohomail.com; s=zohoarc; b=JvHqfWTAnIMk6Z2+UPd1pQEguRbOl/aZ+CJKJzsTjxNgw2RDaEXYHvLROsYjjnlLcTPh7azaB4JspoJfqkb/HQZ1BlrTZce6dAZSLMO5VAEnG4rR550Y6UpDPrazLP1aoBvfiE3Igid7gFGn9Xzt+goK6uwJmDb45nbyXCPzPqM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1752740537; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=QxWqvkf2KdiB/qeLezzgRj6u3zI9mtMUQENXYB98ux0=; b=ZQEso8lty4dz9TgkrV+FfgNcxcwouv0jjaemVHmeSQ2Btk7nbrdqpa6gxRNk56nkvr1DnBVbygtlR5SPaF0hp0MXRFmNW7mIkPuDX/fYVbQd0VeiNUkV+ggzkDBs5L43MHF9gBPeNQB7R1gfi/Eix0hunxXCtUjhQztDwVZZ5eE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1752740537965834.469355787595; Thu, 17 Jul 2025 01:22:17 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ucJsP-0005XO-MV; Thu, 17 Jul 2025 04:22:02 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ucJrt-0005BI-IT for qemu-devel@nongnu.org; Thu, 17 Jul 2025 04:21:31 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ucJrp-0000wH-JN for qemu-devel@nongnu.org; Thu, 17 Jul 2025 04:21:29 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-361-nYaqBuTHPI-Mi_j30-SXAQ-1; Thu, 17 Jul 2025 04:21:21 -0400 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id CFC861800283; Thu, 17 Jul 2025 08:21:20 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.45.242.6]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 6B40A19560A1; Thu, 17 Jul 2025 08:21:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B447B21E6925; Thu, 17 Jul 2025 10:21:17 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1752740483; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=QxWqvkf2KdiB/qeLezzgRj6u3zI9mtMUQENXYB98ux0=; b=UoM51pO569AWKTxK20hhGKZddp3d6mzftq7+jG8nKYVUb+AgzxjR28/n/nXSYzZTej9lvh yUTAsrKHxulJSBqlxQTsBO5z8P5pFNHdwdv88Z83bdbafs7JPmmkjouxsmU68OVj8d8Y5F 1gnz/TbEKrPiLCvoUeQzSuXjAIpMQxE= X-MC-Unique: nYaqBuTHPI-Mi_j30-SXAQ-1 X-Mimecast-MFC-AGG-ID: nYaqBuTHPI-Mi_j30-SXAQ_1752740480 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: eblake@redhat.com, michael.roth@amd.com, kkostiuk@redhat.com, jsnow@redhat.com Subject: [PATCH 2/4] qga: Remove trivial "Returns:" sections Date: Thu, 17 Jul 2025 10:21:15 +0200 Message-ID: <20250717082117.3767754-3-armbru@redhat.com> In-Reply-To: <20250717082117.3767754-1-armbru@redhat.com> References: <20250717082117.3767754-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1752740539839116600 Content-Type: text/plain; charset="utf-8" The QAPI doc generator recently started to auto-generate return documentation when there is no "Returns:" section (commit 636c96cd77d "qapi: Fix undocumented return values by generating something"). Remove "Returns:" sections where the auto-generated text is obviously no worse. For instance, guest-info's documentation changes from Return: GuestAgentInfo -- GuestAgentInfo to Return: GuestAgentInfo The auto-generated returns all are in the exact same spot. We did this for qapi/ in commit 0462da9d6b1 (qapi: remove trivial "Returns:" sections). Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrang=C3=A9 --- qga/qapi-schema.json | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index a569a14b55..a9cc9150dc 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -202,8 +202,6 @@ # # Get some information about the guest agent. # -# Returns: @GuestAgentInfo -# # Since: 0.15.0 ## { 'command': 'guest-info', @@ -285,8 +283,6 @@ # @count: maximum number of bytes to read (default is 4KB, maximum is # 48MB) # -# Returns: @GuestFileRead -# # Since: 0.15.0 ## { 'command': 'guest-file-read', @@ -320,8 +316,6 @@ # @count: bytes to write (actual bytes, after base64-decode), default # is all content in buf-b64 buffer after base64 decoding # -# Returns: @GuestFileWrite -# # Since: 0.15.0 ## { 'command': 'guest-file-write', @@ -387,8 +381,6 @@ # # @whence: Symbolic or numeric code for interpreting offset # -# Returns: @GuestFileSeek -# # Since: 0.15.0 ## { 'command': 'guest-file-seek', @@ -428,9 +420,6 @@ # # Get guest fsfreeze state. # -# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined -# below) -# # .. note:: This may fail to properly report the current state as a # result of some other guest processes having issued an fs # freeze/thaw. @@ -749,8 +738,6 @@ # # Get list of guest IP addresses, MAC addresses and netmasks. # -# Returns: List of GuestNetworkInterface -# # Since: 1.1 ## { 'command': 'guest-network-get-interfaces', @@ -1251,8 +1238,6 @@ # # Get information relating to guest memory blocks. # -# Returns: @GuestMemoryBlockInfo -# # Since: 2.3 ## { 'command': 'guest-get-memory-block-info', @@ -1298,8 +1283,6 @@ # # @pid: pid returned from guest-exec # -# Returns: GuestExecStatus -# # Since: 2.5 ## { 'command': 'guest-exec-status', @@ -1458,8 +1441,6 @@ # # Retrieves the timezone information from the guest. # -# Returns: A GuestTimezone dictionary. -# # Since: 2.10 ## { 'command': 'guest-get-timezone', @@ -1533,8 +1514,6 @@ # # Retrieve guest operating system information # -# Returns: @GuestOSInfo -# # Since: 2.10 ## { 'command': 'guest-get-osinfo', @@ -1604,8 +1583,6 @@ # # Retrieve information about device drivers in Windows guest # -# Returns: @GuestDeviceInfo -# # Since: 5.2 ## { 'command': 'guest-get-devices', @@ -1633,8 +1610,6 @@ # # @username: the user account to add the authorized keys # -# Returns: @GuestAuthorizedKeys -# # Since: 5.2 ## { 'command': 'guest-ssh-get-authorized-keys', --=20 2.49.0 From nobody Sat Nov 15 09:24:00 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1752740567; cv=none; d=zohomail.com; s=zohoarc; b=GsM0AUQP9+RXLbvZyEJXrMOzVx9u/sW6xfvrRBfogr04CqsUJNqu01WzN66OzPQFJU2QiR+bf4AxbC9nyWYUehC+0hk8MKMD9Rb6NZFlqPiQyCbRFKQ13EEcbvTUW0ce4H6LqYF+QhnwA6XyhamVbUxLhSM6lTMlGliXDifzo8w= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1752740567; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=g3wiLVeJG6eRNKooWYvuQr49qjdJy/RkIv0LfEcMu2s=; b=jRaym0jddwQz5zwhvKMjx8yDOVCTCfByU2cA+i5u5Jt/oz7h7aiG48lv6t5qREK7IpEIFD93snsTWKgnGUblIzCRR+qJJvWWG7qHV1+kfuGwm37PydNZ7NlFWRrfI5sKvRIb5iROpK6Xnl5n0+OstB0lcTy7YDgtiti2Q4HaIK0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1752740567419956.4779249772341; Thu, 17 Jul 2025 01:22:47 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ucJsS-0005c3-7V; Thu, 17 Jul 2025 04:22:05 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ucJrv-0005Co-0C for qemu-devel@nongnu.org; Thu, 17 Jul 2025 04:21:31 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ucJrq-0000wl-Qu for qemu-devel@nongnu.org; Thu, 17 Jul 2025 04:21:30 -0400 Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-265-HuBOc1kMMSmAEPzixxjn_A-1; Thu, 17 Jul 2025 04:21:21 -0400 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id EE77F19560B4; Thu, 17 Jul 2025 08:21:20 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.45.242.6]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 7EF3A195608D; Thu, 17 Jul 2025 08:21:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B83D321E6935; Thu, 17 Jul 2025 10:21:17 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1752740485; 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=g3wiLVeJG6eRNKooWYvuQr49qjdJy/RkIv0LfEcMu2s=; b=PuDkGR8Lq+tvP8b8YB0N4Q2BjLZbmHfbhUpnZzR9JDodnUtxQ4bQ7epUcPgwBVTZNksmdc klBTlTsx4yL+16aStphm4FgAjwRL9als5Yt1iIbjjA4Oxeg0jwmucjLyoMVxbE3RLz9SUT RuC42UlIuO+a2sbYaPil4M35I8QSMbw= X-MC-Unique: HuBOc1kMMSmAEPzixxjn_A-1 X-Mimecast-MFC-AGG-ID: HuBOc1kMMSmAEPzixxjn_A_1752740481 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: eblake@redhat.com, michael.roth@amd.com, kkostiuk@redhat.com, jsnow@redhat.com Subject: [PATCH 3/4] qga: Rephrase return docs to avoid type name Date: Thu, 17 Jul 2025 10:21:16 +0200 Message-ID: <20250717082117.3767754-4-armbru@redhat.com> In-Reply-To: <20250717082117.3767754-1-armbru@redhat.com> References: <20250717082117.3767754-1-armbru@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1752740567961116600 "Returns: " is rendered like Return: =E2=80=93 Mentioning the type in the description again is commonly redundant. There is just one such description. Rephrase it not to mention the type. We did this for qapi/ in commit f7296f8de5c (qapi: rephrase return docs to avoid type name). Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrang=C3=A9 --- qga/qapi-schema.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index a9cc9150dc..6c26ace3c9 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -534,8 +534,7 @@ # discarded. The default value is zero, meaning "discard every # free block". # -# Returns: A @GuestFilesystemTrimResponse which contains the status of -# all trimmed paths. (since 2.4) +# Returns: status of all trimmed paths. (since 2.4) # # Since: 1.2 ## --=20 2.49.0 From nobody Sat Nov 15 09:24:00 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1752740611; cv=none; d=zohomail.com; s=zohoarc; b=jq/Ko/SnwZNlafzYUny/a8WEplDeslX2ssuqsNs6StODn5pIaG+WfJRXzhlFhm23ePzRP952n9PBxtPFG33VtJOjgVQbqIO/2eEGNLKBflKopQdVaxq8uPIqIGiYLg9X5pq4Bjgdpk0JufnNjgLuKzB/wRbdzrJVkfGkvHJch0U= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1752740611; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=9xAwGXP+CStL0izplHa1IHGOqPpERz0L6soxz47mg7c=; b=k6xMYqVaP3GPPyuDq7GuhGPozy8IrmJkBeAhgJ3Av1STw4kP2e6oY7rip/eh8k1QkLBYmATfiCeSUwLYUh3jeVcQxlgCdNIWs93zqfkus6DcaBmlvAuUoa6fWJRdnIlEKyQx+kjcJErNI/uwHN2a99yfQ9GtdzPo0fIErAQdWzY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1752740611285122.9888302326724; Thu, 17 Jul 2025 01:23:31 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ucJsX-0005oU-NU; Thu, 17 Jul 2025 04:22:10 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ucJrv-0005Cp-1B for qemu-devel@nongnu.org; Thu, 17 Jul 2025 04:21:31 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ucJrp-0000wU-JH for qemu-devel@nongnu.org; Thu, 17 Jul 2025 04:21:30 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-381-g4ZgAooiNQSzk9tyciaCig-1; Thu, 17 Jul 2025 04:21:21 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 22B6E18004A7; Thu, 17 Jul 2025 08:21:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.45.242.6]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 5903530001BE; Thu, 17 Jul 2025 08:21:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id BC34021E675E; Thu, 17 Jul 2025 10:21:17 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1752740484; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=9xAwGXP+CStL0izplHa1IHGOqPpERz0L6soxz47mg7c=; b=cb6KzZ+7WuFEygpXhze9pl8HQUbk01nocx2UAlsV3GQpj07PTAQC3pe5Tbtzl2n3DStwMD TMeajUz7sHriw0fxkp2Ok+v2YvyvpWO8sDW4vo/0S4RWm1Rd+vPCK3r+qOXX0F0Dt7nO3/ MOqg/WvJXKfQreBSjMNo0bJktMB03e8= X-MC-Unique: g4ZgAooiNQSzk9tyciaCig-1 X-Mimecast-MFC-AGG-ID: g4ZgAooiNQSzk9tyciaCig_1752740481 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: eblake@redhat.com, michael.roth@amd.com, kkostiuk@redhat.com, jsnow@redhat.com Subject: [PATCH 4/4] qga: Add cross-references Date: Thu, 17 Jul 2025 10:21:17 +0200 Message-ID: <20250717082117.3767754-5-armbru@redhat.com> In-Reply-To: <20250717082117.3767754-1-armbru@redhat.com> References: <20250717082117.3767754-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1752740612699116600 Content-Type: text/plain; charset="utf-8" Enclose command and type names in `backquotes`, so they become links in generated HTML. We did this for qapi/ in merge commit 504632dcc631. Signed-off-by: Markus Armbruster Reviewed-by: Daniel P. Berrang=C3=A9 --- qga/qapi-schema.json | 50 ++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 6c26ace3c9..31d454999f 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -96,11 +96,11 @@ # In cases where a partial stale response was previously received by # the client, this cannot always be done reliably. One particular # scenario being if qemu-ga responses are fed character-by-character -# into a JSON parser. In these situations, using guest-sync-delimited +# into a JSON parser. In these situations, using `guest-sync-delimited` # may be optimal. # # For clients that fetch responses line by line and convert them to -# JSON objects, guest-sync should be sufficient, but note that in +# JSON objects, `guest-sync` should be sufficient, but note that in # cases where the channel is dirty some attempts at parsing the # response may result in a parser error. # @@ -247,7 +247,7 @@ # # Close an open file in the guest # -# @handle: filehandle returned by guest-file-open +# @handle: filehandle returned by `guest-file-open` # # Since: 0.15.0 ## @@ -278,7 +278,7 @@ # As this command is just for limited, ad-hoc debugging, such as log # file access, the number of bytes to read is limited to 48 MB. # -# @handle: filehandle returned by guest-file-open +# @handle: filehandle returned by `guest-file-open` # # @count: maximum number of bytes to read (default is 4KB, maximum is # 48MB) @@ -309,7 +309,7 @@ # # Write to an open file in the guest. # -# @handle: filehandle returned by guest-file-open +# @handle: filehandle returned by `guest-file-open` # # @buf-b64: base64-encoded string representing data to be written # @@ -340,7 +340,7 @@ ## # @QGASeek: # -# Symbolic names for use in @guest-file-seek +# Symbolic names for use in `guest-file-seek` # # @set: Set to the specified offset (same effect as 'whence':0) # @@ -355,7 +355,7 @@ ## # @GuestFileWhence: # -# Controls the meaning of offset to @guest-file-seek. +# Controls the meaning of offset to `guest-file-seek`. # # @value: Integral value (0 for set, 1 for cur, 2 for end), available # for historical reasons, and might differ from the host's or @@ -375,7 +375,7 @@ # current file position afterward. Also encapsulates ftell()'s # functionality, with offset=3D0 and whence=3D1. # -# @handle: filehandle returned by guest-file-open +# @handle: filehandle returned by `guest-file-open` # # @offset: bytes to skip over in the file stream # @@ -393,7 +393,7 @@ # # Write file changes buffered in userspace to disk/kernel buffers # -# @handle: filehandle returned by guest-file-open +# @handle: filehandle returned by `guest-file-open` # # Since: 0.15.0 ## @@ -434,12 +434,12 @@ # @guest-fsfreeze-freeze: # # Sync and freeze all freezable, local guest filesystems. If this -# command succeeded, you may call @guest-fsfreeze-thaw later to +# 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. +# 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. # @@ -457,7 +457,7 @@ # @guest-fsfreeze-freeze-list: # # Sync and freeze specified guest filesystems. See also -# @guest-fsfreeze-freeze. +# `guest-fsfreeze-freeze`. # # On error, all filesystems will be thawed. # @@ -482,7 +482,7 @@ # Returns: Number of file systems thawed by this call # # .. note:: If the return value does not match the previous call to -# guest-fsfreeze-freeze, this likely means some freezable filesystems +# `guest-fsfreeze-freeze`, this likely means some freezable filesystems # were unfrozen before this call, and that the filesystem state may # have changed before issuing this command. # @@ -513,7 +513,7 @@ ## # @GuestFilesystemTrimResponse: # -# @paths: list of @GuestFilesystemTrimResult per path that was trimmed +# @paths: list of `GuestFilesystemTrimResult` per path that was trimmed # # Since: 2.4 ## @@ -565,7 +565,7 @@ # Errors: # - If suspend to disk is not supported, Unsupported # -# .. note:: It's strongly recommended to issue the guest-sync command +# .. note:: It's strongly recommended to issue the `guest-sync` command # before sending commands when the guest resumes. # # Since: 1.1 @@ -585,7 +585,7 @@ # - pm-utils (via pm-hibernate) # - manual write into sysfs # -# IMPORTANT: guest-suspend-ram requires working wakeup support in +# IMPORTANT: `guest-suspend-ram` requires working wakeup support in # QEMU. You should check QMP command query-current-machine returns # wakeup-suspend-support: true before issuing this command. Failure # in doing so can result in a suspended guest that QEMU will not be @@ -602,7 +602,7 @@ # Errors: # - If suspend to ram is not supported, Unsupported # -# .. note:: It's strongly recommended to issue the guest-sync command +# .. note:: It's strongly recommended to issue the `guest-sync` command # before sending commands when the guest resumes. # # Since: 1.1 @@ -621,7 +621,7 @@ # - systemd hybrid-sleep # - pm-utils (via pm-suspend-hybrid) # -# IMPORTANT: guest-suspend-hybrid requires working wakeup support in +# IMPORTANT: `guest-suspend-hybrid` requires working wakeup support in # QEMU. You should check QMP command query-current-machine returns # wakeup-suspend-support: true before issuing this command. Failure # in doing so can result in a suspended guest that QEMU will not be @@ -638,7 +638,7 @@ # Errors: # - If hybrid suspend is not supported, Unsupported # -# .. note:: It's strongly recommended to issue the guest-sync command +# .. note:: It's strongly recommended to issue the `guest-sync` command # before sending commands when the guest resumes. # # Since: 1.1 @@ -1171,7 +1171,7 @@ ## # @GuestMemoryBlockResponse: # -# @phys-index: same with the 'phys-index' member of @GuestMemoryBlock. +# @phys-index: same with the 'phys-index' member of `GuestMemoryBlock`. # # @response: the result of memory block operation. # @@ -1277,10 +1277,10 @@ # @guest-exec-status: # # Check status of process associated with PID retrieved via -# guest-exec. Reap the process and associated metadata if it has +# `guest-exec`. Reap the process and associated metadata if it has # exited. # -# @pid: pid returned from guest-exec +# @pid: pid returned from `guest-exec` # # Since: 2.5 ## @@ -1301,7 +1301,7 @@ ## # @GuestExecCaptureOutputMode: # -# An enumeration of guest-exec capture modes. +# An enumeration of `guest-exec` capture modes. # # @none: do not capture any output # @@ -1324,7 +1324,7 @@ ## # @GuestExecCaptureOutput: # -# Controls what guest-exec output gets captures. +# Controls what `guest-exec` output gets captures. # # @flag: captures both stdout and stderr if true. Equivalent to # GuestExecCaptureOutputMode::all. (since 2.5) --=20 2.49.0