From 3f4008acb3debbf08e45d98e52739c3bcd134d4d Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sat, 30 Mar 2013 01:11:41 -0400
Subject: [PATCH] docs: Improve wl_pointer protocol docs

Some descriptions were missing here.
---
 protocol/wayland.xml | 43 +++++++++++++++++++++++++++++++++----------
 1 file changed, 33 insertions(+), 10 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 442862d..87e3d5f 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1167,6 +1167,17 @@
   </interface>
 
   <interface name="wl_pointer" version="1">
+    <description summary="pointer input device">
+      The wl_pointer interface represents one or more input devices,
+      such as mice, which control the pointer location and pointer_focus
+      of a seat.
+
+      The wl_pointer interface generates motion, enter and leave
+      events for the surfaces that the pointer is located over,
+      and button and axis events for button presses, button releases
+      and scrolling.
+    </description>
+
     <request name="set_cursor">
       <description summary="set the pointer surface">
 	Set the pointer surface, i.e., the surface that contains the
@@ -1197,7 +1208,7 @@
 	undefined, and the wl_surface is unmapped.
       </description>
 
-      <arg name="serial" type="uint"/>
+      <arg name="serial" type="uint" summary="serial of the enter event"/>
       <arg name="surface" type="object" interface="wl_surface" allow-null="true"/>
       <arg name="hotspot_x" type="int"/>
       <arg name="hotspot_y" type="int"/>
@@ -1206,9 +1217,11 @@
     <event name="enter">
       <description summary="enter event">
 	Notification that this seat's pointer is focused on a certain
-	surface. When an seat's focus enters a surface, the pointer image
+	surface.
+
+	When an seat's focus enters a surface, the pointer image
 	is undefined and a client should respond to this event by setting
-	an appropriate pointer image.
+	an appropriate pointer image with the set_cursor request.
       </description>
 
       <arg name="serial" type="uint"/>
@@ -1219,6 +1232,11 @@
 
     <event name="leave">
       <description summary="leave event">
+	Notification that this seat's pointer is no longer focused on
+	a certain surface.
+
+	The leave notification is sent before the enter notification
+	for the new focus.
       </description>
       <arg name="serial" type="uint"/>
       <arg name="surface" type="object" interface="wl_surface"/>
@@ -1226,8 +1244,9 @@
 
     <event name="motion">
       <description summary="pointer motion event">
-	Notification of pointer location change. The arguments surface_[xy]
-	are the location relative to the focused surface.
+	Notification of pointer location change. The arguments
+	surface_x and surface_y are the location relative to the
+	focused surface.
       </description>
 
       <arg name="time" type="uint"/>
@@ -1240,14 +1259,16 @@
         Describes the physical state of a button which provoked the button
 	event.
       </description>
-      <entry name="released" value="0" summary="button is not pressed"/>
-      <entry name="pressed" value="1" summary="button is pressed"/>
+      <entry name="released" value="0" summary="The button is not pressed"/>
+      <entry name="pressed" value="1" summary="The button is pressed"/>
     </enum>
 
     <event name="button">
       <description summary="pointer button event">
-	Mouse button click and release notifications.  The location
-	of the click is given by the last motion or pointer_focus event.
+	Mouse button click and release notifications.
+
+	The location of the click is given by the last motion or
+	enter event.
       </description>
 
       <arg name="serial" type="uint"/>
@@ -1257,7 +1278,9 @@
     </event>
 
     <enum name="axis">
-      <description summary="axis types"/>
+      <description summary="axis types">
+	Describes the axis types of scroll events.
+      </description>
       <entry name="vertical_scroll" value="0"/>
       <entry name="horizontal_scroll" value="1"/>
     </enum>
-- 
2.7.4