From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405059; cv=none; d=zohomail.com; s=zohoarc; b=QhUpaySS9NUqD2PCMLAvp0ldQREfJhO87uEI7sKsrqq1hnofBNl7bgiWi+ntjj/shprb+4KgVmSfjJEffZsR0zGkqa6MjgV61TXKqF+8CLlBPB3xPqu8qwtgIf9sSRxjMCwNvCxqMqhQh9qvtOuy7ig8kGfpDhPDuNkup3dnGkQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405059; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=L8vKga74pRM3kfsG4eoAqnDkVQzpJnsRghJB92EVAGE=; b=AYNt/XfuNMAKZAJVydGO5kMh2cJXn4j1ccPXrCURgyuBG6EWTxlHN98e4gr+1d+SYV9TgX0gZeXxM1uRIq4gnLj3OwuRD0kNpozAv1lDeNFAuYLVC4SyijpkVdm0b8q6hgoaeXQU71uTawzxSoXD/fYS4YNnvM+t38V0ycNpn6g= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405059276187.4295072354496; Mon, 24 Apr 2023 23:44:19 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNt-0003w6-Si; Tue, 25 Apr 2023 02:42:41 -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 1prCNq-0003rD-3Y for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:38 -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 1prCNk-0004Lz-4R for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:37 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-608-reT8RBDFNQiZGecR8YeAdQ-1; Tue, 25 Apr 2023 02:42:26 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 46E2F185A792; Tue, 25 Apr 2023 06:42:25 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id C01C044007; Tue, 25 Apr 2023 06:42:24 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B601021F1674; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404951; 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=L8vKga74pRM3kfsG4eoAqnDkVQzpJnsRghJB92EVAGE=; b=YJh1OVVhyehkTE3ZkHCnxB7YfAM2MnaqfEDpvcY8doKjLpT5wL1CourcUm0MPE+5S7EEzN u14DBOCHHS8BQgbiH+mp9O3fQFclT/SIbfJsUUQVCv2iQpYA+y1uMykliY52qfaP646QUz tGnqUd+tHUWhZmDddcUuhovNCi4tfk8= X-MC-Unique: reT8RBDFNQiZGecR8YeAdQ-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 01/16] qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status Date: Tue, 25 Apr 2023 08:42:08 +0200 Message-Id: <20230425064223.820979-2-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.5 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405060816100003 Delete "error state indicates", because it doesn't make sense. I suspect it was an accident. Signed-off-by: Markus Armbruster Reviewed-by: Konstantin Kostiuk Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- qga/qapi-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 796434ed34..f349345116 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -420,7 +420,7 @@ ## # @guest-fsfreeze-status: # -# Get guest fsfreeze state. error state indicates +# Get guest fsfreeze state. # # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below) # --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405115; cv=none; d=zohomail.com; s=zohoarc; b=MSA5jh+6hdSvVAmI4sG7hLScCXnRHOf+Y9OGqIJlTqToKhjuymRYfyT7iPJxWoFM3dTS9UyvlKsbBgfXkkFFUuk2+bQ+XldJ9ilLLRP5UHlwWp6YbYB8vF/Gfbs1aS7E/Fpd/G0RqYb4agJXO9lir72S+cZp+D/6ONahNx/e/04= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405115; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=et/NTq8Lv9MRiaDYgaw6B1pW7h9WoEKTiNzHaDsnN1s=; b=Bpdt2GP+9ga3RRVzBTWbHzLc+CcUceIivKmrH2vnJOVzbVUmPfC9xXsR170fcqb2778VKBpx2SN5KWmZ/TcGtHdetpz9kr6oy0FmZQ1p7MTV888NHM7y3FS/WdGZ/0B2i3YylrH9+4bm10RCL6iwQqoufMC6WRsaa8D5t9PRQ24= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 168240511545115.925763128043513; Mon, 24 Apr 2023 23:45:15 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNp-0003pF-5J; Tue, 25 Apr 2023 02:42:37 -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 1prCNm-0003jb-RD for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:34 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1prCNj-0004Ko-90 for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:34 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-647-elqNykDfPHq3cf7hiAH59g-1; Tue, 25 Apr 2023 02:42:25 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 4381E185A791; Tue, 25 Apr 2023 06:42:25 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BDC42C15BA0; Tue, 25 Apr 2023 06:42:24 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B902E21F1675; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404949; 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=et/NTq8Lv9MRiaDYgaw6B1pW7h9WoEKTiNzHaDsnN1s=; b=c46+JQLEL9lCbsA1YZXNHHKp8ZRxUh4v1F9S39NaEztj8VtqDx7QgsIsrfIenUHU0TCdpc bG+0AQ9cF3Mav/cnuTDC4ZzuF7bQH1H0/u4C4N6GhQQL3UvwSNcHnnP5GfVyjnkkYhTw1O E9LLQgpYELVXeDQ8RDwwu8O/2TXynW8= X-MC-Unique: elqNykDfPHq3cf7hiAH59g-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 02/16] qga/qapi-schema: Fix a misspelled reference Date: Tue, 25 Apr 2023 08:42:09 +0200 Message-Id: <20230425064223.820979-3-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.8 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405117335100011 Code returns a list of GuestNetworkInterface, documentation claims GuestNetworkInfo, which doesn't exist. Fix the documentation. Fixes: 3424fc9f16a1 (qemu-ga: add guest-network-get-interfaces command) Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- qga/qapi-schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index f349345116..bb9bac0655 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -722,7 +722,7 @@ # Get list of guest IP addresses, MAC addresses # and netmasks. # -# Returns: List of GuestNetworkInfo on success. +# Returns: List of GuestNetworkInterface on success. # # Since: 1.1 ## --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405144; cv=none; d=zohomail.com; s=zohoarc; b=BE5q6lW6uLvZaIF4yisbvogApUq7K475Yu+soSvzu+LFqUEwiXmHi8x7ABTrIpCgixPPPXBx7CiYxFbFo+SKjJ8X6I162OAlcKiam8ALh/TOkzc0p64j/VC13xxO9Gh17YrK+C+csI961S6Uu5lphm29VJyywM6eQ2b1YcikV8c= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405144; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=8OglO1GABAkMbLCBpRQLctyxPtXkCPvT3IrDIiXgx0I=; b=SY/rfQ7mWyIrfihs23NbygkfIXevSDTTJEnXdSQLgnYNz0/oCubGjveloYlelS13NpDHxbrswS03nhzjafq+iRhcGuhJKLw3DCwqDACo8A0H8jbIz0rgrJUI37zPCq+3leq967PbYHVCnS6h4WUru/456+N8xe9sJ0o/scvt5cY= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405144912502.91039471034594; Mon, 24 Apr 2023 23:45:44 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNu-0003wB-HE; Tue, 25 Apr 2023 02:42:42 -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 1prCNp-0003qL-GM for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:37 -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 1prCNj-0004Ln-Jh for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:37 -0400 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-608-UJN9eVifOHOnZaBVpotusg-1; Tue, 25 Apr 2023 02:42:25 -0400 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 431F13C0ED67; Tue, 25 Apr 2023 06:42:25 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BCFF92027046; Tue, 25 Apr 2023 06:42:24 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id BBEE421F1678; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404950; 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=8OglO1GABAkMbLCBpRQLctyxPtXkCPvT3IrDIiXgx0I=; b=RiWi5luW2FLFYikVw5DuOsPDxzfohGsFL8A2ziB/cDMMGcYwWyTYtkCx4nK7cFiW4QsA8b DAsBKhdjSi/H+5TozO77b7S47ov7DYHtXRUKodlkID/bB2RVXYkhevfbzHrP5ty9l3lItb jKDFD/ZtuR3owSlJNvBFQhjenvkABJk= X-MC-Unique: UJN9eVifOHOnZaBVpotusg-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 03/16] qapi: Fix misspelled references Date: Tue, 25 Apr 2023 08:42:10 +0200 Message-Id: <20230425064223.820979-4-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405146295100004 query-cpu-definitions returns a list of CpuDefinitionInfo, but documentation claims CpuDefInfo, which doesn't exist. query-migrate-capabilities returns a list of MigrationCapabilityStatus, but documentation claims MigrationCapabilitiesStatus, which doesn't exist. balloon and query-balloon can fail with KVMMissingCap, but documentation claims KvmMissingCap, which doesn't exist. Fix the documentation. Fixes: e4e31c6324af (qapi: add query-cpu-definitions command (v2)) Fixes: bbf6da32b5bd (Add migration capabilities) Fixes: d72f326431e2 (qapi: Convert balloon) Fixes: 96637bcdf9e0 (qapi: Convert query-balloon) Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau Reviewed-by: David Hildenbrand Reviewed-by: Juan Quintela --- qapi/machine-target.json | 2 +- qapi/machine.json | 4 ++-- qapi/migration.json | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 2e267fa458..b94fbdb65e 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -331,7 +331,7 @@ # # Return a list of supported virtual CPU definitions # -# Returns: a list of CpuDefInfo +# Returns: a list of CpuDefinitionInfo # # Since: 1.2 ## diff --git a/qapi/machine.json b/qapi/machine.json index 604b686e59..8c3c58c763 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1029,7 +1029,7 @@ # # Returns: - Nothing on success # - If the balloon driver is enabled but not functional because t= he KVM -# kernel module cannot support it, KvmMissingCap +# kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive # # Notes: This command just issues a request to the guest. When it returns, @@ -1067,7 +1067,7 @@ # # Returns: - @BalloonInfo on success # - If the balloon driver is enabled but not functional because t= he KVM -# kernel module cannot support it, KvmMissingCap +# kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive # # Since: 0.14 diff --git a/qapi/migration.json b/qapi/migration.json index c84fa10e86..87c174dca2 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -531,7 +531,7 @@ # # Returns information about the current migration capabilities status # -# Returns: @MigrationCapabilitiesStatus +# Returns: @MigrationCapabilityStatus # # Since: 1.2 # --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405080; cv=none; d=zohomail.com; s=zohoarc; b=ny5arNrmVI8/K0+P1dtvfy92MiQVTUyuuPY6PgIkdHjZUADKehQ2XEzcsvrGOCC97ulSTWBPYBnEYM7yBECPEDoZsedj32x/A6UVpgD7IJhql1qJ1G9WBphIki6DzxBt5e92+hHpIjPB6x82YeBNDhK9VZlZaII3gPv4uFKSHjY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405080; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=a7YqkyguldLJHFa6e+lj+gnk5EKBe9tfAPYkfiWyHWw=; b=nryJyAsQO+eOsmiv6xtSq1SGGApdIWnB0DJBPla5ME/E8SagfgYOo3BGtLFeD4m6oP1mNIBDshEWPt5Cqy4Z/yrnGNKAIiDbU0tAMfagWqnteP/+OubaeZanNHocdVvPZjse650lhNf7vm8qC0cR01fKNW8O3tiGiB7hKhejWN4= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 168240508051752.668194570892524; Mon, 24 Apr 2023 23:44:40 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNm-0003ho-Ex; Tue, 25 Apr 2023 02:42:34 -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 1prCNk-0003gH-LY for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:32 -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 1prCNi-0004Kq-4n for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:31 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-608-6nGWY7qyMwiLHxkcevJYlA-1; Tue, 25 Apr 2023 02:42:25 -0400 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 4295C886069; Tue, 25 Apr 2023 06:42:25 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id C90BD492B03; Tue, 25 Apr 2023 06:42:24 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id BF02E21F167A; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404949; 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=a7YqkyguldLJHFa6e+lj+gnk5EKBe9tfAPYkfiWyHWw=; b=U5+sRLfcWfocV6p8J7bAIVBLVw35M2ZhZy0qEbc4u7d9LPuZGMeopqmlssj1ar8m7AoQPu fIoek9g2/wyGn2v521agJvMlWfDQlWaHQ6Eq8yNgtKEOMne4UBHPwZExlPlajG/4WXZoMg bABe+9fjrvH+C/rRrysrkY27W1exK2g= X-MC-Unique: 6nGWY7qyMwiLHxkcevJYlA-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 04/16] qapi: Fix up references to long gone error classes Date: Tue, 25 Apr 2023 08:42:11 +0200 Message-Id: <20230425064223.820979-5-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.10 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405081001100001 Commit de253f14912e88f4 (qmp: switch to the new error format on the wire) removed most error classes. Several later commits mistakenly mentioned them in documentation. Replace them by the actual error class there. Fixes: 44e3e053af56 (qmp: add interface blockdev-snapshot-delete-internal-s= ync) Fixes: f323bc9e8b3b (qmp: add interface blockdev-snapshot-internal-sync) Fixes: ba1c048a8f9c (qapi: Introduce add-fd, remove-fd, query-fdsets) Fixes: ed61fc10e8c8 (QAPI: add command for live block commit, 'block-commit= ') Fixes: e4c8f004c55d (qapi: convert sendkey) Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- qapi/block-core.json | 4 ++-- qapi/misc.json | 6 +++--- qapi/ui.json | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index c05ad0c07e..75f7c62405 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -5784,7 +5784,7 @@ # - If any snapshot matching @name exists, or @name is empty, # GenericError # - If the format of the image used does not support it, -# BlockFormatFeatureNotSupported +# GenericError # # Since: 1.7 # @@ -5820,7 +5820,7 @@ # - 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, -# BlockFormatFeatureNotSupported +# GenericError # - If @id and @name are both not specified, GenericError # # Since: 1.7 diff --git a/qapi/misc.json b/qapi/misc.json index 6ddd16ea28..7e278ca1eb 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -349,8 +349,8 @@ # @opaque: A free-form string that can be used to describe the fd. # # Returns: - @AddfdInfo on success -# - If file descriptor was not received, FdNotSupplied -# - If @fdset-id is a negative value, InvalidParameterValue +# - If file descriptor was not received, GenericError +# - If @fdset-id is a negative value, GenericError # # Notes: The list of fd sets is shared by all monitor connections. # @@ -379,7 +379,7 @@ # @fd: The file descriptor that is to be removed. # # Returns: - Nothing on success -# - If @fdset-id or @fd is not found, FdNotFound +# - If @fdset-id or @fd is not found, GenericError # # Since: 1.2 # diff --git a/qapi/ui.json b/qapi/ui.json index 98322342f7..25f9d731df 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -985,7 +985,7 @@ # to 100 # # Returns: - Nothing on success -# - If key is unknown or redundant, InvalidParameter +# - If key is unknown or redundant, GenericError # # Since: 1.3 # --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405155; cv=none; d=zohomail.com; s=zohoarc; b=RkRSByXIQ79rgBEuaQqjj3xqMEDPeCJbTubGq0wfiB9MJjDrjcP5Hpye5Xk7pjA1BzMDuN2vutYiGiqgrlJ1Usq/QEV7NidR8sQUbUvVmX/9g/9vfyxT2IOJ8Ammnj+/CZYqRJyIYuQV3/MYHEUi7+WqMyslbi9muQFZjL3KRxg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405155; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=3nZAihnRm3QUvgN69kUOoUh63ZMl0DOPBL5UGoylvWQ=; b=mUl8l77lVc/hcc1ayfjtDc8x9HvY05Uj7xZl65pBJ0fHIYvfC45PGXkCiQTtpF2e2e5oSa1j6gwQopHTbFkQS6UyGPrdM846Go2cvZy/4/LgV02vdqBcbnvfup+5SnKLecLjLpBLUm/lChuXtQi6SXERpyFVdlP4m+3SWnICdcM= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405155192422.95443036498864; Mon, 24 Apr 2023 23:45:55 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNv-0003xR-FI; Tue, 25 Apr 2023 02:42:43 -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 1prCNp-0003qY-MZ for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:37 -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 1prCNj-0004Lu-Uw for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:37 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-28-R69Oy6YoPHSDS92HxrYK0Q-1; Tue, 25 Apr 2023 02:42:27 -0400 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 4D8F6886065; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2A51C492B03; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id C1D2421F167D; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404951; 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=3nZAihnRm3QUvgN69kUOoUh63ZMl0DOPBL5UGoylvWQ=; b=DPMlOCskWtG4Ttfg6T+lDyGPjBLmxSbwTJCL1v6Xtqz/9plA/eVxN7QaRBEJ4+bLw+PICX pnAJ4HEcodpa9LLjiak068mmHZI2uM/qLtfLgrdYrU2l7CyhhH3SH+EXWH60xCKK/agr7X /U4DGaJtRjcSZxA9yX4rdzjDd0r4B5Q= X-MC-Unique: R69Oy6YoPHSDS92HxrYK0Q-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 05/16] qapi/block-core: Clean up after removal of dirty bitmap @status Date: Tue, 25 Apr 2023 08:42:12 +0200 Message-Id: <20230425064223.820979-6-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.10 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405156325100003 Commit 81cbfd50886 (block: remove dirty bitmaps 'status' field) removed deprecated BlockDirtyInfo member @status. It neglected to remove references to its enumeration values from the documentation of its replacements. Do that now. Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau Reviewed-by: John Snow --- qapi/block-core.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 75f7c62405..eeb2ed3f16 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -582,11 +582,11 @@ # @granularity: granularity of the dirty bitmap in bytes (since 1.4) # # @recording: true if the bitmap is recording new writes from the guest. -# Replaces ``active`` and ``disabled`` statuses. (since 4.0) +# (since 4.0) # # @busy: true if the bitmap is in-use by some operation (NBD or jobs) # and cannot be modified via QMP or used by another operation. -# Replaces ``locked`` and ``frozen`` statuses. (since 4.0) +# (since 4.0) # # @persistent: true if the bitmap was stored on disk, is scheduled to be s= tored # on disk, or both. (since 4.0) --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405032; cv=none; d=zohomail.com; s=zohoarc; b=LJb9ZufnWg/3ku50w4rKN9to8hCWXoznMcqL1lUJ6gatGPFt81Ye9pJDpG/P1c7PNcaGs9XMmkKdVoBEWhxZaIMXoAJzEMxdrEVUwe5JkK2kMtQx3pTB8b7J52gsGMo9QRNgpM3fN6U2Zx4jfu2abCmQXDQFO+kMI0uFOZJoNZM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405032; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=nnbiJdUqt7Fui63ODoE8sxPsfdATTWND/Bq5Rf7J+zE=; b=VTCzpdrJMKpA4/vGM8Lfg1taFR7Cq7mZCCeZ9Tbq8gJmz4RjrHdz4l0CdrNf7GRdpXj1h21xFI9nGLtqZ+s4VR4Oe6C2/7jhJXGxVBdAP4AUSfXlQkVEGPGDR0Qwa49Sz0u8A5S25Rz4ML0S8GhK6NeeQUdZP1wO01EK1VVicc8= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405032281467.8942345191034; Mon, 24 Apr 2023 23:43:52 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCOg-0004Xk-Dp; Tue, 25 Apr 2023 02:43:30 -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 1prCON-0004BX-2C for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:43:15 -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 1prCOJ-0004RC-Dt for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:43:10 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-616-sMtlDMstNfa84TZLFz7JvQ-1; Tue, 25 Apr 2023 02:42:55 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 5072387A9E3; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2BED740C2064; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id C4D9621F9814; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404980; 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=nnbiJdUqt7Fui63ODoE8sxPsfdATTWND/Bq5Rf7J+zE=; b=Ptl13TsI9L9UneEd0xkty+dLiww5SG1N+mtHSnzjhDIpQ3A8fxfC/c6RdXcyLuQwwTJ0ti U8WO8B/x+gLXwPyeZ6UQSWlxwhk7y/Avz1mU3qtH1+Hi2sWGbM+6rGMo/6jj/6TVcXRQXZ CtbAioubd2PYNfcWu2bwmAsCbNqeadc= X-MC-Unique: sMtlDMstNfa84TZLFz7JvQ-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 06/16] qapi: @foo should be used to reference, not ``foo`` Date: Tue, 25 Apr 2023 08:42:13 +0200 Message-Id: <20230425064223.820979-7-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.1 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405032673100001 Documentation suggests @foo is merely shorthand for ``foo``. It's not, it carries additional meaning: it's a reference to a QAPI schema name. Reword the documentation to spell that out. Fix up the few ``foo`` that should be @foo. Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- docs/devel/qapi-code-gen.rst | 8 +++++--- docs/interop/firmware.json | 6 +++--- qapi/qom.json | 2 +- qapi/ui.json | 2 +- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 23e7f2fb1c..23f9059db2 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -925,9 +925,11 @@ first character of the first line. =20 The usual ****strong****, *\*emphasized\** and ````literal```` markup should be used. If you need a single literal ``*``, you will need to -backslash-escape it. As an extension beyond the usual rST syntax, you -can also use ``@foo`` to reference a name in the schema; this is rendered -the same way as ````foo````. +backslash-escape it. + +Use ``@foo`` to reference a name in the schema. This is an rST +extension. It is rendered the same way as ````foo````, but carries +additional meaning. =20 Example:: =20 diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json index 56814f02b3..cc8f869186 100644 --- a/docs/interop/firmware.json +++ b/docs/interop/firmware.json @@ -258,7 +258,7 @@ # # @mode: Describes how the firmware build handles code versus variable # storage. If not present, it must be treated as if it was -# configured with value ``split``. Since: 7.0.0 +# configured with value @split. Since: 7.0.0 # # @executable: Identifies the firmware executable. The @mode # indicates whether there will be an associated @@ -267,13 +267,13 @@ # -drive if=3Dnone,id=3Dpflash0,readonly=3Don,file=3D@exe= cutable.@filename,format=3D@executable.@format # -machine pflash0=3Dpflash0 # or equivalent -blockdev instead of -drive. When -# @mode is ``combined`` the executable must be +# @mode is @combined the executable must be # cloned before use and configured with readonly=3Doff. # With QEMU versions older than 4.0, you have to use # -drive if=3Dpflash,unit=3D0,readonly=3Don,file=3D@execu= table.@filename,format=3D@executable.@format # # @nvram-template: Identifies the NVRAM template compatible with -# @executable, when @mode is set to ``split``, +# @executable, when @mode is set to @split, # otherwise it should not be present. # Management software instantiates an # individual copy -- a specific NVRAM file -- from diff --git a/qapi/qom.json b/qapi/qom.json index a877b879b9..4fe7a93a75 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -637,7 +637,7 @@ # # @discard-data: if true, the file contents can be destroyed when QEMU exi= ts, # to avoid unnecessarily flushing data to the backing file.= Note -# that ``discard-data`` is only an optimization, and QEMU m= ight +# that @discard-data is only an optimization, and QEMU might # not discard file contents if it aborts unexpectedly or is # terminated using SIGKILL. (default: false) # diff --git a/qapi/ui.json b/qapi/ui.json index 25f9d731df..c383c11097 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -1247,7 +1247,7 @@ # available node on the host. # # @p2p: Whether to use peer-to-peer connections (accepted through -# ``add_client``). +# @add_client). # # @audiodev: Use the specified DBus audiodev to export audio. # --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405113; cv=none; d=zohomail.com; s=zohoarc; b=NMWcfUBBInYNV8TJ2JLzCtVvANsIl3Bwyu4Xpi8LM90XjxFNQE/r1zY4tbnuM0sZC5OZ2NUwpJRcHh2VeyfE6nLQ7UTyGA/M2+d5yxeNkd63dntJ++4LAsJaovvR5iSHsp2Hitnv+azNdM23CTLnT7ODGvCT73H7448nc6Oj4P8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405113; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=jA1uuzuaT8CNxMlYFtyJDTbctEafmdIKRlIT9CC8Q8E=; b=NcF1AreOrd2xQmxjI13R6uQNjMUqUcmGGP/xmyt9VInBXq3M1kaP55ycaHcCMH2b3ujNmUerRdVQmSzdcrnKV6d5FUUukVEDJLjs9lolrDg9CUBHDNMeMU4IrQxF9lTY9/N3okyzbEbFKmmDzNClf0Acqkp8ZlcTk9vv897M0jI= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405113129678.9906316853712; Mon, 24 Apr 2023 23:45:13 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNq-0003sF-N0; Tue, 25 Apr 2023 02:42:38 -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 1prCNn-0003mf-I2 for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42: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 1prCNj-0004LR-9v for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:35 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-100-Qt9yQHwsNB6othXKloIMRw-1; Tue, 25 Apr 2023 02:42:27 -0400 Received: from smtp.corp.redhat.com (int-mx09.intmail.prod.int.rdu2.redhat.com [10.11.54.9]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 6A448858F0E; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2A89A492C18; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id C7E8F21F9816; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404950; 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=jA1uuzuaT8CNxMlYFtyJDTbctEafmdIKRlIT9CC8Q8E=; b=SdIDmagEYKOVXXPrNX9Ok3pGyBhrXP318yoxe9N8VFbNijaU2zUAGEvBRJcRwRBE8xW7BG IotpvVnOqyJPNjIcVir7LIn+Ez0ESuRUwJwEo5EazBsa8cHHKUAiMgvPEkKJrUer7LYLEL ffMsdF/iK6Xr+gacCQ88TxC/InCY1zQ= X-MC-Unique: Qt9yQHwsNB6othXKloIMRw-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 07/16] qapi: Tidy up examples Date: Tue, 25 Apr 2023 08:42:14 +0200 Message-Id: <20230425064223.820979-8-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.9 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405115317100007 A few examples neglect to prefix QMP input with '->'. Fix that. Two examples have extra space after '<-'. Delete it. A few examples neglect to show output. Provide some. The example output for query-vcpu-dirty-limit could use further improvement. Add a TODO comment. Use "Examples:" instead of "Example:" where multiple examples are given. One example section numbers its two examples. Not done elsewhere; drop. Another example section separates them with "or". Likewise. Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau Reviewed-by: Juan Quintela --- qapi/block-core.json | 14 ++++++-------- qapi/block.json | 2 +- qapi/char.json | 4 ++-- qapi/machine.json | 7 ++++--- qapi/migration.json | 33 ++++++++++++++++++++++----------- qapi/misc.json | 7 +++---- qapi/net.json | 4 +--- qapi/qdev.json | 2 +- qapi/qom.json | 2 +- qapi/replay.json | 3 +++ qapi/run-state.json | 5 ++--- qapi/ui.json | 2 +- 12 files changed, 47 insertions(+), 38 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index eeb2ed3f16..a5a5007b28 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -4574,9 +4574,8 @@ # # Since: 2.9 # -# Example: +# Examples: # -# 1. # -> { "execute": "blockdev-add", # "arguments": { # "driver": "qcow2", @@ -4589,7 +4588,6 @@ # } # <- { "return": {} } # -# 2. # -> { "execute": "blockdev-add", # "arguments": { # "driver": "qcow2", @@ -5596,7 +5594,7 @@ # # Since: 2.7 # -# Example: +# Examples: # # 1. Add a new node to a quorum # -> { "execute": "blockdev-add", @@ -5646,7 +5644,7 @@ # # Since: 2.12 # -# Example: +# Examples: # # 1. Move a node into an IOThread # -> { "execute": "x-blockdev-set-iothread", @@ -5731,18 +5729,18 @@ # # Since: 2.0 # -# Example: +# Examples: # # 1. Read operation # -# { "event": "QUORUM_REPORT_BAD", +# <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 345435, "sectors-coun= t": 5, # "type": "read" }, # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } # # 2. Flush operation # -# { "event": "QUORUM_REPORT_BAD", +# <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2= 097120, # "type": "flush", "error": "Broken pipe" }, # "timestamp": { "seconds": 1456406829, "microseconds": 291763 } } diff --git a/qapi/block.json b/qapi/block.json index 5fe068f903..94339a1761 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -457,7 +457,7 @@ # # Since: 1.1 # -# Example: +# Examples: # # -> { "execute": "block_set_io_throttle", # "arguments": { "id": "virtio-blk-pci0/virtio-backend", diff --git a/qapi/char.json b/qapi/char.json index 923dc5056d..c9431dd0a7 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -637,7 +637,7 @@ # # Since: 1.4 # -# Example: +# Examples: # # -> { "execute" : "chardev-add", # "arguments" : { "id" : "foo", @@ -673,7 +673,7 @@ # # Since: 2.10 # -# Example: +# Examples: # # -> { "execute" : "chardev-change", # "arguments" : { "id" : "baz", diff --git a/qapi/machine.json b/qapi/machine.json index 8c3c58c763..20541cb319 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -954,7 +954,7 @@ # # Since: 2.7 # -# Example: +# Examples: # # For pseries machine type started with -smp 2,cores=3D2,maxcpus=3D4 -cpu = POWER8: # @@ -1677,8 +1677,9 @@ # Since: 7.2 # # Example: -# {"execute": "dumpdtb"} -# "arguments": { "filename": "fdt.dtb" } } +# -> { "execute": "dumpdtb" } +# "arguments": { "filename": "fdt.dtb" } } +# <- { "return": {} } # ## { 'command': 'dumpdtb', diff --git a/qapi/migration.json b/qapi/migration.json index 87c174dca2..477ee4d35b 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -273,7 +273,7 @@ # # Since: 0.14 # -# Example: +# Examples: # # 1. Before the first migration # @@ -521,6 +521,7 @@ # # -> { "execute": "migrate-set-capabilities" , "arguments": # { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } +# <- { "return": {} } # ## { 'command': 'migrate-set-capabilities', @@ -989,6 +990,7 @@ # # -> { "execute": "migrate-set-parameters" , # "arguments": { "compress-level": 1 } } +# <- { "return": {} } # ## { 'command': 'migrate-set-parameters', 'boxed': true, @@ -1279,8 +1281,8 @@ # # Example: # -# { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, -# "event": "MIGRATION_PASS", "data": {"pass": 2} } +# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, +# "event": "MIGRATION_PASS", "data": {"pass": 2} } # ## { 'event': 'MIGRATION_PASS', @@ -1861,8 +1863,9 @@ # # Example: # -# {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, -# 'sample-pages': 512} } +# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, +# 'sample-pages': 512} } +# <- { "return": {} } # ## { 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64', @@ -1914,9 +1917,11 @@ # Since: 7.1 # # Example: -# {"execute": "set-vcpu-dirty-limit"} -# "arguments": { "dirty-rate": 200, -# "cpu-index": 1 } } +# +# -> {"execute": "set-vcpu-dirty-limit"} +# "arguments": { "dirty-rate": 200, +# "cpu-index": 1 } } +# <- { "return": {} } # ## { 'command': 'set-vcpu-dirty-limit', @@ -1937,8 +1942,10 @@ # Since: 7.1 # # Example: -# {"execute": "cancel-vcpu-dirty-limit"} -# "arguments": { "cpu-index": 1 } } +# +# -> {"execute": "cancel-vcpu-dirty-limit"}, +# "arguments": { "cpu-index": 1 } } +# <- { "return": {} } # ## { 'command': 'cancel-vcpu-dirty-limit', @@ -1952,7 +1959,11 @@ # Since: 7.1 # # Example: -# {"execute": "query-vcpu-dirty-limit"} +# +# -> {"execute": "query-vcpu-dirty-limit"} +# <- {"return": [ +# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0}, +# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]} # ## { 'command': 'query-vcpu-dirty-limit', diff --git a/qapi/misc.json b/qapi/misc.json index 7e278ca1eb..4afaee7fe7 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -580,10 +580,9 @@ # # Example: # -# <- { "event": "RTC_CHANGE", -# "data": { "offset": 78 }, -# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } -# +# <- { "event": "RTC_CHANGE", +# "data": { "offset": 78 }, +# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } ## { 'event': 'RTC_CHANGE', 'data': { 'offset': 'int', 'qom-path': 'str' } } diff --git a/qapi/net.json b/qapi/net.json index d6eb30008b..1f1e148f01 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -914,7 +914,7 @@ # # Since: 7.2 # -# Example: +# Examples: # # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", @@ -922,8 +922,6 @@ # "host": "::1", "type": "inet" } }, # "timestamp": { "seconds": 1666269863, "microseconds": 311222 } } # -# or -# # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", # "addr": { "path": "/tmp/qemu0", "type": "unix" } }, diff --git a/qapi/qdev.json b/qapi/qdev.json index 2708fb4e99..f309facf8d 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -100,7 +100,7 @@ # # Since: 0.14 # -# Example: +# Examples: # # -> { "execute": "device_del", # "arguments": { "id": "net1" } } diff --git a/qapi/qom.json b/qapi/qom.json index 4fe7a93a75..2a3891e3cb 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -103,7 +103,7 @@ # # Since: 1.2 # -# Example: +# Examples: # # 1. Use absolute path # diff --git a/qapi/replay.json b/qapi/replay.json index 729470300d..fcbf10e237 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -81,6 +81,7 @@ # Example: # # -> { "execute": "replay-break", "arguments": { "icount": 220414 } } +# <- { "return": {} } # ## { 'command': 'replay-break', 'data': { 'icount': 'int' } } @@ -96,6 +97,7 @@ # Example: # # -> { "execute": "replay-delete-break" } +# <- { "return": {} } # ## { 'command': 'replay-delete-break' } @@ -117,5 +119,6 @@ # Example: # # -> { "execute": "replay-seek", "arguments": { "icount": 220414 } } +# <- { "return": {} } ## { 'command': 'replay-seek', 'data': { 'icount': 'int' } } diff --git a/qapi/run-state.json b/qapi/run-state.json index 419c188dd1..bfc15ecad5 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -258,9 +258,8 @@ # # Example: # -# <- { "event": "SUSPEND_DISK", -# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } -# +# <- { "event": "SUSPEND_DISK", +# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } ## { 'event': 'SUSPEND_DISK' } =20 diff --git a/qapi/ui.json b/qapi/ui.json index c383c11097..e9599dea50 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -1153,7 +1153,7 @@ # so it is possible to map which console belongs to which device and # display. # -# Example: +# Examples: # # 1. Press left mouse button. # --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405105; cv=none; d=zohomail.com; s=zohoarc; b=hrnZfU992cV8/cuo4EFzodfEnnMpshHoYu/n4VYu4n1P8zlk0HsDJy4iB7svYf/YCVVC8pFBLkQhl1OfgTMPPQup4dVV/7rLqPgEu4YzygtDOvIdmbzC1wU3ixGwsIFvFHZM68ckJTemqhRJhtMnmwuBmkGF1SKZ2tyY71XdE4Y= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405105; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=P7nlyVx9PdxU9RBlHQh1GQfJayml4LDhrANl9WJhhhY=; b=PMoqfBtb57znlr/NULORcpI9yW2fS02VwGATDIQa7/CCeOWtW4Qk3t8SoCYFu8ipgxvjTj2IoEbHkn2P0o2WiAGd+DBMjx2rZsnaD92fSVMquZ6xI60AE0uSVJRUTNsqUv32wpHdvME/hViXw3upRZdeJDnl4l/hVJwdQvlEFjA= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405105189219.54479439329657; Mon, 24 Apr 2023 23:45:05 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNp-0003pQ-AA; Tue, 25 Apr 2023 02:42:37 -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 1prCNn-0003kr-48 for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:35 -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 1prCNj-0004LK-CE for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:34 -0400 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-595-2fKRQmzkMIiKaxxMtJawxQ-1; Tue, 25 Apr 2023 02:42:27 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 5225629AB3FE; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2C440C15BAD; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id CAD0C21F9817; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404950; 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=P7nlyVx9PdxU9RBlHQh1GQfJayml4LDhrANl9WJhhhY=; b=Km11imT7+0+FcOoJcKRRHExAIHRmDmdnOnHyJoRKK6Apne+dVsOnT1DBXcK7pecQhbn0FM hU5Y5gOQpLbATHy5COAOLKaqmBDJA7w+/GJui07+X22K3H5OQqRCGcDks+pLW8RHarig3j YYgYigAEbn/tBVTuGbMecnvn00lddLA= X-MC-Unique: 2fKRQmzkMIiKaxxMtJawxQ-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 08/16] qapi: Delete largely misleading "Stability Considerations" Date: Tue, 25 Apr 2023 08:42:15 +0200 Message-Id: <20230425064223.820979-9-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.8 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405107028100003 Documentation section "Stability Considerations" dates back to the early days of QMP (commit 82a56f0d83d (Monitor: Introduce the qmp-commands.hx file)). It became largely misleading years ago. Delete it. Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- qapi/qapi-schema.json | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 7c09af5cc8..e57d8ff801 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -28,28 +28,6 @@ # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. -# -# =3D Stability Considerations -# -# The current QMP command set (described in this file) may be useful for a -# number of use cases, however it's limited and several commands have bad -# defined semantics, specially with regard to command completion. -# -# These problems are going to be solved incrementally in the next QEMU rel= eases -# and we're going to establish a deprecation policy for badly defined comm= ands. -# -# If you're planning to adopt QMP, please observe the following: -# -# 1. The deprecation policy will take effect and be documented soon, p= lease -# check the documentation of each used command as soon as a new rel= ease of -# QEMU is available -# -# 2. DO NOT rely on anything which is not explicit documented -# -# 3. Errors, in special, are not documented. Applications should NOT c= heck -# for specific errors classes or data (it's strongly recommended to= only -# check for the "error" key) -# ## =20 { 'include': 'pragma.json' } --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405113; cv=none; d=zohomail.com; s=zohoarc; b=LGexEq866fCyPJgUodeEh/rAljk9J05X3sNXiNu8aDSkPZT6D0q0lhUxSsMMZ/BjaclSnz3gv9CwSDRYVgVSpC9agFS6ofXi686yWrQoLDW9eFy8Ilaw+vJWeRmlUeeSNLzoC+kk9YjIZSNMam9tVsB1V6TjqUX609INBcWCSGI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405113; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=W6le+9+a75N0/4Rn66845924IWAndAGfIivbp0OvYTI=; b=Iaa2CfDamFqOs41zy4uBXEvpFu/31IhytUIrGHegCnDixdzwKFtIphrZCdI0jh5rBJbJyzEukeMz3Zx3bMm7w91K7qXxdsCVNnnrlNI9VRvIqeBz5ppOd7MNtUQzCOCioid3lNZgzD+UmOGxZ3RL+aAAUf+by9mcB72CeOF7AK8= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405113078680.3721635307407; Mon, 24 Apr 2023 23:45:13 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNs-0003tD-2Y; Tue, 25 Apr 2023 02:42:40 -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 1prCNo-0003ou-NV for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:36 -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 1prCNj-0004LI-CH for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:36 -0400 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-619-C1mDXNk4Os-Hz3Abtlb_3Q-1; Tue, 25 Apr 2023 02:42:27 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 521741C06ED2; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2E3B040C6E68; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id CDEED21F9818; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404950; 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=W6le+9+a75N0/4Rn66845924IWAndAGfIivbp0OvYTI=; b=GbsIGdVpxCNmx/Hnel+xDKZQX1rlTjZz1INwVioIksi7o6RUnpzTUUjAOR6T8O6g6VHNIl TRPAI+AyxzPc8kqsEjCMTW8msApobXI6isknxWvUeBGfIGEr+xQL4YV0dZzYmixfzO0ODU g2Flxvbq+jUX+DrzQGCUUY4qtL9wIVU= X-MC-Unique: C1mDXNk4Os-Hz3Abtlb_3Q-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 09/16] qapi: Fix bullet list markup in documentation Date: Tue, 25 Apr 2023 08:42:16 +0200 Message-Id: <20230425064223.820979-10-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.2 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405114798100003 Peter Maydell's commit 100cc4fe0f08 explains: rST insists on a blank line before and after a bulleted list [...] Add some extra blank lines in the doc comments so they're acceptable rST input. It missed one in qapi/trace.json. Paolo Bonzini later added another instance in qapi/stats.json, providing further, if unintended, evidence for his quip that rST is the Perl of ASCII-based markups. Both are parsed as ordinary paragraph, resulting in garbled output. Add the blank lines we need to get the bullet lists recognized as such. Kevin Wolf and Lukas Straub added two more, but indented. Sphinx recognizes them as (indented) bullet lists. The indentation looks slightly off. Insert a blank line and delete the extra indentation. Fixes: 100cc4fe0f0827f8da1a5c05f9c65e2aaa40e03d (qapi: Add blank lines befo= re bulleted lists) Fixes: 467ef823d83e (qmp: add filtering of statistics by target vCPU) Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- qapi/block-export.json | 7 ++++--- qapi/stats.json | 1 + qapi/trace.json | 1 + qapi/yank.json | 21 +++++++++++---------- 4 files changed, 17 insertions(+), 13 deletions(-) diff --git a/qapi/block-export.json b/qapi/block-export.json index 4627bbc4e6..3be3de357f 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -275,9 +275,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 +# +# - the server is not running +# - export is not found +# - mode is 'safe' and there are existing connections # # Since: 2.12 ## diff --git a/qapi/stats.json b/qapi/stats.json index 1f5d3c59ab..f17495ee65 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -107,6 +107,7 @@ # The arguments to the query-stats command; specifies a target for which to # request statistics and optionally the required subset of information for # that target: +# # - which vCPUs to request statistics for # - which providers to request statistics from # - which named values to return within each provider diff --git a/qapi/trace.json b/qapi/trace.json index 6c6982a587..f425d10764 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -87,6 +87,7 @@ # @vcpu: The vCPU to act upon (all by default; since 2.7). # # An event's state is modified if: +# # - its name matches the @name pattern, and # - if @vcpu is given, the event has the "vcpu" property. # diff --git a/qapi/yank.json b/qapi/yank.json index 167a775594..1639744ada 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -50,16 +50,17 @@ # hanging QEMU. # # Currently implemented yank instances: -# - nbd block device: -# Yanking it will shut down the connection to the nbd server without -# attempting to reconnect. -# - socket chardev: -# Yanking it will shut down the connected socket. -# - migration: -# Yanking it will shut down all migration connections. Unlike -# @migrate_cancel, it will not notify the migration process, so migrati= on -# will go into @failed state, instead of @cancelled state. @yank should= be -# used to recover from hangs. +# +# - nbd block device: +# Yanking it will shut down the connection to the nbd server without +# attempting to reconnect. +# - socket chardev: +# Yanking it will shut down the connected socket. +# - migration: +# Yanking it will shut down all migration connections. Unlike +# @migrate_cancel, it will not notify the migration process, so migration +# will go into @failed state, instead of @cancelled state. @yank should = be +# used to recover from hangs. # # Since: 6.0 ## --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405116; cv=none; d=zohomail.com; s=zohoarc; b=Bc6A88n3b3KGDRFMC/XHOosWPX/UXUD9JmpbEHaIoVjKLxgZ6gkOA4W1WS4VgloLhGRk3VFbpMIix23ukknL98AmM+6bFxcB6gtC2TCgqTTK9nMr+noQro5uEsBwEr+NJ+QxriCj66Io8av7A1kOSZei3nQyibpNO0gsfG3SM/s= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405116; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=/NH69U59Jgca1Vf5HweOGs2oX5HqBAz/Qsu4ziWQdyE=; b=na7HnFfzrRbDwrzO4xUEObmN4IhkMRMjGKrHsWHpMpjnxVzKkNy9juXHmwnOC7wAgMk53gfNj37jORUICr0fxH0+unDW1aBOhcQSCIkDAop1NE0njDTIFBQLlruSeW8c29/G9TF66+BB1gM/TiQBVQtfVdesJTNB1hRvwa0+PnU= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405116887879.1029185234628; Mon, 24 Apr 2023 23:45:16 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNp-0003qX-Nv; Tue, 25 Apr 2023 02:42:37 -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 1prCNn-0003kt-4w for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42: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 1prCNi-0004LF-Ta for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:34 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-100-doNaFpXwNEGRKN8PC2SaSg-1; Tue, 25 Apr 2023 02:42:27 -0400 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 73C49886063; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 2D882492B0F; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id D0EB621F981C; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404950; 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=/NH69U59Jgca1Vf5HweOGs2oX5HqBAz/Qsu4ziWQdyE=; b=PVeu3KWF2cCEaP9P0sg83COR4hNCZxyixxnvtZJNW8fUUKrrGE+K60SnKXipqa6bXIJFz1 2Z5cXBxHtNHXJhKuMG2OXLh6SHXoI6h6T3y8AsHEJmUzeil6WIHNgS8ksR08VObji9WYgJ iuSYeou2JjyyoAKM0LXnlQG6rsZFozY= X-MC-Unique: doNaFpXwNEGRKN8PC2SaSg-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com, Peter Maydell Subject: [PATCH v2 10/16] qapi: Fix unintended definition lists in documentation Date: Tue, 25 Apr 2023 08:42:17 +0200 Message-Id: <20230425064223.820979-11-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.10 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405118840100019 rST parses something like first line second line as a definition list item, where "first line" is the term being defined by "second line". This bites us in a couple of places. Here's one: # @bps_max: total throughput limit during bursts, # in bytes (Since 1.7) scripts/qapi/parser.py parses this into an "argument section" with name "bps_max" and text total throughput limit during bursts, in bytes (Since 1.7) docs/sphinx/qapidoc.py duly passes the text to the rST parser, which parses it as another definition list. Comes out as nested definitions: term "bps_max: int (optional)" defined as term "total throughput limit during bursts," defined as "in bytes (Since 1.7)". rST truly is the Perl of ASCII-based markups. Fix by deleting the extra indentation. Fixes: 26ec4e53f2bf (qapi: Fix indent level on doc comments in json files) Fixes: c0ac533b6f97 (qapi: Stop using whitespace for alignment in comments) Fixes: 81ad2964e938 (net/vmnet: add vmnet backends to qapi/net) Reported-by: Peter Maydell Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau Reviewed-by: Peter Maydell --- qapi/block-core.json | 52 ++++++++++++++++++++++---------------------- qapi/control.json | 2 +- qapi/machine.json | 4 ++-- qapi/net.json | 2 +- 4 files changed, 30 insertions(+), 30 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index a5a5007b28..2382772e17 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -488,41 +488,41 @@ # # @image: the info of image used (since: 1.6) # -# @bps_max: total throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_max: total throughput limit during bursts, in bytes +# (Since 1.7) # -# @bps_rd_max: read throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_rd_max: read throughput limit during bursts, in bytes +# (Since 1.7) # -# @bps_wr_max: write throughput limit during bursts, -# in bytes (Since 1.7) +# @bps_wr_max: write throughput limit during bursts, in bytes +# (Since 1.7) # -# @iops_max: total I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_max: total I/O operations per second during bursts, in bytes +# (Since 1.7) # -# @iops_rd_max: read I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_rd_max: read I/O operations per second during bursts, in bytes +# (Since 1.7) # -# @iops_wr_max: write I/O operations per second during bursts, -# in bytes (Since 1.7) +# @iops_wr_max: write I/O operations per second during bursts, in +# bytes (Since 1.7) # -# @bps_max_length: maximum length of the @bps_max burst -# period, in seconds. (Since 2.6) +# @bps_max_length: maximum length of the @bps_max burst period, in +# seconds. (Since 2.6) # -# @bps_rd_max_length: maximum length of the @bps_rd_max -# burst period, in seconds. (Since 2.6) +# @bps_rd_max_length: maximum length of the @bps_rd_max burst period, +# in seconds. (Since 2.6) # -# @bps_wr_max_length: maximum length of the @bps_wr_max -# burst period, in seconds. (Since 2.6) +# @bps_wr_max_length: maximum length of the @bps_wr_max burst period, +# in seconds. (Since 2.6) # -# @iops_max_length: maximum length of the @iops burst -# period, in seconds. (Since 2.6) +# @iops_max_length: maximum length of the @iops burst period, in +# seconds. (Since 2.6) # -# @iops_rd_max_length: maximum length of the @iops_rd_max -# burst period, in seconds. (Since 2.6) +# @iops_rd_max_length: maximum length of the @iops_rd_max burst +# period, in seconds. (Since 2.6) # -# @iops_wr_max_length: maximum length of the @iops_wr_max -# burst period, in seconds. (Since 2.6) +# @iops_wr_max_length: maximum length of the @iops_wr_max burst +# period, in seconds. (Since 2.6) # # @iops_size: an I/O size in bytes (Since 1.7) # @@ -948,7 +948,7 @@ # by the device (Since 4.2) # # @invalid_rd_operations: The number of invalid read operations -# performed by the device (Since 2.5) +# performed by the device (Since 2.5) # # @invalid_wr_operations: The number of invalid write operations # performed by the device (Since 2.5) @@ -3735,7 +3735,7 @@ # Driver specific block device options for Quorum # # @blkverify: true if the driver must print content mismatch -# set to false by default +# set to false by default # # @children: the children block devices to use # diff --git a/qapi/control.json b/qapi/control.json index afca2043af..f83499280a 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -195,7 +195,7 @@ # @id: Name of the monitor # # @mode: Selects the monitor mode (default: readline in the system -# emulator, control in qemu-storage-daemon) +# emulator, control in qemu-storage-daemon) # # @pretty: Enables pretty printing (QMP only) # diff --git a/qapi/machine.json b/qapi/machine.json index 20541cb319..1a90376f4e 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -457,7 +457,7 @@ # @nodeid: NUMA node ID (increase by 1 from 0 if omitted) # # @cpus: VCPUs belonging to this node (assign VCPUS round-robin -# if omitted) +# if omitted) # # @mem: memory size of this node; mutually exclusive with @memdev. # Equally divide total memory among nodes if both @mem and @memdev a= re @@ -690,7 +690,7 @@ # 5.2.27.5: Table 5-147 of ACPI 6.3 spec. # # @none: None (no memory side cache in this proximity domain, -# or cache associativity unknown) +# or cache associativity unknown) # # @direct: Direct Mapped # diff --git a/qapi/net.json b/qapi/net.json index 1f1e148f01..ec66b39b70 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -533,7 +533,7 @@ # Must be specified along with @start-address and @subnet-ma= sk. # # @subnet-mask: The IPv4 subnet mask to use on the interface. Must -# be specified along with @start-address and @subnet-mask. +# be specified along with @start-address and @subnet-mask. # # @isolated: Enable isolation for this interface. Interface isolation # ensures that vmnet interface is not able to communicate --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405028; cv=none; d=zohomail.com; s=zohoarc; b=jbgHDsLDeCBjdcBUzuj3QmYPlgZkOslB5XIh7ROZb97zkuEzAGgDgDUW7IofkXUdbjAHC1I0GoNJ1e66ztLq105W1pSJG3BcD9Gm4ymS+shjQCh8Rt+M9VuUKogOL83SP0bs4Zf3HTuAc+Voz3UhgXYqzvIipB3+CIidUq8Mfws= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405028; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=1vqz6aQQZQpZhCnnrpi0dckCi7obvzL1PeLXth4PS5w=; b=L+ISIG8sEwlek0W3sd5spItLSaLTMGQqPFC9+nyHhuSc0ZyrJy2qxucROwI8r+luUmWsDdPRKgJEQIDEHx7UP4v90efP7jmrNu+tj/q+1N+9hw098R7Z579A7dm9vNaDBymRzl0g5MaCnc7qCDjO1EK5TodiI/7FhjziWW6Mnes= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 168240502861540.3704642293427; Mon, 24 Apr 2023 23:43:48 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNw-0003ys-IJ; Tue, 25 Apr 2023 02:42:44 -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 1prCNr-0003sf-E8 for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:39 -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 1prCNk-0004MM-Ez for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:39 -0400 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-28-iRzAE_ymOXiZJ-aWDCW3wQ-1; Tue, 25 Apr 2023 02:42:27 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 590D71C06EDB; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 337C349AF0; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id D3DB121F9821; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404951; 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=1vqz6aQQZQpZhCnnrpi0dckCi7obvzL1PeLXth4PS5w=; b=VCfPt+bU3DsY+wPqCcjY5fpxB7KRyu3Vf7BBbJTlm3hMRZ2pyNezwLhWgiUpKjrBrmQaFw LYnGvJJf27zEM8lwMDvMKRMMLzC2dKz6eIPeQrJtTT1djmzgtGCZ44nP6+Xo17A+qutuNa g2AuMZxv4rva/CQwU9/M6ZsPzDoxsJQ= X-MC-Unique: iRzAE_ymOXiZJ-aWDCW3wQ-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 11/16] qga/qapi-schema: Fix member documentation markup Date: Tue, 25 Apr 2023 08:42:18 +0200 Message-Id: <20230425064223.820979-12-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.5 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405029880100001 GuestDiskStatsInfo's member documentation is parsed as ordinary text due to missing colons. The generated documentation shows these members as "Not documented". The fix is obvious: add the missing colons. Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- 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 bb9bac0655..6a20eeb297 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -1553,11 +1553,11 @@ ## # @GuestDiskStatsInfo: # -# @name disk name +# @name: disk name # -# @major major device number of disk +# @major: major device number of disk # -# @minor minor device number of disk +# @minor: minor device number of disk ## { 'struct': 'GuestDiskStatsInfo', 'data': {'name': 'str', --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405059; cv=none; d=zohomail.com; s=zohoarc; b=OcBXbHtgSP5xavikKqcavXA8kRZK5+QisjYSxc8UesVZMM4dvA94RQfYwcYI/wet/+U6x8MuvoOKG7GKzcGh0i6LacQx2CjfXTUsPCHEgxw58e6m1zu90RR1Fpm9myOqB/uKhr5yWxuNBYCSqBwI+rCA//RZyUie0WTAakLSOwU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405059; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=DxfNcJrRJsee4ANBv7r5t6cxjIvXEmjQswThWG35zl0=; b=I0IX5iiAYn98H9aA86c/NbpFjbraqioK5Karv1VLDz8lfr4bw4sQfHfXSzd4ljeL//eyjK79zVgKsAi8J8jpEyUkY66ETVjJxw7fJuxbsHdqyo1ynPcC8La7LXRxoz16807mLn/IE8d5a350GLMQf1NGm/D8WMq5jZ2LBNZ7mdI= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405059673344.0020108497913; Mon, 24 Apr 2023 23:44:19 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCOb-0004Mg-10; Tue, 25 Apr 2023 02:43:28 -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 1prCOJ-0004B5-NP for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:43:08 -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 1prCOC-0004R4-6v for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:43:01 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-616-GQ_ZiePNPl2Vhthwl44cvw-1; Tue, 25 Apr 2023 02:42:54 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 5B3C0802C1A; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 376F914171B8; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id D75DC21F9824; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404979; 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=DxfNcJrRJsee4ANBv7r5t6cxjIvXEmjQswThWG35zl0=; b=asMvF1Qs1zN9xJbmt00okCPsSWxgWHs5Uz+wQv2L1Kg7s2bJpCLf6gXWjNYCAl1C4S2XON o1PF+6VZjfzSHLuJqncLayo4cnZgUHS3CtNLBBphfYNHqtcmwYiWYREM6To8GDpH2LwFD3 5O+WxLtGeZ2bHgEYZhosrHcTpAJEMOE= X-MC-Unique: GQ_ZiePNPl2Vhthwl44cvw-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 12/16] qapi: Fix argument documentation markup Date: Tue, 25 Apr 2023 08:42:19 +0200 Message-Id: <20230425064223.820979-13-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.7 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405061897100007 Member / argument documentation of BlockdevAmendOptionsQcow2, job-resume, and RDMA_GID_STATUS_CHANGED is parsed as ordinary text due to missing colon or space before the colon. The generated documentation shows these members / arguments as "Not documented". The fix is obvious: add missing colons, delete extra spaces. Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- qapi/block-core.json | 2 +- qapi/job.json | 2 +- qapi/rdma.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 2382772e17..9dd5ed9a47 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -5155,7 +5155,7 @@ # Driver specific image amend options for qcow2. # For now, only encryption options can be amended # -# @encrypt Encryption options to be amended +# @encrypt: Encryption options to be amended # # Since: 5.1 ## diff --git a/qapi/job.json b/qapi/job.json index d5f84e9615..bc4104757a 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -148,7 +148,7 @@ # This command returns immediately after resuming a paused job. Resuming an # already running job is an error. # -# @id : The job identifier. +# @id: The job identifier. # # Since: 3.0 ## diff --git a/qapi/rdma.json b/qapi/rdma.json index a1d2175a8b..5b6b66afa4 100644 --- a/qapi/rdma.json +++ b/qapi/rdma.json @@ -17,7 +17,7 @@ # # @subnet-prefix: Subnet Prefix # -# @interface-id : Interface ID +# @interface-id: Interface ID # # Since: 4.0 # --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405117; cv=none; d=zohomail.com; s=zohoarc; b=h7508jPh+w3TumebZEQNkkT084xZRD8EgbftIaojHFrvh4vo+zWNQV0cu17WQx12RYPPfNqcBmsV9iZ2QC0kIqSoaOR+hxmdiqvSfzA2xAxR6aqvpOxGDLNDB+qkogJ121L3hNm52BKnEgNrVqGqrhORI9Xa1pGaeTscpYxvID0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405117; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=7D0x+7C+MvhzYpgX6YUAoAIatGCvC2iHtUDGAlLTcHU=; b=k6y63/nnUHrtUPmy/elxCwAZi7dp/Hr4afVUk4mBqbupg6tsEsYSBj6vzg3kZXEngZuz3yrwpdNI1AFK523rhe/YTgLbz2pGY+DUjtgth+5EXeqGjaOOGl3FgMZvON009A4aWaZvmrGd709PbRPJGxkrSRRWyXdyS1lWWuokQ8M= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405117498237.3305021311844; Mon, 24 Apr 2023 23:45:17 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNv-0003wy-3f; Tue, 25 Apr 2023 02:42:43 -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 1prCNq-0003rK-62 for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:38 -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 1prCNk-0004M7-5E for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:37 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-100-e2cUoHCTMImtKP0_1Rx3PA-1; Tue, 25 Apr 2023 02:42:27 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 71FB4101A5D1; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 4DF0A4C83A; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id DA47C21F9829; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404951; 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=7D0x+7C+MvhzYpgX6YUAoAIatGCvC2iHtUDGAlLTcHU=; b=Q0hu6YF5CKBcsvBqr898m2OFx+Dn1M/FNm94Zyn/Nk2t7/oNYmqvN82PUGPIsbQi1KbUjn 8Ba2rZOlu/ckz5v6Ht4Krh3N8S3zn2FYYoMZKRObLSmXnn2GKa4f8mItfkKlImAFvHwtZ2 CiEJQyBdLsu2Spiz9NbQErx2G0shrrU= X-MC-Unique: e2cUoHCTMImtKP0_1Rx3PA-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 13/16] qapi: Replace ad hoc "since" documentation by member documentation Date: Tue, 25 Apr 2023 08:42:20 +0200 Message-Id: <20230425064223.820979-14-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.5 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405118147100017 MemoryDeviceInfoKind, NetClientDriver, and GuestPanicAction mention some members only in ad hoc since documentation. The generated documentation shows these members as "Not documented". Replace by formal member documentation. Add actual documentation text for the GuestPanicAction members, to match existing member documentation there. For the others, merely move existing "since" information. Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- qapi/machine.json | 11 ++++++++--- qapi/net.json | 21 ++++++++------------- qapi/run-state.json | 6 +++++- 3 files changed, 21 insertions(+), 17 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index 1a90376f4e..5a18913767 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1260,6 +1260,14 @@ ## # @MemoryDeviceInfoKind: # +# @nvdimm: since 2.12 +# +# @virtio-pmem: since 4.1 +# +# @virtio-mem: since 5.1 +# +# @sgx-epc: since 6.2. +# # Since: 2.1 ## { 'enum': 'MemoryDeviceInfoKind', @@ -1302,9 +1310,6 @@ # # Union containing information about a memory device # -# nvdimm is included since 2.12. virtio-pmem is included since 4.1. -# virtio-mem is included since 5.1. sgx-epc is included since 6.2. -# # Since: 2.1 ## { 'union': 'MemoryDeviceInfo', diff --git a/qapi/net.json b/qapi/net.json index ec66b39b70..3606d9d27f 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -641,14 +641,15 @@ # # Available netdev drivers. # -# Since: 2.7 +# @l2tpv3: since 2.1 +# @vhost-vdpa: since 5.1 +# @vmnet-host: since 7.1 +# @vmnet-shared: since 7.1 +# @vmnet-bridged: since 7.1 +# @stream: since 7.2 +# @dgram: since 7.2 # -# @vhost-vdpa since 5.1 -# @vmnet-host since 7.1 -# @vmnet-shared since 7.1 -# @vmnet-bridged since 7.1 -# @stream since 7.2 -# @dgram since 7.2 +# Since: 2.7 ## { 'enum': 'NetClientDriver', 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'stream', @@ -669,12 +670,6 @@ # # Since: 1.2 # -# 'l2tpv3' - since 2.1 -# 'vmnet-host' - since 7.1 -# 'vmnet-shared' - since 7.1 -# 'vmnet-bridged' - since 7.1 -# 'stream' since 7.2 -# 'dgram' since 7.2 ## { 'union': 'Netdev', 'base': { 'id': 'str', 'type': 'NetClientDriver' }, diff --git a/qapi/run-state.json b/qapi/run-state.json index bfc15ecad5..e5f5d31395 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -467,7 +467,11 @@ # # @pause: system pauses # -# Since: 2.1 (poweroff since 2.8, run since 5.0) +# @poweroff: system powers off (since 2.8) +# +# @run: system continues to run (since 5.0) +# +# Since: 2.1 ## { 'enum': 'GuestPanicAction', 'data': [ 'pause', 'poweroff', 'run' ] } --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405028; cv=none; d=zohomail.com; s=zohoarc; b=NmBV5bAZCLw9GnmuOpTBf/S2GBt8f2p/pYRLw2sqi+gDGJDf+mwdm50X9jdDoO/8Av89illPQgUbmeEvBGRcarzoXFTsDmELhBHTYD3lsWISidpwWZ8YtSiaKm9kpyfwDDixFMYu3mkPnY0o+Vv/fsxHyoK18e75ZhZov8z+gNg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405028; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=bAiIXkTR4yMwAvoN0NHiE4OcT5TSg9eON9JUsUnjpyo=; b=YgpraVFvt6PHzy6je0rDCXDAqABJkoOE+UCWZnJL0LODYOi8EKHn2fws74IHWlC7TtBwdVBuxSm4GR5Fk94JmggmvS8hhtEznNxjcR07xSOa1AEQP2STg977pv3BwfKfdIUUDZzg6kTOYmIcEs3Oxu5YkcWcx7+Zcltr0HUqta4= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405028768580.8723949260278; Mon, 24 Apr 2023 23:43:48 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNt-0003vy-Hf; Tue, 25 Apr 2023 02:42:41 -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 1prCNo-0003ot-ML for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:36 -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 1prCNj-0004LS-FG for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:36 -0400 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-657-bWD-vWKNN-aNvt25tHX35g-1; Tue, 25 Apr 2023 02:42:27 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 684CA1C06EDF; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 465032166B41; Tue, 25 Apr 2023 06:42:26 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id DDEF621F9831; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404950; 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=bAiIXkTR4yMwAvoN0NHiE4OcT5TSg9eON9JUsUnjpyo=; b=To5hEC0A+AXxwdgs6z0S3r7Kq8Qasssq/saxT32Tv98C5ODzGckjULmGhnk7AysDJeV+kS kJJDDEPaNRIMU0XujZNvlrTk6Y2EYJhGeS01fuFt1UJ6WRDpr2JguzJ90iuL0LA9ghhek1 hGYIqhJaBELJq7pIdiFKW2cBF5cRsF4= X-MC-Unique: bWD-vWKNN-aNvt25tHX35g-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 14/16] qapi: Fix misspelled section tags in doc comments Date: Tue, 25 Apr 2023 08:42:21 +0200 Message-Id: <20230425064223.820979-15-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.6 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405030640100006 Section tags are case sensitive and end with a colon. Screwing up either gets them interpreted as ordinary paragraph. Fix a few. Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- qapi/machine.json | 4 ++-- qapi/migration.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index 5a18913767..fcd69965e5 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -517,7 +517,7 @@ # @targets: Target root bridge IDs from -device ...,id=3D for each root # bridge. # -# Since 7.1 +# Since: 7.1 ## { 'struct': 'CXLFixedMemoryWindowOptions', 'data': { @@ -532,7 +532,7 @@ # # @cxl-fmw: List of CXLFixedMemoryWindowOptions # -# Since 7.1 +# Since: 7.1 ## { 'struct' : 'CXLFMWProperties', 'data': { 'cxl-fmw': ['CXLFixedMemoryWindowOptions'] } diff --git a/qapi/migration.json b/qapi/migration.json index 477ee4d35b..1b6c7b19e4 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1991,7 +1991,7 @@ # # data: migration thread name # -# returns: information about migration threads +# Returns: information about migration threads # # Since: 7.2 ## --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405145; cv=none; d=zohomail.com; s=zohoarc; b=JukYA4zKuMhlG4kXvDUg0YtXs1o6N1tZGLA6elFhvRVTKTqtcK1JTZtLfU3IHSgdfBzkm7eCoxHsOhwXZ0829YOGh2ma6W8wrkl9Jqc7v7LW7NAG2eiVnZ70LCBQPWiihSj3KwJPex72SDQwcWfmDRhUlO/ADWG2LQafo6CjiWQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405145; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=QDpQV06NfgVcspa4es6zhNZleoHG7UY4WS2OAhGfowg=; b=RUp3k/usspJ20e0G0eV8dl2G3QbCL8YxtJGNg5sUipxBrr9DLuEbDjNiPM8bGmkI22w7KrpLPpm4ztC46ywHan9bteohDCzPMj8IuB9JisaRKzmxx+/QwQXM6abRREWBdQ8khEkQIx2vafrHoeltIs2Oy8+5DXLtQj3p10i+gGY= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405145487777.0635060466993; Mon, 24 Apr 2023 23:45:45 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNu-0003wI-Mi; Tue, 25 Apr 2023 02:42:42 -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 1prCNs-0003tJ-9S for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:40 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1prCNk-0004MW-Gv for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:40 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-637-QkPe6hPtMlCYM3fmpa7X9Q-1; Tue, 25 Apr 2023 02:42:28 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 59650811E7C; Tue, 25 Apr 2023 06:42:27 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 3676740C2064; Tue, 25 Apr 2023 06:42:27 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id E0EED21F9835; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404951; 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=QDpQV06NfgVcspa4es6zhNZleoHG7UY4WS2OAhGfowg=; b=WG7PfpHW5jb4wdl+tJTbZjLHLy/7P5KVngyTVh4UU0nypUQcdHRBr7qmaAfTj9z5cTWyCV neOA0G4k3D17Twu5S/Ei5Ui9Z7A8W2TrImjvOnoIY9o2eArpSdjznBY+yAS0QfCVDbdI6L 5YzKcrL8RJCks/P4oA074rlCHeRQlbI= X-MC-Unique: QkPe6hPtMlCYM3fmpa7X9Q-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 15/16] qapi: Format since information the conventional way: (since X.Y) Date: Tue, 25 Apr 2023 08:42:22 +0200 Message-Id: <20230425064223.820979-16-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.1 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405147213100009 Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau --- qapi/block-core.json | 6 +++--- qapi/stats.json | 2 +- qapi/tpm.json | 3 +-- qapi/ui.json | 6 +++--- 4 files changed, 8 insertions(+), 9 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 9dd5ed9a47..b57978957f 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1318,10 +1318,10 @@ # value is monotonically increasing. # # @busy: false if the job is known to be in a quiescent state, with -# no pending I/O. Since 1.3. +# no pending I/O. (Since 1.3) # # @paused: whether the job is paused or, if @busy is true, will -# pause itself as soon as possible. Since 1.3. +# pause itself as soon as possible. (Since 1.3) # # @speed: the rate limit, bytes per second # @@ -2741,7 +2741,7 @@ # # @on-error: the action to take on an error (default report). # 'stop' and 'enospc' can only be used if the block device -# supports io-status (see BlockInfo). Since 1.3. +# supports io-status (see BlockInfo). (Since 1.3) # # @filter-node-name: the node name that should be assigned to the # filter driver that the stream job inserts into the gr= aph diff --git a/qapi/stats.json b/qapi/stats.json index f17495ee65..36d5f4dc94 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -69,7 +69,7 @@ # # @vcpu: statistics that apply to a single virtual CPU. # -# @cryptodev: statistics that apply to a crypto device. since 8.0 +# @cryptodev: statistics that apply to a crypto device (since 8.0) # # Since: 7.1 ## diff --git a/qapi/tpm.json b/qapi/tpm.json index 4e2ea9756a..eac87d30b2 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -44,8 +44,7 @@ # An enumeration of TPM types # # @passthrough: TPM passthrough type -# @emulator: Software Emulator TPM type -# Since: 2.11 +# @emulator: Software Emulator TPM type (since 2.11) # # Since: 1.5 ## diff --git a/qapi/ui.json b/qapi/ui.json index e9599dea50..88de458ba9 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -1207,13 +1207,13 @@ # window resizes (virtio-gpu) this will default to "on", # assuming the guest will resize the display to match # the window size then. Otherwise it defaults to "off". -# Since 3.1 +# (Since 3.1) # @show-tabs: Display the tab bar for switching between the various grap= hical # interfaces (e.g. VGA and virtual console character devices) # by default. -# Since 7.1 +# (Since 7.1) # @show-menubar: Display the main window menubar. Defaults to "on". -# Since 8.0 +# (Since 8.0) # # Since: 2.12 ## --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682405054; cv=none; d=zohomail.com; s=zohoarc; b=S30cznkIisRA5zVIcu/8zzc1RGH7Bpn8ivBFNR3DQqLjVmwyG+5y9EUlc+lTseelBXBM6FrmKALe27gY4CK5nz8tEo1oRp2aKJ+WczPaKY2M5gEb1S7vCIKCMP7Nv5/2i3vQS4+AXo/2JJ3O4Wi7tbeRsDQD4sPk36LMt9SPKz4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682405054; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=mrHMrosKDQaKSe8rxiYwmF82/vlFDdSh72QjQ16rbYg=; b=Dp6ZoAHYKGJ/5DYWQzGXKFQVHYaU7lvrg9Kk2fN1v79t4sImuWAtjSnUflT4jDQBFd+zMVxUu+XWt83ZDa1UiZw5B9lPfBhy76IR09Sxw7uxa/7cPPpj4Am550q3zNG6pHW8NSTbYlyDK8Kq+OpXwjTZ7RXLupWWp2KUqWq54Lg= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682405054703518.5665233808257; Mon, 24 Apr 2023 23:44:14 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1prCNw-0003ym-C9; Tue, 25 Apr 2023 02:42:44 -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 1prCNs-0003ux-VX for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:40 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1prCNk-0004MX-Ji for qemu-devel@nongnu.org; Tue, 25 Apr 2023 02:42:40 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-635-QubYTjSGP4-6qAMqte4wzA-1; Tue, 25 Apr 2023 02:42:28 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 7AE88858289; Tue, 25 Apr 2023 06:42:27 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 3835414171B8; Tue, 25 Apr 2023 06:42:27 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id E43C421F9836; Tue, 25 Apr 2023 08:42:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682404951; 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=mrHMrosKDQaKSe8rxiYwmF82/vlFDdSh72QjQ16rbYg=; b=e8gaiIpRoJgWF1KhlayBxXkc3lbm6e48Y5zF4ZW+umWk1lAa7pbLrVyaynzvFbVWW39Rgr 0jatETIYyBaSnRWIEBIbEOrp8RMPyDflReOmXWmJsFSLNg0Vo9GTVmrm8SYOru7rBKms+V JPrCI2wXv66TINyA9rhIT1+5Oqk+K5E= X-MC-Unique: QubYTjSGP4-6qAMqte4wzA-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH v2 16/16] qapi storage-daemon/qapi: Fix documentation section structure Date: Tue, 25 Apr 2023 08:42:23 +0200 Message-Id: <20230425064223.820979-17-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-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.1 on 10.11.54.7 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682405056506100001 In the QEMU QMP Reference Manual, subsection "Block core (VM unrelated)" is empty. Its contents is at the end of subsection "Background jobs" instead. That's because qapi/job.json is included first from qapi/block-core.json, which makes qapi/job.json's documentation go between qapi/block-core.json's subsection heading and contents. In the QEMU Storage Daemon QMP Reference Manual, section "Block Devices" contains nothing but an empty subsection "Block core (VM unrelated)". The latter's contents is at the end section "Socket data types", along with subsection "Block device exports". Subsection "Background jobs" is at the end of section "Cryptography". All this is because storage-daemon/qapi/qapi-schema.json includes modules in a confused order. Fix both as follows. Turn subsection "Background jobs" into a section. Move it before section "Block devices" in the QEMU QMP Reference Manual, by including qapi/jobs.json right before qapi/block.json. Reorder include directives in storage-daemon/qapi/qapi-schema.json to match the order in qapi/qapi-schema.json, so that the QEMU Storage Daemon QMP Reference Manual's section structure the QEMU QMP Reference Manual's. In the QEMU QMP Reference Manual, qapi/cryptodev.json's documentation is at the end of section "Virtio devices". That's because it lacks a section heading, and therefore gets squashed into whatever section happens to precede it. Add section heading so it's in section "Cryptography devices". Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-Andr=C3=A9 Lureau Reviewed-by: Eric Blake Acked-by: zhenwei pi --- qapi/cryptodev.json | 4 ++++ qapi/job.json | 2 +- qapi/qapi-schema.json | 2 +- storage-daemon/qapi/qapi-schema.json | 22 +++++++++++++++------- 4 files changed, 21 insertions(+), 9 deletions(-) diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json index f33f96a692..cf960ea81f 100644 --- a/qapi/cryptodev.json +++ b/qapi/cryptodev.json @@ -4,6 +4,10 @@ # This work is licensed under the terms of the GNU GPL, version 2 or later. # See the COPYING file in the top-level directory. =20 +## +# =3D Cryptography devices +## + ## # @QCryptodevBackendAlgType: # diff --git a/qapi/job.json b/qapi/job.json index bc4104757a..9e29a796c5 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -2,7 +2,7 @@ # vim: filetype=3Dpython =20 ## -# =3D=3D Background jobs +# =3D Background jobs ## =20 ## diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index e57d8ff801..bb7217da26 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -43,11 +43,11 @@ { 'include': 'sockets.json' } { 'include': 'run-state.json' } { 'include': 'crypto.json' } +{ 'include': 'job.json' } { 'include': 'block.json' } { 'include': 'block-export.json' } { 'include': 'char.json' } { 'include': 'dump.json' } -{ 'include': 'job.json' } { 'include': 'net.json' } { 'include': 'rdma.json' } { 'include': 'rocker.json' } diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qap= i-schema.json index 67749d1101..f10c949490 100644 --- a/storage-daemon/qapi/qapi-schema.json +++ b/storage-daemon/qapi/qapi-schema.json @@ -15,18 +15,26 @@ =20 { 'include': '../../qapi/pragma.json' } =20 +# Documentation generated with qapi-gen.py is in source order, with +# included sub-schemas inserted at the first include directive +# (subsequent include directives have no effect). To get a sane and +# stable order, it's best to include each sub-schema just once, or +# include it first right here. + +{ 'include': '../../qapi/common.json' } +{ 'include': '../../qapi/sockets.json' } +{ 'include': '../../qapi/crypto.json' } +{ 'include': '../../qapi/job.json' } + ## # =3D Block devices ## { 'include': '../../qapi/block-core.json' } { 'include': '../../qapi/block-export.json' } + { 'include': '../../qapi/char.json' } -{ 'include': '../../qapi/common.json' } -{ 'include': '../../qapi/control.json' } -{ 'include': '../../qapi/crypto.json' } -{ 'include': '../../qapi/introspect.json' } -{ 'include': '../../qapi/job.json' } { 'include': '../../qapi/authz.json' } -{ 'include': '../../qapi/qom.json' } -{ 'include': '../../qapi/sockets.json' } { 'include': '../../qapi/transaction.json' } +{ 'include': '../../qapi/control.json' } +{ 'include': '../../qapi/introspect.json' } +{ 'include': '../../qapi/qom.json' } --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682589259; cv=none; d=zohomail.com; s=zohoarc; b=hy9GWgSgYoBFBYETnjAd4CL1l242WeQUK5BDWAtGFsVPbMpYGGIIvNCKjggqJPjO624CP8XZsgbJlE/XFNYBZg/o8Y+VkEbjPoJU2TX9wufXEqpzBY3sZluhhtRAfETlOlEXmL0GKr5MTc/mScfn85z+rs/aoAhMqjUyOhoTB8A= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682589259; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=uHYyBz+fmnoc8Dkb2G/7Q1mzvfUIsMnmiow0yU6kOro=; b=C7vmt7QkgrzoZ6GSS06Dt1fiHeOgnslZEbRw2mddueHKtS49JWvIOOcovAOe4wh93v8qMyl+ASiVmiOiEPuTPuZtrfIRlK8mMPcujEAnkYD5eWl0rRB4dgbXi+N9n3z4ROyhzMlRpg3FRyR0TDmQG7+pqHGkxu3BTq+qI773wFo= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682589259125919.50031989779; Thu, 27 Apr 2023 02:54:19 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pryK9-0005NG-KQ; Thu, 27 Apr 2023 05:54:01 -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 1pryK6-0005MN-BJ for qemu-devel@nongnu.org; Thu, 27 Apr 2023 05:53:58 -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 1pryK3-0000NO-Oh for qemu-devel@nongnu.org; Thu, 27 Apr 2023 05:53:58 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-47-R6iH-MwpP5KiCWcgoXYn_g-1; Thu, 27 Apr 2023 05:53:49 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id BFB29884EC1; Thu, 27 Apr 2023 09:53:48 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id A029AC15BAD; Thu, 27 Apr 2023 09:53:47 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 79B3F21E6608; Thu, 27 Apr 2023 11:53:46 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682589233; 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=uHYyBz+fmnoc8Dkb2G/7Q1mzvfUIsMnmiow0yU6kOro=; b=TXnfG/r0PzBaBTJ0sFzhi5xMKIUNmKpe307htZOYn9shDq9rC5LNf/YqBHe3udKoT6Dm/Q QK3rQSgLTaZhV1wrfOiFWyANngLdI1IkMWtsgul2aJBv35PmnA4qKezxLa8W+CzhgaIAOi l09RYzRfrs6JKJ7knwSLJ/Wygc/By38= X-MC-Unique: R6iH-MwpP5KiCWcgoXYn_g-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls Date: Thu, 27 Apr 2023 11:53:46 +0200 Message-Id: <20230427095346.1238913-2-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.1 on 10.11.54.8 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682589259942100007 Content-Type: text/plain; charset="utf-8" Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.rst | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index d81aac7a19..14983b074c 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1059,6 +1059,59 @@ For example:: 'returns': ['BlockStats'] } =20 =20 +Markup pitfalls +~~~~~~~~~~~~~~~ + +A blank line is required between list items and paragraphs. Without +it, the list may not be recognized, resulting in garbled output. Good +example:: + + # An event's state is modified if: + # + # - its name matches the @name pattern, and + # - if @vcpu is given, the event has the "vcpu" property. + +Without the blank line this would be a single paragraph. + +Indentation matters. Bad example:: + + # @none: None (no memory side cache in this proximity domain, + # or cache associativity unknown) + +The description is parsed as a definition list with term "None (no +memory side cache in this proximity domain," and definition "or cache +associativity unknown)". + +Section tags are case-sensitive and end with a colon. Good example:: + + # Since: 7.1 + +Bad examples (all ordinary paragraphs):: + + # since: 7.1 + + # Since 7.1 + + # Since : 7.1 + +Likewise, member descriptions require a colon. Good example:: + + # @interface-id: Interface ID + +Bad examples (all ordinary paragraphs):: + + # @interface-id Interface ID + + # @interface-id : Interface ID + +Undocumented members are not flagged, yet. Instead, the generated +documentation describes them as "Not documented". Think twice before +adding more undocumented members. + +When you change documentation comments, please check the generated +documentation comes out as intended! + + Client JSON Protocol introspection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.39.2 From nobody Sun May 19 15:58:38 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1682589266; cv=none; d=zohomail.com; s=zohoarc; b=R569cnkDhrqncSjHZP2Ke14icQmbUI6tXWtvbRgFAOAG/vBvBjWA2fBAAfKVf/xuZNUuHIeCwlyYcKedysVnQUE407Geg87L6MZ/78pHwQk12n2GX9S+ncgyOCi9U/B5irAmCu6J0KQt74ikoAf1Z0AG44pbZwZ8P2IjWA3uaq0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1682589266; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=uHYyBz+fmnoc8Dkb2G/7Q1mzvfUIsMnmiow0yU6kOro=; b=Zi3GXhAi8MLtq3ElZ0uXSMQT1JZfgpzVeE3ywHjWdxxjPQY9vqklHxsdkrzpQ4RcP42ka55P/Cqmzo5eBFlf7HDc1AbnTVEUeizGVHUFoLKF8u1+DI7UoOcilhH7KLw28/sLWvnUFusAaW2bC4TPH1UYypCOAlEl54K1V04KR2s= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1682589266970779.3308131952914; Thu, 27 Apr 2023 02:54:26 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pryKF-0005RT-Fz; Thu, 27 Apr 2023 05:54: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 1pryKA-0005NN-6C for qemu-devel@nongnu.org; Thu, 27 Apr 2023 05:54:02 -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 1pryK3-0000NP-Pk for qemu-devel@nongnu.org; Thu, 27 Apr 2023 05:54:01 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-601-jT5YynCLNcKZHx1KyPXdsg-1; Thu, 27 Apr 2023 05:53:49 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id C0B6485A5A3; Thu, 27 Apr 2023 09:53:48 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.39.192.121]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 9F9A8C15BA0; Thu, 27 Apr 2023 09:53:47 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 77E9E21E66EF; Thu, 27 Apr 2023 11:53:46 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1682589233; 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=uHYyBz+fmnoc8Dkb2G/7Q1mzvfUIsMnmiow0yU6kOro=; b=J5bD4yMbs7e6tbkU6LbN1N0grqdeSNc4D3SDLNwazeSgcIVrNfz/TSv+DA80fHFxocRm8R CSS717ZAbhfa2eZrvFhlIUTjhWX6tekUnHtP71HaR66J0lRBs4VLACqWKU5lSBk6lQbeol K0eBm4UwwYG1mLSftqSfjEt4iCvEHV0= X-MC-Unique: jT5YynCLNcKZHx1KyPXdsg-1 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com, hreitz@redhat.com, pbonzini@redhat.com, marcandre.lureau@redhat.com, arei.gonglei@huawei.com, pizhenwei@bytedance.com, jsnow@redhat.com, vsementsov@yandex-team.ru, eduardo@habkost.net, marcel.apfelbaum@gmail.com, wangyanan55@huawei.com, quintela@redhat.com, jasowang@redhat.com, yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com, kkostiuk@redhat.com, qemu-block@nongnu.org, marcandre.lureau@gmail.com, david@redhat.com Subject: [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls Date: Thu, 27 Apr 2023 11:53:45 +0200 Message-Id: <20230427095346.1238913-1-armbru@redhat.com> In-Reply-To: <20230425064223.820979-1-armbru@redhat.com> References: <20230425064223.820979-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.1 on 10.11.54.8 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.171, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1682589268824100003 Content-Type: text/plain; charset="utf-8" Signed-off-by: Markus Armbruster Reviewed-by: Juan Quintela Reviewed-by: Vladimir Sementsov-Ogievskiy --- docs/devel/qapi-code-gen.rst | 53 ++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index d81aac7a19..14983b074c 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1059,6 +1059,59 @@ For example:: 'returns': ['BlockStats'] } =20 =20 +Markup pitfalls +~~~~~~~~~~~~~~~ + +A blank line is required between list items and paragraphs. Without +it, the list may not be recognized, resulting in garbled output. Good +example:: + + # An event's state is modified if: + # + # - its name matches the @name pattern, and + # - if @vcpu is given, the event has the "vcpu" property. + +Without the blank line this would be a single paragraph. + +Indentation matters. Bad example:: + + # @none: None (no memory side cache in this proximity domain, + # or cache associativity unknown) + +The description is parsed as a definition list with term "None (no +memory side cache in this proximity domain," and definition "or cache +associativity unknown)". + +Section tags are case-sensitive and end with a colon. Good example:: + + # Since: 7.1 + +Bad examples (all ordinary paragraphs):: + + # since: 7.1 + + # Since 7.1 + + # Since : 7.1 + +Likewise, member descriptions require a colon. Good example:: + + # @interface-id: Interface ID + +Bad examples (all ordinary paragraphs):: + + # @interface-id Interface ID + + # @interface-id : Interface ID + +Undocumented members are not flagged, yet. Instead, the generated +documentation describes them as "Not documented". Think twice before +adding more undocumented members. + +When you change documentation comments, please check the generated +documentation comes out as intended! + + Client JSON Protocol introspection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.39.2