From patchwork Thu Nov 12 18:50:43 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Blake X-Patchwork-Id: 543600 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 26E821402C6 for ; Fri, 13 Nov 2015 05:51:14 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; secure) header.d=comcast.net header.i=@comcast.net header.b=ka+lNZk+; dkim-atps=neutral Received: from localhost ([::1]:49136 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Zwwxk-00018g-43 for incoming@patchwork.ozlabs.org; Thu, 12 Nov 2015 13:51:12 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:55467) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZwwxQ-0000cT-II for qemu-devel@nongnu.org; Thu, 12 Nov 2015 13:50:53 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZwwxN-0001bS-8i for qemu-devel@nongnu.org; Thu, 12 Nov 2015 13:50:52 -0500 Received: from resqmta-po-06v.sys.comcast.net ([2001:558:fe16:19:96:114:154:165]:53664) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZwwxN-0001bI-3d for qemu-devel@nongnu.org; Thu, 12 Nov 2015 13:50:49 -0500 Received: from resomta-po-13v.sys.comcast.net ([96.114.154.237]) by resqmta-po-06v.sys.comcast.net with comcast id giqk1r00A57bBgG01iqovq; Thu, 12 Nov 2015 18:50:48 +0000 Received: from red.redhat.com ([24.10.254.122]) by resomta-po-13v.sys.comcast.net with comcast id giql1r00F2fD5rL01iqn7c; Thu, 12 Nov 2015 18:50:48 +0000 From: Eric Blake To: qemu-devel@nongnu.org Date: Thu, 12 Nov 2015 11:50:43 -0700 Message-Id: <1447354243-31825-1-git-send-email-eblake@redhat.com> X-Mailer: git-send-email 2.4.3 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=comcast.net; s=q20140121; t=1447354248; bh=5PGVnDPJ9u47KV7ph+O22kQ1TsuWvPnSBF2Gc+O5pDM=; h=Received:Received:From:To:Subject:Date:Message-Id; b=ka+lNZk+iXZ4HPo5ScbJJUTl/cI7t94nDvqmyuxTgifJh+Nte4MLZqUiJxpBHzR22 RHxtEitpzD3+sovX6DWV9W0cZyFLRTL7pjbacCaqcMvqlVntwH38u1m+eaXW0xseW5 L//52MkvqVwivWRENX/OOnXzPKEzkjdl/PjcWpDnnkijwm+K5QxLMz3Oeu3S3JdpTS g6jBxEv35MOyoij/GQbfMrGjJYTqwl92HQ0KaAm91zf/dLoJYRCPrMvXaQ4vhiKSVK JmGUwxGM+rM9Ifv2JV2ESf/qPOkrX74jL9mYNek+e5SqtXsdHUOUc2AuSX0cXtBCtS YVzCOwJGgceZg== X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2001:558:fe16:19:96:114:154:165 Cc: armbru@redhat.com, kraxel@redhat.com Subject: [Qemu-devel] [PATCH for-2.5 v2] input: Document why x-input-send-event is still experimental X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org The x-input-send-event command was introduced in 2.2 with mention that it is experimental, but now that several releases have elapsed without any changes, it would be nice to document why that was done and should still remain experimental in 2.5. Meanwhile, our documentation states that we prefer 'lower-case', rather than 'CamelCase', for qapi enum values. The InputButton and InputAxis enums violate this convention. However, because they are currently used primarily for generating code that is used internally; and their only exposure through QMP is via the experimental 'x-input-send-event' command, we are free to change their spelling. Of course, it would be nicer to delay such a change until the same time we promote the command to non-experimental. Adding documentation will help us remember to do that rename. We have plans to tighten the qapi generator to flag instances of inconsistent use of naming conventions; if that lands first, it will just need to whitelist these exceptions until the time we settle on the final interface. Fix a typo in the docs for InputAxis while at it. Signed-off-by: Eric Blake Reviewed-by: Gerd Hoffmann --- v2: Rather than changing spelling, just document things qapi-schema.json | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/qapi-schema.json b/qapi-schema.json index 36e59b8..323d8ea 100644 --- a/qapi-schema.json +++ b/qapi-schema.json @@ -3577,16 +3577,22 @@ # Button of a pointer input device (mouse, tablet). # # Since: 2.0 +# +# Note that the spelling of these values may change when the +# x-input-send-event is promoted out of experimental status. ## { 'enum' : 'InputButton', 'data' : [ 'Left', 'Middle', 'Right', 'WheelUp', 'WheelDown' ] } ## -# @InputButton +# @InputAxis # # Position axis of a pointer input device (mouse, tablet). # # Since: 2.0 +# +# Note that the spelling of these values may change when the +# x-input-send-event is promoted out of experimental status. ## { 'enum' : 'InputAxis', 'data' : [ 'X', 'Y' ] } @@ -3677,7 +3683,10 @@ # # Since: 2.2 # -# Note: this command is experimental, and not a stable API. +# Note: this command is experimental, and not a stable API. Things that +# might change before it becomes stable include the spelling of enum +# values for InputButton and InputAxis, and the notion of how to designate +# which console will receive the event. # ## { 'command': 'x-input-send-event',