[PATCH] text: Improve text protocol documentation

[Jan Arne Petersen]

From: Jan Arne Petersen <jpetersen at openismus.com>

Add some missing descriptions to the text protocol file.

---
 protocol/text.xml | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/protocol/text.xml b/protocol/text.xml
index eded1c8..857fd83 100644
--- a/protocol/text.xml
+++ b/protocol/text.xml
@@ -40,9 +40,9 @@
     <request name="set_surrounding_text">
       <description summary="sets the surrounding text">
         Sets the plain surrounding text around the input position. Cursor is the
-        position within the surrounding text. Anchor is the position of the
+        byte index within the surrounding text. Anchor is the byte index of the
         selection anchor within the surrounding text. If there is no selected
-        text anchor is the same as cursor.
+	text anchor is the same as cursor.
       </description>
       <arg name="text" type="string"/>
       <arg name="cursor" type="uint"/>
@@ -68,7 +68,12 @@
       <arg name="seat" type="object" interface="wl_seat"/>
     </request>
     <request name="reset">
-    </request>
+      <description summary="reset">
+        Should be called by an editor widget when the input state should
+        be reseted, for example after the text was changed outside of the
+        normal input method flow.
+      </description>
+     </request>
     <request name="set_micro_focus">
       <arg name="x" type="int"/>
       <arg name="y" type="int"/>
@@ -79,19 +84,43 @@
     <request name="set_content_type"/>
 
     <event name="commit_string">
+      <description summary="commit">
+        Notify when text should be inserted into the editor widget. The text
+        to commit could be either just a single character after a key press
+        or the result of some composing (pre-edit). It also sets the new
+        cursor position (as byte index) relative to the inserted text.
+      </description>
       <arg name="text" type="string"/>
       <arg name="index" type="uint"/>
     </event>
     <event name="preedit_string">
+      <description summary="pre-edit">
+        Notify when a new composing text (pre-edit) should be set around the
+        current cursor position. Any previously set composing text should
+        be removed. It also sets the cursor positon (as byte index) relative
+        to the start of the composing text.
+      </description>
       <arg name="text" type="string"/>
       <arg name="index" type="uint"/>
     </event>
     <event name="delete_surrounding_text">
+      <description summary="delete surrounding text">
+        Notify when the text around the current cursor position should be
+        deleted. Index is relative to the current cursor (as byte index).
+        Length is the length of deleted text (as bytes).
+      </description>
       <arg name="index" type="int"/>
       <arg name="length" type="uint"/>
     </event>
     <event name="preedit_styling"/>
     <event name="key">
+      <description summary="key">
+        Notify when a key event was sent. Key events should not be used
+        for normal text input operations, which should be done with
+        commit_string, delete_surrounfing_text, etc. The key event follows
+        the wl_keyboard key event convention. Key is a XKB keycode, state a
+        wl_keyboard key_state.
+      </description>
       <arg name="key" type="uint"/>
       <arg name="state" type="uint"/>
     </event>
-- 
1.7.11.4