diff --git a/proto/protocol.xml b/proto/protocol.xml
index 5fd38aa..61a515f 100644
--- a/proto/protocol.xml
+++ b/proto/protocol.xml
@@ -94,6 +94,13 @@
     </request>
 
     <enum name="context_type" since="1">
+      <description summary="context type">
+        This enum denotes context types for the libei context.
+
+        A context type of receiver is a libei context receiving events
+        from the EIS implementation. A context type of sender is a libei context
+        sending events to the EIS implementation.
+      </description>
       <entry name="receiver" value="0"/>
       <entry name="sender" value="1"/>
     </enum>
@@ -132,6 +139,13 @@
         so will result in the EIS implementation disconnecting the client
         on ei_connection_setup.done.
 
+        If the ei_connection_setup version is given, the interface of this
+        object is upgraded to the given version. Otherwise, the
+        ei_connection_setup version defaults to 1.
+
+        A client must not provide a ei_connection_setup version higher
+        than ei_connection_setup.version.
+
         This request must not be sent more than once per interface.
       </description>
       <arg name="name" type="string" summary="the interface name"/>
@@ -140,28 +154,29 @@
 
     <event name="version" since="1">
       <description summary="the connection setup version">
-        The highest supported version of this interface
-        by the EIS implementation. Any requests
-        send by the client must be provided in this version
+        The highest supported version of the ei_connection_setup
+        interface as supported by the EIS implementation. Any requests
+        sent by the client must be provided in this version
         or any lower version.
 
         This event is sent immediately after connection. A client
         should not issue any requests until processing this version.
 
         Note that the EIS implementation assumes that the supported
-        client version of this interface is 1 until the client announces
-        a higher version of this interface in the
+        client version of this interface is 1 unless and until the client
+        announces a higher version of this interface in the
         ei_connection_setup.interface request.
       </description>
       <arg name="version" type="uint"
         summary="the highest version supported by the EIS implementation"/>
     </event>
 
-    <event name="connection">
+    <event name="connection" since="1">
       <description summary="the core connection object">
         Provides the client with the connection object that is the top-level
         object for all future requests and events.
-        This event is sent immediately after the client sends the
+
+        This event is sent at some unspecified time after the client sends the
         ei_connection_setup.done request to the EIS implementation.
 
         The ei_connection_setup object will be destroyed by the
@@ -180,8 +195,8 @@
 
   <interface name="ei_connection" version="1">
     <description summary="core global object">
-      The core global object.  This is a special singleton object.  It
-      is used for internal ei protocol features.
+      The core connection object. This is the top-level object for any communication
+      with the EIS implementation.
     </description>
 
     <request name="sync" since="1">
@@ -204,7 +219,13 @@
            summary="callback object for the sync request"/>
     </request>
 
-    <request name="disconnect">
+    <request name="disconnect" since="1">
+      <description summary="disconnection request">
+        A request to the EIS implementation that this client should be disconnected.
+        This is a courtesy request to allow the EIS implementation to distinquish
+        between a client disconnecting on purpose and one disconnecting through the
+        socket becoming invalid.
+      </description>>
     </request>
 
     <enum name="disconnect_reason">
@@ -215,13 +236,14 @@
       <entry name="error" value="1" help="an error caused the disconnection"/>
     </enum>
 
-    <event name="disconnected">
+    <event name="disconnected" since="1">
       <description summary="disconnection event">
         This event may be sent by the EIS implementation immediately before
         the client is disconnected.
 
-        Where a client is disconnected by EIS directly, the reason is
-        disconnect_reason.disconnected and the explanation is NULL.
+        Where a client is disconnected by EIS on purpose, for example after
+        a user interaction, the reason is disconnect_reason.disconnected and
+        the explanation is NULL.
 
         Where a client is disconnected due to some invalid request or other
         protocol error, the reason is disconnect_reason.error and
@@ -264,28 +286,57 @@
 
   <interface name="ei_seat" version="1">
     <description summary="seat object">
+      An ei_seat represents a set of input devices that logically belong together. In most
+      cases only one seat is present and all input devices on that seat share the same
+      pointer and keyboard focus.
+
+      A seat has potential capabilities, a client is expected to bind to those capabilities.
+      The EIS implementation then creates logical input devices based on the capabilities the
+      client is interested in.
+
+      Immediately after creation of the ei_seat object, the EIS implementation sends a burst
+      of events with information about this seat. This burst of events is terminated by the
+      ei_seat.done event.
     </description>
 
-    <request name="release">
+    <request name="release" since="1">
       <description summary="Seat removal request">
         Notification that the client is no longer interested in this seat.
         The EIS implementation will release any resources related to this seat and
         send the ei_seat.destroyed event once complete.
+
+        Note that releasing a seat does not guarantee another seat becomes available.
+        In other words, in most single-seat cases, releasing the seat means the
+        connection becomes effectively inert.
       </description>
     </request>
 
     <enum name="capabilities" since="1">
+      <description summary="Seat capabilities">
+        A set of capabilities possible available on this seat. A client may bind to these
+        capabilies and an EIS implementation may then create device based on the bound
+        capabilities.
+      </description>
       <entry name="pointer" value="2"/>
       <entry name="pointer_absolute" value="4"/>
       <entry name="keyboard" value="8"/>
       <entry name="touch" value="16"/>
     </enum>
 
