From nobody Thu Apr 3 10:34:18 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1741253891; cv=none; d=zohomail.com; s=zohoarc; b=MPU4TKc2szzwYowReVoVKQrRimHOKXtIYjsh+3RXllcpJdw53r4XWKv+s9Ch7kflxWuxJguP6cAElORTSm0iR5uuas+T01iWetaIU/I4BUZ5fPqTCV2i96nEw2H3IEyM+oI2CjEV058OBPCRjMDFStB//cF7Divr915QYYXOj9A= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741253891; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=wVYGB4a0aYe5XmfVsir1N1qs9DgdDMnLkRkugkD+1Xw=; b=K12JMu/LooBCsl/l/anhwsAe+DR9x1KDrLe6E/JxUAArGzb+LTE0Q2FlIPBMTOsN6544xMWiot4SUJydpCPRIZxW9/4DwmUlnjNuMhMOM0V/FBpkVsu1iOPfVoo6KqZIGcpmmqa0u/+GwMz8FHmt+tY+5rrHz7f/SnDha1MQ2is= 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 1741253891802647.4738909050901; Thu, 6 Mar 2025 01:38:11 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tq7eP-0008Tt-PV; Thu, 06 Mar 2025 04:36:23 -0500 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 1tq7eK-0008T0-Ma for qemu-devel@nongnu.org; Thu, 06 Mar 2025 04:36:16 -0500 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 1tq7eH-0002Ab-RS for qemu-devel@nongnu.org; Thu, 06 Mar 2025 04:36:16 -0500 Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-84-r6QFK1dHM6SsRkGv_-JFcg-1; Thu, 06 Mar 2025 04:36:09 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id BDB9F1955BCD for ; Thu, 6 Mar 2025 09:36:08 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.45.242.15]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 53ADE195609D for ; Thu, 6 Mar 2025 09:36:08 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id D853721E6562; Thu, 06 Mar 2025 10:36:01 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741253772; 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=wVYGB4a0aYe5XmfVsir1N1qs9DgdDMnLkRkugkD+1Xw=; b=D+KR9jX3XSfa+O53NjASTIu84np/ji/y1d/QpW4Ex4yAAVXUFRHkkyQaCj7HCEMO9xHFFY WoGZMsEe3RELNseym5C74PCc9qJWIMfNHKZaXrXC1//8jLzZwjVK8E4Bg7xhoAggEEMmOT nAtJvgnb/0lJL+1hxpwh4Suawl64fFw= X-MC-Unique: r6QFK1dHM6SsRkGv_-JFcg-1 X-Mimecast-MFC-AGG-ID: r6QFK1dHM6SsRkGv_-JFcg_1741253768 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PULL 10/10] docs/devel/qapi-code-gen: Discourage use of 'prefix' Date: Thu, 6 Mar 2025 10:36:01 +0100 Message-ID: <20250306093601.2264772-11-armbru@redhat.com> In-Reply-To: <20250306093601.2264772-1-armbru@redhat.com> References: <20250306093601.2264772-1-armbru@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1741253892980019000 QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. Commit 7bbadc60b5..64f5e9db77 eliminated most uses. Discourage new ones. Signed-off-by: Markus Armbruster Message-ID: <20250228134335.132278-1-armbru@redhat.com> Reviewed-by: Daniel P. Berrang=C3=A9 --- docs/devel/qapi-code-gen.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 9fa94251b0..f9cfe8721f 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -229,7 +229,8 @@ These are of the form PREFIX_NAME, where PREFIX is deri= ved from the enumeration type's name, and NAME from the value's name. For the example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1. The -optional 'prefix' member overrides PREFIX. +optional 'prefix' member overrides PREFIX. This is rarely necessary, +and should be used with restraint. =20 The generated C enumeration constants have values 0, 1, ..., N-1 (in QAPI schema order), where N is the number of values. There is an --=20 2.48.1