From nobody Mon Feb 9 02:05:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; 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=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 163524677656465.20308902675185; Tue, 26 Oct 2021 04:12:56 -0700 (PDT) Received: from localhost ([::1]:50624 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mfKNx-0005qg-R2 for importer@patchew.org; Tue, 26 Oct 2021 07:12:55 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:33126) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mfKLi-0003hT-9O for qemu-devel@nongnu.org; Tue, 26 Oct 2021 07:10:37 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:59028) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mfKLg-0005Zs-7N for qemu-devel@nongnu.org; Tue, 26 Oct 2021 07:10:34 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-562-C9y2E9FxOJKxnJ9mLbKfIw-1; Tue, 26 Oct 2021 07:10:28 -0400 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A35CA18414B6; Tue, 26 Oct 2021 11:10:25 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-7.ams2.redhat.com [10.36.112.7]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 5D42C5DD68; Tue, 26 Oct 2021 11:10:25 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id E7CE111380AA; Tue, 26 Oct 2021 13:10:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1635246631; 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=qXsWxIM8aVu0WS55lpdZTaHOWr45uIRuZB8adCEFPwc=; b=BuVKz2a+MCPu2T9QYIA2+X9A5exQBskFFCPA88/WPIG60D2lovE+B6zddOHqT8g3d3EgP1 yVZUnLVsNp/XzuP3810oNVG4w/e2G+zEWCsIdonbf8tBbzELDb3Xl6EjSOoDAv0ozbNum2 aaMGMwul5/nwSXaszsNOlnkc+d5zr7w= X-MC-Unique: C9y2E9FxOJKxnJ9mLbKfIw-1 From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PATCH 1/2] docs/devel/qapi-code-gen: Drop a duplicate paragraph Date: Tue, 26 Oct 2021 13:10:22 +0200 Message-Id: <20211026111023.76937-2-armbru@redhat.com> In-Reply-To: <20211026111023.76937-1-armbru@redhat.com> References: <20211026111023.76937-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=armbru@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable 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: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , jsnow@redhat.com, eblake@redhat.com, mdroth@linux.vnet.ibm.com, marcandre.lureau@redhat.com Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1635246778526100001 Content-Type: text/plain; charset="utf-8" Commit 55ec69f8b1 "docs/devel/qapi-code-gen.txt: Update to new rST backend conventions" accidentally duplicated a paragraph. Drop it. Cc: Peter Maydell Signed-off-by: Markus Armbruster Reviewed-by: John Snow Reviewed-by: Philippe Mathieu-Daud=C3=A9 --- docs/devel/qapi-code-gen.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index b2569de486..1f6805a705 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -993,12 +993,6 @@ multiline argument descriptions. A 'Since: x.y.z' tagged section lists the release that introduced the definition. =20 -The text of a section can start on a new line, in -which case it must not be indented at all. It can also start -on the same line as the 'Note:', 'Returns:', etc tag. In this -case if it spans multiple lines then second and subsequent -lines must be indented to match the first. - An 'Example' or 'Examples' section is automatically rendered entirely as literal fixed-width text. In other sections, the text is formatted, and rST markup can be used. --=20 2.31.1 From nobody Mon Feb 9 02:05:43 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; 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=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1635247455721235.23243066351904; Tue, 26 Oct 2021 04:24:15 -0700 (PDT) Received: from localhost ([::1]:38834 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mfKYw-0000QB-Ci for importer@patchew.org; Tue, 26 Oct 2021 07:24:14 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:33112) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mfKLg-0003hM-W4 for qemu-devel@nongnu.org; Tue, 26 Oct 2021 07:10:34 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:27925) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mfKLc-0005Yt-C1 for qemu-devel@nongnu.org; Tue, 26 Oct 2021 07:10:31 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-594-RXeigo9lNdyaZBQI7ERrYg-1; Tue, 26 Oct 2021 07:10:26 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A39281030C2B; Tue, 26 Oct 2021 11:10:25 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-112-7.ams2.redhat.com [10.36.112.7]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 5FDD85F4EE; Tue, 26 Oct 2021 11:10:25 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id EB64B11380B8; Tue, 26 Oct 2021 13:10:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1635246627; 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=y9WHk2vijC92BVSL64OdXsCmyjOnosDFALxFGp0h1MM=; b=ZTXRTy5EHmDsoP16IXu4NEhBCGe/NgNljOhNKO37dU5Dxkc2TjEvt/OaA3R/O4xN2NJviC gYpn3qOOIFRcVK0h1M6b74xGxwgTDX2vCHhfFesWranUYlls1T1c6UJwMWW3+dsOyckczK kgfK9ak3X+w9AeL0frDk6PTNLjWxLzc= X-MC-Unique: RXeigo9lNdyaZBQI7ERrYg-1 From: Markus Armbruster To: qemu-devel@nongnu.org Subject: [PATCH 2/2] docs/devel/qapi-code-gen: Belatedly document feature documentation Date: Tue, 26 Oct 2021 13:10:23 +0200 Message-Id: <20211026111023.76937-3-armbru@redhat.com> In-Reply-To: <20211026111023.76937-1-armbru@redhat.com> References: <20211026111023.76937-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=armbru@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable 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: -27 X-Spam_score: -2.8 X-Spam_bar: -- X-Spam_report: (-2.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin Wolf , jsnow@redhat.com, eblake@redhat.com, mdroth@linux.vnet.ibm.com, marcandre.lureau@redhat.com Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1635247457051100001 Content-Type: text/plain; charset="utf-8" Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected to document how to document feature flags. Make up for that. Cc: Kevin Wolf Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.rst | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 1f6805a705..4b79623f51 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -949,15 +949,16 @@ definition must have documentation. Definition documentation starts with a line naming the definition, followed by an optional overview, a description of each argument (for commands and events), member (for structs and unions), branch (for -alternates), or value (for enums), and finally optional tagged -sections. +alternates), or value (for enums), a description of each feature (if +any), and finally optional tagged sections. =20 -Descriptions of arguments can span multiple lines. The description -text can start on the line following the '\@argname:', in which case it -must not be indented at all. It can also start on the same line as -the '\@argname:'. In this case if it spans multiple lines then second -and subsequent lines must be indented to line up with the first -character of the first line of the description:: +The description of an argument or feature 'name' starts with +'\@name:'. The description text can start on the line following the +'\@argname:', in which case it must not be indented at all. It can +also start on the same line as the '\@argname:'. In this case if it +spans multiple lines then second and subsequent lines must be indented +to line up with the first character of the first line of the +description:: =20 # @argone: # This is a two line description @@ -979,6 +980,12 @@ The number of spaces between the ':' and the text is n= ot significant. Extensions added after the definition was first released carry a '(since x.y.z)' comment. =20 +The feature descriptions must be preceded by a line "Features:", like +this:: + + # Features: + # @feature: Description text + A tagged section starts with one of the following words: "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". The section ends with the start of a new section. --=20 2.31.1