From nobody Sat Oct 24 00:32:59 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875434; cv=none; d=zohomail.com; s=zohoarc; b=f6piXSXwPJJ7WyGXadkG+9KISVM8FKzIlQ9ls83lW5c5x6GkUAu/RV66AcTbLp2Q7LYS/+bn5lGzfA50NND96al17RJxY3QrGFwrQE9t9G9J7XVpfX61VeFeZ5bhR5TC9nVQsSqbPsdRRYIb+YMBTnL0a7z0vkXHjNVtnWh0E2k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875434; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=gOhUlaqYft9ZEwA3v6D1+kcKuZduQ2ieI8v0P5bHeA8=; b=l3Xl4B0/rxijXYUrxGwbUhBcZQkzZfVJvv9p9j+/ysjbhnmzdnoX2UnQHz+NdXqz8yuD1vK6fERCz/cHkqGwW20QJYCpxMJtRZJ86/yfoX0X4kdWi9RkdvTnQCA5jbBaPUupAPSX2mzNBj8r8Q419kStEulrzvyk76PBBVhYFho= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1790875434547319.56794398792704; Thu, 1 Oct 2026 10:23:54 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUf-0008WO-69; Thu, 01 Oct 2026 13:22:53 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUc-0008Vc-Q9 for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:50 -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 1xCKUb-0006vd-Ax for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:50 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-637-JmispcK4MW2HovZbJTJMfw-1; Thu, 01 Oct 2026 13:22:43 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 92E24180058D; Thu, 1 Oct 2026 17:22:42 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id A7B591800348; Thu, 1 Oct 2026 17:22:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875367; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=gOhUlaqYft9ZEwA3v6D1+kcKuZduQ2ieI8v0P5bHeA8=; b=LLPiZYbZiJaVFkzTLrusCa8ycnersu7xL0SYcD3KgNnhZhspLA1Ys3Ns6Fnu+zdqbEAe1M 4jyv966iwf8g+S9/2NpgmZFBSikJOT6lMwHjsUXPFlFGz6sP2rM3EjsmL/eVU5OAYwd8tJ g5z7q/Rms955RTymoYWNr12pfqYf+gs= X-MC-Unique: JmispcK4MW2HovZbJTJMfw-1 X-Mimecast-MFC-AGG-ID: JmispcK4MW2HovZbJTJMfw_1790875362 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 01/11] docs/qapi-code-gen: change "x.y.z" to "x.y" for Since: documentation Date: Thu, 1 Oct 2026 13:22:28 -0400 Message-ID: <20261001172239.2825745-2-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875435117158500 Content-Type: text/plain; charset="utf-8" We prefer using only x.y for Since: tags, not x.y.z. Adjust docs accordingly. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- docs/devel/qapi-code-gen.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index b1cc5b5f0db..f276a2bc9bc 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1001,7 +1001,7 @@ indented like this:: .. FIXME union branches should be described, too. =20 Extensions added after the definition was first released carry a -"(since x.y.z)" comment. +"(since x.y)" comment. =20 The feature descriptions must be preceded by a blank line and then a line "Features:", like this:: @@ -1034,7 +1034,7 @@ detailing a relevant error condition. For example:: # - If @device does not exist, DeviceNotFound # - Any other error returns a GenericError. =20 -A "Since: x.y.z" tagged section lists the release that introduced the +A "Since: x.y" tagged section lists the release that introduced the definition. =20 "TODO" sections are not rendered (they are for developers, not users of --=20 2.55.0 From nobody Sat Oct 24 00:33:00 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875450; cv=none; d=zohomail.com; s=zohoarc; b=oLNYqAxD99gCDmGsKoxhivB6g3ExvKlpQooLjqg8/v/q9PN2DlJkbDgm9DwePjdLLMPLOxyse3GyrBQxUBZF29pKqv4jDgsJLl4zmU0alTdaC6oBSy5O8l4/aKmdj9Z7//A0CxFZ5cnq5YtKW/d4CATWA25BHP7X3+VedFXoC2Y= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875450; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=1kDOFPBW2oMrVVHxyWRIyMlnE1a2Vn5NxO3NmZkA/Wc=; b=Dqjun+Hyw1SVVUcRT2IBeOzxJvm8M4FDp4zceb9nuyJFK8EEU/Ire6VXRnTJzmNN0DKUVKBUZCOWoYAPZyo7IX/B3LVp7KEZJwlCiIbgqzkV3RiiWVT/pF9cfV1WsS776LaAfe3kcCL0c3/f0RslPl4eU+JVjnFFqWzSyvPO0Ds= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1790875450164700.7960004188504; Thu, 1 Oct 2026 10:24:10 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUg-00005J-QH; Thu, 01 Oct 2026 13:22:54 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUe-0008WN-V8 for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:53 -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 1xCKUd-0006vv-15 for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:52 -0400 Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-588-oF-Usu_dM-OK7_dktPM1cg-1; Thu, 01 Oct 2026 13:22:45 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E282B1936125; Thu, 1 Oct 2026 17:22:43 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 053A0180056E; Thu, 1 Oct 2026 17:22:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875370; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=1kDOFPBW2oMrVVHxyWRIyMlnE1a2Vn5NxO3NmZkA/Wc=; b=KTrw3fxMjQ6sA5jAXq90ijmZRarGD42eJRao99/mxp2CbZPEEJrIQIyNDv4Rc8gEF9gAyl 7FeT4M0C3oEa+hkuGQ1Ym1PGePcIpcgfoa0cN1zAbnURbjyMW/dlwxyufdEiAWHKnXlOzZ 2NFgclxua3nMaODhyD0CdBuq0m4wLaQ= X-MC-Unique: oF-Usu_dM-OK7_dktPM1cg-1 X-Mimecast-MFC-AGG-ID: oF-Usu_dM-OK7_dktPM1cg_1790875364 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 02/11] docs/qapi-code-gen: add "Putting it all together" subsection Date: Thu, 1 Oct 2026 13:22:29 -0400 Message-ID: <20261001172239.2825745-3-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 9 X-Spam_score: 0.9 X-Spam_bar: / X-Spam_report: (0.9 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875451281158500 Content-Type: text/plain; charset="utf-8" Separate the specification portion of the documentation section from the holistic examples. Avoid naming the section "Examples" because it might be confused with the literal case of documenting how code examples should themselves be documented. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index f276a2bc9bc..0f66f012be1 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1089,6 +1089,9 @@ Highlighting in non-QMP languages can be accomplished= by using the achieved by omitting the language argument. =20 =20 +Putting it all together +^^^^^^^^^^^^^^^^^^^^^^^ + Examples of complete definition documentation:: =20 ## --=20 2.55.0 From nobody Sat Oct 24 00:33:00 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875436; cv=none; d=zohomail.com; s=zohoarc; b=nd3VCfXefM0FP7SLgtTxgzhWf21RyF5p7R4s6TUVo77VDgjD6T1SBf3VVCXI+29sK8qF3AYjAVIp97M0Zf4YHQcT/C6vtcmDR4RUHoQMJCObqB/kcXPBtwukWVqW7vYw+ixpnAfjWfTWgnIGL6Q/Acdz+cA6UnEyzQ4ooi3asWM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875436; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=7Lb3eGf0FXX9eE+1r6OB1d4Cyeor+pv5f6KD+VZq458=; b=UilL+5cvMMjp8cPsTn1lcNAbYKdP+4PWWCVUTOMW6K04NVl7FIIIU7XDJVl9vV9OMwHn6B1BRZBDfjVwTdf0bPnFHMkCjM+NCKlI2ajuee/F91hrdjxc4urBGwhZ794u3LIgVh/ejeBhbKmbdnDKSlutHvambQlw1Dcn1ZoIPLM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1790875436217386.130840866005; Thu, 1 Oct 2026 10:23:56 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUm-00007X-A5; Thu, 01 Oct 2026 13:23:00 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUf-00004x-SS for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:54 -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 1xCKUe-0006w8-Bd for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:53 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-466-0uzP3nwVPF-GFLWpwWQYRQ-1; Thu, 01 Oct 2026 13:22:46 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 2546C18007FD; Thu, 1 Oct 2026 17:22:45 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 437DE180056E; Thu, 1 Oct 2026 17:22:44 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875371; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=7Lb3eGf0FXX9eE+1r6OB1d4Cyeor+pv5f6KD+VZq458=; b=R+1fIZBSErJTNdy1i34D02TXJG9wahXhDKnilFaGNrrp/jzhCIuQxMmyJGcmUXyR80EUP5 3KanHph0eis15x5rlg527pufQXCHhAkxiuc52uc0RI2yQ4qvP3ZuYiQ7jgpXjyQxVznIsR rb9XZZED7mUj0OYiHjxEG/A2aE6NmFw= X-MC-Unique: 0uzP3nwVPF-GFLWpwWQYRQ-1 X-Mimecast-MFC-AGG-ID: 0uzP3nwVPF-GFLWpwWQYRQ_1790875365 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 03/11] docs/qapi-code-gen: add "TODO" subsection Date: Thu, 1 Oct 2026 13:22:30 -0400 Message-ID: <20261001172239.2825745-4-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875437026158500 Content-Type: text/plain; charset="utf-8" Split the "TODO" section description into its own little section, and add a dedicated example for it. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 0f66f012be1..977ed1aa3bd 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1037,8 +1037,7 @@ detailing a relevant error condition. For example:: A "Since: x.y" tagged section lists the release that introduced the definition. =20 -"TODO" sections are not rendered (they are for developers, not users of -QMP). In other sections, the text is formatted, and rST markup can be +In other sections, the text is formatted, and rST markup can be used. =20 QMP Examples can be added by using the ``.. qmp-example::`` directive. @@ -1089,6 +1088,17 @@ Highlighting in non-QMP languages can be accomplishe= d by using the achieved by omitting the language argument. =20 =20 +TODO +^^^^ + +"TODO" tagged sections are not rendered (they are for developers, not user= s of +QMP). They can appear anywhere after the introductory section:: + + # + ## TODO: This is not rendered in the documentation. + # + + Putting it all together ^^^^^^^^^^^^^^^^^^^^^^^ =20 --=20 2.55.0 From nobody Sat Oct 24 00:33:00 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875455; cv=none; d=zohomail.com; s=zohoarc; b=BIeRUHWreSP4vMa/gug8jL/7txh9nFP8Cmt9OoNLtsnYsm1aavvw48waFRWUWQB4vDuZkCJOzGPvlwQwDbRbedRUfhaOrYChH8t8stuHJ5cj+YN3FqUqXgriapGSD8tjIcd4Tbfq7YEV+G6vWMlJgQkcCOuQppxv9BLYTWs5n9g= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875455; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=heSp2XsbY/eTkiY2OCCy6coI8HThCxSD5E3KRwwAkas=; b=P7TdZb+J9hla5COoHf6bn1qbvfiOFQpXfI6RyTyO3Bz3+UISKS/53Lcl2Z1jSUYMsXUMKVdOgAPAdsnVgZINhIxmw30n0NYKJtzGqbrOwe89wAK9isVPV6Mh6xT0zjknxIsuIOi3xcOXrRihyP6EX2nAb8U9NIzKq+bQNgYCbAg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1790875455642989.3569143584865; Thu, 1 Oct 2026 10:24:15 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUg-000058-5f; Thu, 01 Oct 2026 13:22:54 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUe-0008W7-5w for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:52 -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 1xCKUc-0006vo-O7 for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:51 -0400 Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-311-6aRNtb6YMQ-4LxwwlDt5eQ-1; Thu, 01 Oct 2026 13:22:47 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 41C881936107; Thu, 1 Oct 2026 17:22:46 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 5A39A1800348; Thu, 1 Oct 2026 17:22:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875369; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=heSp2XsbY/eTkiY2OCCy6coI8HThCxSD5E3KRwwAkas=; b=E8xC6VDIRNeR328G1Xw+ZHIzAIKgVAUF1YdKh1+6JGQGpLW35W6gZa+iYbwTEMSuF2YhRs SZ4up3UHvVWot22/MnfXAakTZi3hjfQIZclPdp2SvvB1+xX+jBiziiSorUfXZ0h5dNyNjL zkX7/Kg9USmek///cPmNpFksBOf4kJw= X-MC-Unique: 6aRNtb6YMQ-4LxwwlDt5eQ-1 X-Mimecast-MFC-AGG-ID: 6aRNtb6YMQ-4LxwwlDt5eQ_1790875366 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 04/11] docs/qapi-code-gen: add "Since" subsection Date: Thu, 1 Oct 2026 13:22:31 -0400 Message-ID: <20261001172239.2825745-5-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 9 X-Spam_score: 0.9 X-Spam_bar: / X-Spam_report: (0.9 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875457137158500 Content-Type: text/plain; charset="utf-8" Add a standalone "Since:" documentation section, with usage example. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 977ed1aa3bd..fcb52ce157e 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1034,8 +1034,6 @@ detailing a relevant error condition. For example:: # - If @device does not exist, DeviceNotFound # - Any other error returns a GenericError. =20 -A "Since: x.y" tagged section lists the release that introduced the -definition. =20 In other sections, the text is formatted, and rST markup can be used. @@ -1088,6 +1086,17 @@ Highlighting in non-QMP languages can be accomplishe= d by using the achieved by omitting the language argument. =20 =20 +Since +^^^^^ + +A "Since: x.y" section lists the release that introduced the +definition:: + + # + # Since: 11.2 + # + + TODO ^^^^ =20 --=20 2.55.0 From nobody Sat Oct 24 00:33:00 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875435; cv=none; d=zohomail.com; s=zohoarc; b=oBQUJ++lGc+lhfTTMVjK1rZv72K1zkh8z5486MPpm0NAaQ1YUzQMnW4B3i2nWYU6CIGNilmCzlyUc7nV8gx9ah5TMZNblVwPh5G3/c8xpok6B8LMyUUV9ZYBUiBycFmgt4j3/HAyjJflTfB1fEAts+eARG1VZsTHh6uvpHg27hk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875435; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=WMyik7tYov5ovdgrsl8O72Dfyg5fnx0SW/wI/urp4Us=; b=hbUgL4eXx7LOIxWcELDYeLDCFkuipBbmSvSGMSChfxcVTYjKH7hsPoB3VpGHcDpWRxLqv6+7jVxEasj2KEuyknP/DUHa5YVtYiKcZciQfBw3G4vu86tipmYcdv1s5KvhEUNbyQBC7dwg1OjNqWqu1bbzK+ZiPgfGBrpJUZzTpdA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 17908754359873.6650386081885244; Thu, 1 Oct 2026 10:23:55 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUg-00005G-8o; Thu, 01 Oct 2026 13:22:54 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUd-0008W1-Sg for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:52 -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 1xCKUc-0006vm-Cv for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:51 -0400 Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-41-D5hG5l8oPVi2b1rGdG_vBw-1; Thu, 01 Oct 2026 13:22:48 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 58BCA1955DC2; Thu, 1 Oct 2026 17:22:47 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 7A9E6180056E; Thu, 1 Oct 2026 17:22:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875369; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=WMyik7tYov5ovdgrsl8O72Dfyg5fnx0SW/wI/urp4Us=; b=R4qMYNYQK/4QqarYM+2h6RdZ7FJrepEhLNcitf037ZN3KWsnG/dpHk7Q41bNU1ag3NHPHt 4SvPpi7bEY/P3ZFArDCZ8LOxER4rcnXBFMpckwIPQnLIR+OCkIGOu4VN6zg8zG7XBp82fm alJDv9FXz+wM8/21uKx7ceayeiJ4H80= X-MC-Unique: D5hG5l8oPVi2b1rGdG_vBw-1 X-Mimecast-MFC-AGG-ID: D5hG5l8oPVi2b1rGdG_vBw_1790875367 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 05/11] docs/qapi-code-gen: add "Details" docs subsection Date: Thu, 1 Oct 2026 13:22:32 -0400 Message-ID: <20261001172239.2825745-6-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 9 X-Spam_score: 0.9 X-Spam_bar: / X-Spam_report: (0.9 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875437021158500 Content-Type: text/plain; charset="utf-8" Mostly, this is just adding a heading and explaining that arbitrary rST formatting is allowed in this section. Note: The QAPI parser still refers to these sections internally as "PLAIN", but I wanted to name this documentation section after the eventual, true name for the section. It is effectively only an implementation detail at this point. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index fcb52ce157e..8fc75488019 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1035,8 +1035,15 @@ detailing a relevant error condition. For example:: # - Any other error returns a GenericError. =20 =20 -In other sections, the text is formatted, and rST markup can be -used. +Details +^^^^^^^ + +Details sections are comprised of one or more paragraphs of rST +formatted text, but otherwise are not marked up with any QAPI-specific +syntax. In general, this text contains in-depth explanations of the +definition being documented and may include various rST admonitions +like ``.. seealso::``, ``.. note::``, etc. This is also the section +where QMP usage examples should be placed. =20 QMP Examples can be added by using the ``.. qmp-example::`` directive. In its simplest form, this can be used to contain a single QMP code --=20 2.55.0 From nobody Sat Oct 24 00:33:00 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875430; cv=none; d=zohomail.com; s=zohoarc; b=Ws4iOnEgWlXx3DEwPPy64IW7E1HzU4mWNrSrnI6J3dQ6KovFV433luELqyiG/bJMqs8YM+AYDdvtAgcf4/5WcR5DwXNVIcnn9pamhtIWLHvskFPZMlcqRgfcCNY3mv5WyPWeGVJ+ts0blq0MbJIGnfrEgOl9/R42EOBUcztqPpY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875430; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=g8at+swstqrGAUyB6OIzkTtvoAOHY+PW+wLe6WMUYbs=; b=IrototAOv2oKUzvUo/Ew9SSUvAriVWQRtqD448VY0HAU1fpSYG0YdraVrar6ephwSF3LdO6iKvrEKdT1A1wZORNLxVq4kOVXb3JT8FzY0GYCVnf40N5XZFoyxuUMd/n9ZIiERoTkxyWN4ge5uy4eO5Lx5Vl6R3lrj+uaBoGoavk= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 179087543082949.10447120291872; Thu, 1 Oct 2026 10:23:50 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUl-00006z-76; Thu, 01 Oct 2026 13:23:00 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUi-00005j-JT for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:56 -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 1xCKUg-0006wi-6U for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:56 -0400 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-434-D9tSikvAM0eV31SRHUsgVw-1; Thu, 01 Oct 2026 13:22:49 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8C290197702D; Thu, 1 Oct 2026 17:22:48 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id ACAC31800348; Thu, 1 Oct 2026 17:22:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875373; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=g8at+swstqrGAUyB6OIzkTtvoAOHY+PW+wLe6WMUYbs=; b=FTU4+PP+bJOn8s8x6d04cvNPTVojiDIV3u4DErFtrEKsyjH8JTxJ9d9n1E3e8vHAJ+6/KA EAoukUp38wtvoqRgn/Hhi9Nryg9x8DrL9qla1QD+iSjxZlk0gXPjSZXzMwVIr78CXBbYS0 ZSD1vzxCLYPFCwUcf4ZiiexCqaly328= X-MC-Unique: D9tSikvAM0eV31SRHUsgVw-1 X-Mimecast-MFC-AGG-ID: D9tSikvAM0eV31SRHUsgVw_1790875368 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 06/11] docs/qapi-code-gen: add "Errors" and "Returns" subsections Date: Thu, 1 Oct 2026 13:22:33 -0400 Message-ID: <20261001172239.2825745-7-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 9 X-Spam_score: 0.9 X-Spam_bar: / X-Spam_report: (0.9 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875431043158500 Content-Type: text/plain; charset="utf-8" This is a two-for-one as they are described together in one paragraph, which I split apart into two sections. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 8fc75488019..90488da7ffd 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1024,8 +1024,31 @@ like this:: # Duis aute irure dolor in reprehenderit in voluptate velit esse # cillum dolore eu fugiat nulla pariatur. =20 -"Returns" and "Errors" sections are only valid for commands. They -document the success and the error response, respectively. + +Returns +^^^^^^^ + +"Returns" sections are only valid for commands. They document the +success response of the command. If there is some nuance to capture +with the return value, it may be documented as:: + + # + # Returns: a list describing each virtual block device. Filter nodes + # that were created implicitly are skipped over. + # + +Long descriptions are written as a block, with additional lines indented. + +The type of the return value will be added to the documentation +automatically. If there is nothing relevant to add apart from type, +this section may be omitted. + + +Errors +^^^^^^ + +"Errors" sections are only valid for commands. They document +the error response(s) for a command. =20 "Errors" sections should be formatted as an rST list, each entry detailing a relevant error condition. For example:: --=20 2.55.0 From nobody Sat Oct 24 00:33:00 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875410; cv=none; d=zohomail.com; s=zohoarc; b=N1558tdCLIyjVBXcgBnZ7+PX+OGUtyhbyBJlcBumqjhFsxHO1iRElBOQoOzOKsTJbMiFLJbLCUezu8dWErm7ivVTIrFDDTotJqLqFt+eAysc30TAj1o+YWZYocRzybkkevXxeS+VOjbiZtJBlze0zITdhHYk5NzlamXaLiz3oKA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875410; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=LcofzWvDzqbOlYQzfI7ekRqRMO9baKh4hD5KFHBom4s=; b=FBASFDQoNfWEO6PfScwHRr8WifbtMIHXmAvMnDFmXthFibc36gibregWleHPaniuOZVZNjc6bSEEMCGMdglEfs6Scr42cG4UigC/1P14qZCYIXE0h2/dIPYspNXOXR4GqIF2/V7Vink2tZQnsyQRHKgLl5XqOCY2taIMzHqKzuo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1790875410363452.5800221815283; Thu, 1 Oct 2026 10:23:30 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUk-00006u-Qi; Thu, 01 Oct 2026 13:22:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUi-00005e-Fy for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:56 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUf-0006wZ-PR for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:56 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-335-dnDZ9IqIMxOsLS9k9SWSbA-1; Thu, 01 Oct 2026 13:22:50 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id A8ED71865DA0; Thu, 1 Oct 2026 17:22:49 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id C36751800348; Thu, 1 Oct 2026 17:22:48 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875373; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=LcofzWvDzqbOlYQzfI7ekRqRMO9baKh4hD5KFHBom4s=; b=D0WF1QMLbXOPOhBJy54mIaBA8+D2IZlu4ERQqLAYKTbffcCIlfcAQ3pputnclb3SxtRFzJ MG9wpKwlDbMgz8B8qoTGtiIZyKFmSOzNakdnGFrHu43SBi5bV5yqGOwb8alNt4KOJRgkDn tFhJph5lLAGru4LIivtyONA49BZno5E= X-MC-Unique: dnDZ9IqIMxOsLS9k9SWSbA-1 X-Mimecast-MFC-AGG-ID: dnDZ9IqIMxOsLS9k9SWSbA_1790875369 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 07/11] docs/qapi-code-gen: add "Tagged sections" subsection Date: Thu, 1 Oct 2026 13:22:34 -0400 Message-ID: <20261001172239.2825745-8-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875410871158500 Content-Type: text/plain; charset="utf-8" The usefulness of naming and defining a "tagged section" is waning; its only remaining use is to describe a shared syntax common to all sections. I think it's probably likely we want to omit this section entirely, but here's our chance to discuss that. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 90488da7ffd..1897cde39cf 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1011,6 +1011,12 @@ line "Features:", like this:: # # @feature: Description text =20 + +.. _doc-tagged: + +Tagged sections +^^^^^^^^^^^^^^^ + A tagged section begins with a paragraph that starts with one of the following words: "Since:", "Returns:", "Errors:", "TODO:". It ends with the start of a new section. --=20 2.55.0 From nobody Sat Oct 24 00:33:00 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875449; cv=none; d=zohomail.com; s=zohoarc; b=AKD27Ee9Nu+CUUh1/MoR59GfAzEOPjV8dyQ7b+K8Q3J/kWD+CXC+08MI5VrjYglv2HEYEqaFKkY5Coc9ktNQX1/VCcKbtHLjCr4aDUJa2ME+lhaJ/PC15+fQTvmK0tenAabA18dNQcdyf/NG3eVGSaQ0+zxcCSCLGI+JWD4pcGI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875449; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=UA9NJUGZGQHtACdSce224KO4nypWuzIASCtwqNttVwg=; b=N+SkyUx9V5SJzexm2LlCM7OiYGHkM1tMF4o+cMgaTG7K3pwR0zJ+HOoguZTyHNnDzx5jnVpYyE8HIKkmvANECIkK1QfR4mxUr2ZxjzPEPbcFpmGcupsDXpLZK1ugtb1bTIebU4wxqDla26LMkpynHDxGZMvE3oB9X+GQdRdYVug= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1790875449067212.95268378210164; Thu, 1 Oct 2026 10:24:09 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUo-000089-8m; Thu, 01 Oct 2026 13:23:02 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUh-00005N-6c for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:56 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUf-0006wV-LG for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:54 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-303-6ofdOkHBOTSVyRGgOsAFjw-1; Thu, 01 Oct 2026 13:22:51 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id BC3321802143; Thu, 1 Oct 2026 17:22:50 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id DFF591800348; Thu, 1 Oct 2026 17:22:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875373; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=UA9NJUGZGQHtACdSce224KO4nypWuzIASCtwqNttVwg=; b=FGHRh0eBkFYRMr2+IF+/lEY54PZytR1+mYv5RxcFgU2HVBBKaFZKoMcNzC8UoyXiM1CPGF A8cnhCcHW99H6dTaH4i4XsQ1+5ujKiYvQSAAPMegRH9KgCePbqObuAJmkluwwq+Z3DqcsY C58Nf21YjQOaHT3j47BAlx6S21tlyvA= X-MC-Unique: 6ofdOkHBOTSVyRGgOsAFjw-1 X-Mimecast-MFC-AGG-ID: 6ofdOkHBOTSVyRGgOsAFjw_1790875370 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 08/11] docs/qapi-code-gen: add "Descriptions" subsection Date: Thu, 1 Oct 2026 13:22:35 -0400 Message-ID: <20261001172239.2825745-9-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875451307158500 Content-Type: text/plain; charset="utf-8" Section off the part of the spec that describes descriptions. Similarly to "Tagged sections", the concept of naming "Descriptions" as a proper noun might also be something we'd like to sunset, but for now I have retained the section. I believe the documentation itself is entirely valid and useful, but we may want to come up with a term for "arguments, members, branches, or values" as a group of concepts instead - excising only "Features" as something that is different. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 1897cde39cf..7e7b11d01df 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -985,13 +985,23 @@ When documentation is required (see pragma_ 'doc-requ= ired'), every definition must have documentation. =20 Definition documentation starts with a description naming the -definition with an optional indented overview, a description of each -argument (for commands and events), member (for structs and unions), -branch (for alternates), or value (for enums), a description of each -feature (if any), and finally optional tagged sections. +definition with an optional indented overview, :ref:`descriptions +` of each argument (for commands and events), member (for +structs and unions), branch (for alternates), or value (for enums), a +description of each feature (if any), and finally optional tagged +sections. =20 -Descriptions start with '\@name:'. The description text must be -indented like this:: + +.. _doc-descrip: + +Descriptions +^^^^^^^^^^^^ + +Descriptions start with '\@name:'. These are used to document +arguments (for commands and events), members (for structs and unions), +branches (for alternates), or values (for enums). + +The description text must be indented like this:: =20 # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. --=20 2.55.0 From nobody Sat Oct 24 00:33:00 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875406; cv=none; d=zohomail.com; s=zohoarc; b=SLBVAu+wQl8D+5QujZFyFCQpoNh3MWsA18ylJftd2LqPin6B51pnDyueRdsdHYb8vM5kY0IlmK9SLa1ZE1zExuRuXytqczBApn/Mp5kNJT4L2Sqgp+zrZXNK6KYqXQlAa4H6IbCVKinTy7YUG9vT7rP0pgt4UcuQ8Cb7ql+l6KA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875406; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=d/bO0aLAO4a0bEivHsgpJrmpIIJcq9RNM8+5qXbbFkQ=; b=Jqq3LC0DE4chb3pM0sqZnMv6T7sCfnxbdDWk7TS9FsZd3uoc21daD0kBxT0roUXeBfR3hYpEfVnXWVHzipffUb2SUdWE7vXWi3aarHFRtQsTpv1Df4PENVKDKdkF002uhtqoNLT3XXc+dYQvuWTdAFsZj6aaYzwgr5l5+ljcth8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1790875406279714.2732178359716; Thu, 1 Oct 2026 10:23:26 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUk-00006t-Qj; Thu, 01 Oct 2026 13:22:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUi-00005l-M4 for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:57 -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 1xCKUg-0006ws-TF for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:56 -0400 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-421-efQfHoxGMMioTrFYA0Fz7w-1; Thu, 01 Oct 2026 13:22:52 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id D22191977528; Thu, 1 Oct 2026 17:22:51 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id F37E5180056E; Thu, 1 Oct 2026 17:22:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875374; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=d/bO0aLAO4a0bEivHsgpJrmpIIJcq9RNM8+5qXbbFkQ=; b=UIlYBdsUE6RiJfxsbqCQzPtVRzU1qzqvjimgCl21u2cCEeREGPIPCZlQ3HYKZq9gfWqsKA 78L+sULfsw4vr4xk/DC/T/51VfBuU+IT79QG8S9odhwtfeukrKJErCX4dmCVM7JvV4Fmik RVFb318y/ypR/v3J80MaPW752m99l2I= X-MC-Unique: efQfHoxGMMioTrFYA0Fz7w-1 X-Mimecast-MFC-AGG-ID: efQfHoxGMMioTrFYA0Fz7w_1790875371 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 09/11] docs/qapi-code-gen: add "Feature descriptions" subsection Date: Thu, 1 Oct 2026 13:22:36 -0400 Message-ID: <20261001172239.2825745-10-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 9 X-Spam_score: 0.9 X-Spam_bar: / X-Spam_report: (0.9 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875407202158500 Content-Type: text/plain; charset="utf-8" Move the features text down to where it would appear in-order in a QAPI documentation block, and expand it into its own subsection separate from member/arg/etc descriptions. This draft refers back to the "Descriptions" section to make it clear that they are syntactically related, but has otherwise broken the section out into its own discrete thing to make it clear that it is an entirely separate section (group of sections). The key element here is that Descriptions and Feature Descriptions have been split apart so that they can each occupy their correct relative position in the docs that mirrors their appearance in actual documentation. (i.e. members - returns - errors - features, in that order.) Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 7e7b11d01df..febe8af49f9 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -987,9 +987,10 @@ definition must have documentation. Definition documentation starts with a description naming the definition with an optional indented overview, :ref:`descriptions ` of each argument (for commands and events), member (for -structs and unions), branch (for alternates), or value (for enums), a -description of each feature (if any), and finally optional tagged -sections. +structs and unions), branch (for alternates), or value (for enums), +:ref:`feature descriptions ` of each feature (if any), and +finally optional tagged sections. + =20 =20 .. _doc-descrip: @@ -1013,14 +1014,6 @@ The description text must be indented like this:: Extensions added after the definition was first released carry a "(since x.y)" comment. =20 -The feature descriptions must be preceded by a blank line and then a -line "Features:", like this:: - - # - # Features: - # - # @feature: Description text - =20 .. _doc-tagged: =20 @@ -1074,6 +1067,23 @@ detailing a relevant error condition. For example:: # - Any other error returns a GenericError. =20 =20 +.. _doc-feat: + +Feature Descriptions +^^^^^^^^^^^^^^^^^^^^ + +Feature descriptions are a :ref:`doc-descrip` section that document featur= es +that apply to this definition. + +The feature descriptions must be preceded by a blank line and then a +line "Features:", like this:: + + # + # Features: + # + # @feature: Description text + + Details ^^^^^^^ =20 --=20 2.55.0 From nobody Sat Oct 24 00:33:00 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875456; cv=none; d=zohomail.com; s=zohoarc; b=WaJVAZBp7jLqHhUt4/6x9qUoMLbEl+MMWJl6ipVoeUePC5bMf+VwrrvVuys3/IqQMykkpUo3gre+GVNXuoEarbaJ1iCZ0MPaaj4D56UOAne7WhNyXPdYvHXaC0zR2HTpIdZNymINFGOQRtH0eAuDDfIIWKPBLJJbsoKziB6qw50= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875456; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=M0Lu4w3v5ROvHuqVnhBBxqGW5dfKhCSgiG5K8prljbs=; b=I+bOoOM6+8+Dsciup7jGEdxtQxH00T+hok02jumtBNuQGVZ0EzyhMBd8iWWSeqVl6aLlB/TTflDPGA2c+tsSwmC3U0nGwW0abNTeaarSDv9ljRsNwurvRhB4GomHGKybChChfW/4Fx9DRAAORsg2JAUESfmhS06+wwQ9LleH7IY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 179087545636662.31309674096042; Thu, 1 Oct 2026 10:24:16 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUp-00008i-44; Thu, 01 Oct 2026 13:23:03 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUl-00007W-P1 for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:23:00 -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 1xCKUk-0006xY-2Q for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:59 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-580---vaCPJxPBqx3KCE1zpiuA-1; Thu, 01 Oct 2026 13:22:53 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E54AF186BB05; Thu, 1 Oct 2026 17:22:52 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 1462F180056E; Thu, 1 Oct 2026 17:22:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875377; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=M0Lu4w3v5ROvHuqVnhBBxqGW5dfKhCSgiG5K8prljbs=; b=NexOYrH1yqZ/2lCeU5VISQgPNNvMIUmNQK+ZSVUp05oOjAkr5V7HwfkMnoTpiM3f6GJFqQ vNR6t44cFXHWyC4dxAyucPl5l0NepltFDp0NBk8imjHwSRACs48WJUPYMTnDE9gCxNmHYx eIeH8kBcWvolLuJjXcp7bT4EWWokal8= X-MC-Unique: --vaCPJxPBqx3KCE1zpiuA-1 X-Mimecast-MFC-AGG-ID: --vaCPJxPBqx3KCE1zpiuA_1790875373 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 10/11] docs/qapi-code-gen: add "Intro" subsection Date: Thu, 1 Oct 2026 13:22:37 -0400 Message-ID: <20261001172239.2825745-11-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875457161158500 Content-Type: text/plain; charset="utf-8" Give the introductory section its own small treatment. Without going into details about the as-yet-unmerged inliner, I struggle to describe precisely how the intro should be used and what types of documentation are better suited for Details. This is my attempt. I find PEP 257 https://peps.python.org/pep-0257/#one-line-docstrings to have very good advice on what should appear in a doc summary line, but did not want to reference it directly in our specification. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index febe8af49f9..4932dd35b64 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -985,13 +985,30 @@ When documentation is required (see pragma_ 'doc-requ= ired'), every definition must have documentation. =20 Definition documentation starts with a description naming the -definition with an optional indented overview, :ref:`descriptions -` of each argument (for commands and events), member (for -structs and unions), branch (for alternates), or value (for enums), -:ref:`feature descriptions ` of each feature (if any), and -finally optional tagged sections. +definition with an optional indented overview (the :ref:`doc-intro`), +:ref:`descriptions ` of each argument (for commands and +events), member (for structs and unions), branch (for alternates), or +value (for enums), :ref:`feature descriptions ` of each +feature (if any), and finally optional tagged sections. =20 =20 +.. _doc-intro: + +Intro +^^^^^ + +The Intro section names the symbol being defined and is optionally +followed by an indented brief summary or overview of the definition. + +The intro section *may* consist of multiple indented paragraphs, but +is ideally a single summary line that does not repeat type +information or reference individual arguments/members/et al:: + + ## + # @query-block-jobs: + # Return information about long-running block device operations. + # + =20 .. _doc-descrip: =20 --=20 2.55.0 From nobody Sat Oct 24 00:33:00 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1790875452; cv=none; d=zohomail.com; s=zohoarc; b=M5n1cYtS6bw65wJIBahe8o8dPmRftHoQAxsvRwe929yoB8TRA+EDFHqvxxe5ac6QmMclQeYQ6E6KLzjKGNYFbcxBVAqdxIs5zcksF3ewY0Q5r1R9ZNdpresyln3p5s0jVxiPUbNx1dCcMJDLjxZvH6jKB/AO9h03HX4raWvE1Sg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1790875452; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=CYsb7NTC8Z9e9Rqh6I1hYSOLFUYlcVN77Z36/edbuYc=; b=JbGT8ip6BSNVIRygVUtCLhysMCcp6UZuHlSNZE/IhktJxxdzIjFeEntlZQjLQJbse1WWg56SWUKkAoGpX+akuzaVeQNdAXG/JvZtbJWCQt9fhnHgva8yFTOGOa+v3n5lliSOP7aUhGxlaROHoOcoJAJi+dMkKTOsR8ndBE75tws= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1790875452901632.470225015404; Thu, 1 Oct 2026 10:24:12 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1xCKUp-00008j-4I; Thu, 01 Oct 2026 13:23:03 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1xCKUl-00006y-29 for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:59 -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 1xCKUj-0006xP-2n for qemu-devel@nongnu.org; Thu, 01 Oct 2026 13:22:58 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-640-QXG6CBpcM4eLjJl_w955VQ-1; Thu, 01 Oct 2026 13:22:55 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 0487D182A107; Thu, 1 Oct 2026 17:22:54 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 2819C18002B7; Thu, 1 Oct 2026 17:22:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1790875376; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=CYsb7NTC8Z9e9Rqh6I1hYSOLFUYlcVN77Z36/edbuYc=; b=D8NV693EcAprLDjXgk7uxiwqnj5r/TBjnxPfmK0H/8cLmZmLFP+diYW+C4VMWadNMalkU+ 1GkwtmKm4QEZeZEUGO+sxwETZgBJ/nIAS32+ni220EW5yGxJqFMoiOrZCnQDdjJEuT+g6+ eBTQKLq4YLQwDqRCC5iLfjsuK3gMqkI= X-MC-Unique: QXG6CBpcM4eLjJl_w955VQ-1 X-Mimecast-MFC-AGG-ID: QXG6CBpcM4eLjJl_w955VQ_1790875374 From: John Snow To: qemu-devel@nongnu.org Cc: Pierrick Bouvier , Michael Roth , Markus Armbruster , John Snow Subject: [PATCH 11/11] docs/qapi-code-gen: add "Tagged sections" cross-references Date: Thu, 1 Oct 2026 13:22:38 -0400 Message-ID: <20261001172239.2825745-12-jsnow@redhat.com> In-Reply-To: <20261001172239.2825745-1-jsnow@redhat.com> References: <20261001172239.2825745-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -23 X-Spam_score: -2.4 X-Spam_bar: -- X-Spam_report: (-2.4 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.331, 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_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development 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: 1790875455149158500 Content-Type: text/plain; charset="utf-8" Add some XRef markup that links to the "tagged section" subsection. I don't know if we want to keep that section, so these cross-reference additions are isolated here. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 4932dd35b64..ff7663a2666 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -989,7 +989,8 @@ definition with an optional indented overview (the :ref= :`doc-intro`), :ref:`descriptions ` of each argument (for commands and events), member (for structs and unions), branch (for alternates), or value (for enums), :ref:`feature descriptions ` of each -feature (if any), and finally optional tagged sections. +feature (if any), and finally optional :ref:`tagged sections +`. =20 =20 .. _doc-intro: @@ -1054,7 +1055,7 @@ like this:: Returns ^^^^^^^ =20 -"Returns" sections are only valid for commands. They document the +"Returns" :ref:`doc-tagged` are only valid for commands. They document the success response of the command. If there is some nuance to capture with the return value, it may be documented as:: =20 @@ -1073,8 +1074,8 @@ this section may be omitted. Errors ^^^^^^ =20 -"Errors" sections are only valid for commands. They document -the error response(s) for a command. +"Errors" :ref:`doc-tagged` are only valid for commands. They document +the error responses. =20 "Errors" sections should be formatted as an rST list, each entry detailing a relevant error condition. For example:: @@ -1162,7 +1163,7 @@ achieved by omitting the language argument. Since ^^^^^ =20 -A "Since: x.y" section lists the release that introduced the +A "Since: x.y" :ref:`doc-tagged` lists the release that introduced the definition:: =20 # --=20 2.55.0