From nobody Mon Feb 9 10:12:08 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1713501665; cv=none; d=zohomail.com; s=zohoarc; b=Z/seqOmzFC3DR7IXw38PDxiw0TTAw2Ew/ZPzPUAn0sWV//nMsiOmiGSIZPSG58Z4en2Vu1ZL0pq69HZRVvxdOuTgN3OVSb9gj9dcMvWNJ2oexF9Y4XgohK7bdGqD/GfAeRfWwYmSt4m4Q6w8a8jZDypWMfQ+uS2am1EkqoTEjkQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1713501665; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=Rtuow9SNA+OVjXTxvHwCUSUMwDlRyPh0+mhQGPz8ocQ=; b=lmERad0MuD4gycUI5bwjyNlOh3YJZZerGNWRAoAAQ3fMSxvvPSEozjBFnN/4k2TgknsAm/QJtP7Wgv0AF8UekNHwSaxRInP/PSxibjhMEWPcjCobBVVhsmhowPtHwoGHlTn6ZufaVmtVQy8d9Y6TD0/EG/rZ+FvHN1PlMOqjWfM= 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 1713501665852601.4407514816437; Thu, 18 Apr 2024 21:41:05 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rxg1P-0007Vf-3q; Fri, 19 Apr 2024 00:38:47 -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 1rxg1C-0007SI-LZ for qemu-devel@nongnu.org; Fri, 19 Apr 2024 00:38:34 -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 1rxg1A-0004C4-O3 for qemu-devel@nongnu.org; Fri, 19 Apr 2024 00:38: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.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-664-2eb8cY2_Nti9Q0RrmW0RXw-1; Fri, 19 Apr 2024 00:38:30 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id C054D104B500; Fri, 19 Apr 2024 04:38:29 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.8.7]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1A6864011FF7; Fri, 19 Apr 2024 04:38:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1713501512; 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=Rtuow9SNA+OVjXTxvHwCUSUMwDlRyPh0+mhQGPz8ocQ=; b=VutQ0i6FwiaEiHxyqi9rlTvJN3rrwuDFxaKssvCM6m7jcLhp2whjKmk5NpqAW7mvXfzrf/ 8UzwIe8Yw0TOylhIgc34BYdbYeBi7QP5GgLTQXTA1OBS0nnvliNFqez+1ZIfO/ARGne2N2 Xg6GB4Z9gjXQn2ZCfhFeaaHqrtnno+o= X-MC-Unique: 2eb8cY2_Nti9Q0RrmW0RXw-1 From: John Snow To: qemu-devel@nongnu.org Cc: =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Markus Armbruster , Victor Toso de Carvalho , Peter Maydell , Paolo Bonzini , John Snow Subject: [PATCH 11/27] docs/qapi-domain: add "Errors:" field lists Date: Fri, 19 Apr 2024 00:37:59 -0400 Message-ID: <20240419043820.178731-12-jsnow@redhat.com> In-Reply-To: <20240419043820.178731-1-jsnow@redhat.com> References: <20240419043820.178731-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.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.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -41 X-Spam_score: -4.2 X-Spam_bar: ---- X-Spam_report: (-4.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-2.067, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 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: 1713501667505100004 Content-Type: text/plain; charset="utf-8" ``:error type: descr`` can now be used to document error conditions, naming the type of error object and a description of when the error is surfaced. Like the previous Arguments patch, this patch does not apply any special QAPI syntax highlighting or cross-referencing for the types, but this can be adjusted in the future if desired. (At present, I have no commits that add such highlighting. Sphinx also does not appear to support Grouped fields with optional (or no) parameters, so the ability to exclude error types is currently not supported. If you omit the type, Sphinx treats it as a regular field list and doesn't apply the special Grouping postprocessing to it.) Signed-off-by: John Snow --- docs/qapi/index.rst | 4 ++++ docs/sphinx/qapi-domain.py | 6 ++++++ 2 files changed, 10 insertions(+) diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst index a570c37abb2..004d02e0437 100644 --- a/docs/qapi/index.rst +++ b/docs/qapi/index.rst @@ -98,6 +98,10 @@ Explicit cross-referencing syntax for QAPI modules is av= ailable with :feat unstable: More than unstable, this command doesn't even exist! :arg no-descr: :feat hallucination: This command is a figment of your imagination. + :error CommandNotFound: When you try to use this command, because it + isn't real. + :error GenericError: If the system decides it doesn't like the + argument values. It's very temperamental. =20 Field lists can appear anywhere in the directive block, but any field list entries in the same list block that are recognized as special diff --git a/docs/sphinx/qapi-domain.py b/docs/sphinx/qapi-domain.py index c0dc6482204..1f0b168fa2c 100644 --- a/docs/sphinx/qapi-domain.py +++ b/docs/sphinx/qapi-domain.py @@ -273,6 +273,12 @@ class QAPICommand(QAPIObject): names=3D("arg",), can_collapse=3DTrue, ), + GroupedField( + "error", + label=3D_("Errors"), + names=3D("error",), + can_collapse=3DTrue, + ), ] ) =20 --=20 2.44.0