[Qemu-devel] [PATCH for-2.5 v2] input: Document why x-input-send-event is still experimental

[Qemu-devel] [PATCH for-2.5 v2] input: Document why x-input-send-event is still experimental

[Eric Blake]

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>
---
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',
-- 
2.4.3

Re: [Qemu-devel] [PATCH for-2.5 v2] input: Document why x-input-send-event is still experimental

[Gerd Hoffmann]

On Do, 2015-11-12 at 11:50 -0700, Eric Blake wrote:
> 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.

Reviewed-by: Gerd Hoffmann <kraxel@redhat.com>

Re: [Qemu-devel] [PATCH for-2.5 v2] input: Document why x-input-send-event is still experimental

[Markus Armbruster]

Gerd Hoffmann <kraxel@redhat.com> writes:

> On Do, 2015-11-12 at 11:50 -0700, Eric Blake wrote:
>> 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.
>
> Reviewed-by: Gerd Hoffmann <kraxel@redhat.com>

Applied to qapi-next for 2.5, thanks!