OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

input: Document why x-input-send-event is still experimental

Browse Source 
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 <eblake@redhat.com>
Message-Id: <1447354243-31825-1-git-send-email-eblake@redhat.com>
Reviewed-by: Gerd Hoffmann <kraxel@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
Eric Blake 2015-11-12 11:50:43 -07:00 committed by Markus Armbruster
parent 39a65e2c24
commit 513e7cdbae
1 changed files with 11 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
qapi-schema.json
View File

@ -3579,16 +3579,22 @@
# Button of a pointer input device (mouse, tablet). # Button of a pointer input device (mouse, tablet).
# #
# Since: 2.0 # 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', { 'enum' : 'InputButton',
'data' : [ 'Left', 'Middle', 'Right', 'WheelUp', 'WheelDown' ] } 'data' : [ 'Left', 'Middle', 'Right', 'WheelUp', 'WheelDown' ] }
## ##
# @InputButton # @InputAxis
# #
# Position axis of a pointer input device (mouse, tablet). # Position axis of a pointer input device (mouse, tablet).
# #
# Since: 2.0 # 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', { 'enum' : 'InputAxis',
'data' : [ 'X', 'Y' ] } 'data' : [ 'X', 'Y' ] }
@ -3679,7 +3685,10 @@
# #
# Since: 2.2 # 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', { 'command': 'x-input-send-event',