[PATCH 2/3] protocol: document wl_pointer, wl_keyboard, wl_touch

[Peter Hutterer]

Most of this should be clear, but let's spell a few things out.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 protocol/wayland.xml | 69 ++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 54 insertions(+), 15 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 4750115..ac560b2 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1002,6 +1002,13 @@
   </interface>
 
   <interface name="wl_pointer" version="1">
+    <description summary="pointer input device">
+      A pointer input device is a device that is usually represented by a
+      visible cursor. Pointer input devices include mice,
+      trackballs, touchpads, etc. A multi-touch device is not a
+      wl_pointer device, see wl_touch.
+    </description>
+
     <request name="set_cursor">
       <description summary="set the pointer surface">
 	Set the pointer surface, i.e., the surface that contains the
@@ -1034,8 +1041,8 @@
 
       <arg name="serial" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
-      <arg name="hotspot_x" type="int"/>
-      <arg name="hotspot_y" type="int"/>
+      <arg name="hotspot_x" type="fixed" summary="x coordinate in surface-relative coordinates"/>
+      <arg name="hotspot_y" type="fixed" summary="y coordinate in surface-relative coordinates"/>
     </request>
 
     <event name="enter">
@@ -1048,8 +1055,8 @@
 
       <arg name="serial" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="surface_x" type="fixed"/>
-      <arg name="surface_y" type="fixed"/>
+      <arg name="surface_x" type="fixed" summary="x coordinate in surface-relative coordinates"/>
+      <arg name="surface_y" type="fixed" summary="y coordinate in surface-relative coordinates"/>
     </event>
 
     <event name="leave">
@@ -1066,8 +1073,8 @@
       </description>
 
       <arg name="time" type="uint"/>
-      <arg name="surface_x" type="fixed"/>
-      <arg name="surface_y" type="fixed"/>
+      <arg name="surface_x" type="fixed" summary="x coordinate in surface-relative coordinates"/>
+      <arg name="surface_y" type="fixed" summary="y coordinate in surface-relative coordinates"/>
     </event>
 
     <enum name="button_state">
@@ -1125,6 +1132,8 @@
 
   <interface name="wl_keyboard" version="1">
     <description summary="keyboard input device">
+      A keyboard input device is a device that emits wl_keyboard::key events,
+      representing a physical or logical change in that key's state.
     </description>
 
     <enum name="keymap_format">
@@ -1146,12 +1155,20 @@
     </event>
 
     <event name="enter">
+      <description summary="keyboard focus enter">
+        This event notifies the client that the keyboard focus has been set
+        to the surface.
+      </description>
       <arg name="serial" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="keys" type="array"/>
+      <arg name="keys" type="array" summary="keys currently down"/>
     </event>
 
     <event name="leave">
+      <description summary="keyboard focus enter">
+        This event notifies the client that the keyboard focus has left the
+        last surface entered.
+      </description>
       <arg name="serial" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
     </event>
@@ -1191,28 +1208,47 @@
 
   <interface name="wl_touch" version="1">
     <description summary="touch screen input device">
+      A touch screen input device is a direct-touch device that is not
+      represented by a visible cursor. More than one touch point may be
+      active at any time. Touch devices include touch screens and
+      multi-touch-capable devices, but exclude touchpads. Touchpads are
+      wl_pointer devices.
     </description>
 
     <event name="down">
+      <description summary="begin of a touch event sequence">
+	A new touch point has appeared on the surface. This touch point is
+	assigned a unique @id. Future events from this touchpoint reference
+	this ID. The ID ceases to be valid after a touch up event and may be
+	re-used in the future.
+      </description>
       <arg name="serial" type="uint"/>
       <arg name="time" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
-      <arg name="id" type="int" />
-      <arg name="x" type="fixed" />
-      <arg name="y" type="fixed" />
+      <arg name="id" type="int" summary="the unique ID of this touch point"/>
+      <arg name="x" type="fixed" summary="x coordinate in surface-relative coordinates"/>
+      <arg name="y" type="fixed" summary="y coordinate in surface-relative coordinates"/>
     </event>
 
     <event name="up">
+      <description summary="end of a touch event sequence">
+	The touch point has disappeared. No further events will be sent for
+	this touchpoint and the touch point's ID is released and may be
+	re-used in a future touch down event.
+      </description>
       <arg name="serial" type="uint"/>
       <arg name="time" type="uint"/>
-      <arg name="id" type="int" />
+      <arg name="id" type="int" summary="the unique ID of this touch point"/>
     </event>
 
     <event name="motion">
+      <description summary="end of a touch event sequence">
+	A touchpoint has changed coordinates.
+      </description>
       <arg name="time" type="uint"/>
-      <arg name="id" type="int" />
-      <arg name="x" type="fixed" />
-      <arg name="y" type="fixed" />
+      <arg name="id" type="int" summary="the unique ID of this touch point"/>
+      <arg name="x" type="fixed" summary="x coordinate in surface-relative coordinates"/>
+      <arg name="y" type="fixed" summary="y coordinate in surface-relative coordinates"/>
     </event>
 
     <event name="frame">
@@ -1225,7 +1261,10 @@
       <description summary="touch session cancelled">
 	Sent if the compositor decides the touch stream is a global
 	gesture. No further events are sent to the clients from that
-	particular gesture.
+	particular gesture. Touch cancellation applies to all touch points
+	currently active on this client's surface. The client is
+	responsible for finalizing the touch points, future touch points on
+	this surface may re-use the touch point ID.
       </description>
     </event>
   </interface>
-- 
1.8.1.4