From patchwork Fri Feb 28 13:43:35 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Markus Armbruster X-Patchwork-Id: 13996445 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 605C8C19776 for ; Fri, 28 Feb 2025 13:44:25 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1to0em-0004CX-5i; Fri, 28 Feb 2025 08:44:00 -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 1to0eY-00049W-Qm for qemu-devel@nongnu.org; Fri, 28 Feb 2025 08:43:49 -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 1to0eW-0004dj-FD for qemu-devel@nongnu.org; Fri, 28 Feb 2025 08:43:46 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740750223; 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; bh=3t4wWRsTdcDh/6oP1JOHE53eENmtJW9iD8oy/7lCkko=; b=dIKw3+GdTYVL0f3/rQOuwledKjDLuVK+LhqRqoj9CazFzqE094kqnIoW9hrGXgi0bgTdSy NrB9lbIBfusSCFqkto8ThSqjqx2geYeGvGwCY4WmGAtu4Gp9XtBDLhH+JscTGHYp0WU2kY w81VzFnQeewaWgOV86mGyLnic2TtoPM= 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-616-x4Dz9dd6MoGwUrTSIV0CiA-1; Fri, 28 Feb 2025 08:43:39 -0500 X-MC-Unique: x4Dz9dd6MoGwUrTSIV0CiA-1 X-Mimecast-MFC-AGG-ID: x4Dz9dd6MoGwUrTSIV0CiA_1740750219 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (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 EDF46180087A; Fri, 28 Feb 2025 13:43:38 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.45.242.9]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 94D44300019E; Fri, 28 Feb 2025 13:43:37 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 18F7721E675E; Fri, 28 Feb 2025 14:43:35 +0100 (CET) From: Markus Armbruster To: qemu-devel@nongnu.org Cc: michael.roth@amd.com, berrange@redhat.com Subject: [PATCH] docs/devel/qapi-code-gen: Discourage use of 'prefix' Date: Fri, 28 Feb 2025 14:43:35 +0100 Message-ID: <20250228134335.132278-1-armbru@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 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: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.444, 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+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org 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 Reviewed-by: Daniel P. Berrangé --- 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 derived 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. 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