-    <request name="bind">
+    <request name="bind" since="1">
       <description summary="Seat binding">
-        Bind to the bitmask of capabilities given.
+        Bind to the bitmask of capabilities given. The bitmask is zero or more of the
+        capabilities provided in the ei_seat.capabilities event. That event's capabilities
+        are used as a mask of capabilities that can be bound.
+
+        Binding capabilities that are not supported in the ei_seat's interface version
+        is a client bug and may result in disconnection.
+
+        A client may send this request multiple times to adjust the capabilities it
+        is interested in. If capabilities are dropped, the EIS implementation may
+        ei_device.remove devices that have these capabilities.
       </description>
-      <arg name="capabilities" type="uint"/>
+      <arg name="capabilities" type="uint" enum="capabilities"/>
     </request>
 
     <event name="destroyed" since="1">
@@ -307,7 +358,7 @@
       <description summary="Seat capability notification">
         A bitmask of the capabilities of this seat.
       </description>
-      <arg name="capabilities" type="uint" enum="capabilities" help="the seat name"/>
+      <arg name="capabilities" type="uint" enum="capabilities" help="the seat capabilities"/>
     </event>
 
     <event name="done" since="1">
@@ -339,14 +390,14 @@
       </description>
     </request>
 
-    <request name="start_emulating">
+    <request name="start_emulating" since="1">
       <arg name="sequence" type="uint"/>
     </request>
 
-    <request name="stop_emulating">
+    <request name="stop_emulating" since="1">
     </request>
 
-    <request name="frame">
+    <request name="frame" since="1">
       <arg name="timestamp" type="uint"/>
       <arg name="micros" type="uint"/>
     </request>
@@ -430,17 +481,17 @@
       </description>
     </event>
 
-    <event name="resumed">
+    <event name="resumed" since="1">
     </event>
 
-    <event name="paused">
+    <event name="paused" since="1">
     </event>
 
-    <event name="start_emulating">
+    <event name="start_emulating" since="1">
       <arg name="sequence" type="uint"/>
     </event>
 
-    <event name="stop_emulating">
+    <event name="stop_emulating" since="1">
     </event>
 
     <event name="frame" since="1">
@@ -541,7 +592,7 @@
     <description summary="keyboard object">
     </description>
 
-    <request name="release">
+    <request name="release" since="1">
       <description summary="keyboard removal request">
         Notification that the client is no longer interested in this keyboard.
         The EIS implementation will release any resources related to this keyboard and
@@ -593,7 +644,7 @@
     <description summary="touchscreen object">
     </description>
 
-    <request name="release">
+    <request name="release" since="1">
       <description summary="touch removal request">
         Notification that the client is no longer interested in this touch.
         The EIS implementation will release any resources related to this touch and
@@ -601,19 +652,36 @@
       </description>
     </request>
 
-    <request name="down">
+    <request name="down" since="1">
+      <description summary="touch down request">
+        Notifies the EIS implementation about a new touch logically down at the
+        given coordinates. The touchid is a unique id for this touch. Touchids
+        may be re-used after ei_touchscreen.up.
+      </description>
       <arg name="touchid" type="uint"/>
       <arg name="x" type="float"/>
       <arg name="y" type="float"/>
     </request>
 
-    <request name="motion">
+    <request name="motion" since="1">
+      <description summary="touch motion request">
+        Notifies the EIS implementation about an existing touch changing position to
+        the given coordinates. The touchid is the unique id for this touch previously
+        sent with ei_touchscreen.down.
+      </description>
       <arg name="touchid" type="uint"/>
       <arg name="x" type="float"/>
       <arg name="y" type="float"/>
     </request>
 
-    <request name="up">
+    <request name="up" since="1">
+      <description summary="touch up request">
+        Notifies the EIS implementation about an existing touch being logically
+        up. The touchid is the unique id for this touch previously
+        sent with ei_touchscreen.down.
+
+        The touchid may be re-used after this request.
+      </description>
       <arg name="touchid" type="uint"/>
     </request>
 
@@ -624,19 +692,31 @@
       </description>
     </event>
 
-    <event name="down">
+    <event name="down" since="1">
+      <description summary="touch down request">
+        See the ei_touchscreen.down request for details. This event is
+        for ei receiver contexts.
+      </description>
       <arg name="touchid" type="uint"/>
       <arg name="x" type="float"/>
       <arg name="y" type="float"/>
     </event>
 
-    <event name="motion">
+    <event name="motion" since="1">
+      <description summary="touch motion request">
+        See the ei_touchscreen.motion request for details. This event is
+        for ei receiver contexts.
+      </description>
       <arg name="touchid" type="uint"/>
       <arg name="x" type="float"/>
       <arg name="y" type="float"/>
     </event>
 
-    <event name="up">
+    <event name="up" since="1">
+      <description summary="touch motion request">
+        See the ei_touchscreen.up request for details. This event is
+        for ei receiver contexts.
+      </description>
       <arg name="touchid" type="uint"/>
     </event>
   </interface>