diff --git a/proto/protocol.xml b/proto/protocol.xml
index 77aaf7f..1c01c90 100644
--- a/proto/protocol.xml
+++ b/proto/protocol.xml
@@ -61,6 +61,10 @@
       than 0xff000000.
     - 'object_id': a previously allocated object id
 
+    Protocol XML:
+    - a request or event marked as type="destructor" causes the object to be
+      destroyed immediately after that message has been sent.
+
     The initial connection is a two-step process:
     An ei_connection_setup object with the special ID 0 is guaranteed to
     exists. The client must send the appropriate requests to set up
@@ -69,6 +73,37 @@
     (or any lower version) that is the connection for the remainder of this
     client.
 
+    Version negotiation for interfaces is also handled in the ei_connection_setup
+    object. The client announces which interfaces are supported and their
+    respective version, future server-created objects will use that version or any
+    lower version.
+
+    In summary, a typical client connection does:
+    - connect to the socket
+    - read ei_connection_setup.version for object id 0
+    - send ei_connection_setup.interface for "ei_connection"
+    - send ei_connection_setup.interface for all other supported interfaces
+    - optionally: send ei_connection_setup.name and ei_connection_setup.context_type
+    - send ei_connection_setup.done
+    - receive the ei_connection.connection event and create that object
+    - receive ei_connection.seat (if any seats are available)
+    - ....
+    - receive ei_connection.disconnect and close the socket
+
+    As of version 1 for most interfaces, the typical object tree looks like this:
+    - ei_connection_setup (destroyed after .connection)
+    - ei_connection
+      - ei_seat
+        - ei_device
+          - ei_pointer
+          - ei_keyboard
+        - ei_device
+          - ei_touchscreen
+        - ei_device
+      - ei_seat
+        - ei_device
+      - ei_callback (destroyed after .done)
+      - ei_callback (destroyed after .done)
   -->
 
   <interface name="ei_connection_setup" version="1">
@@ -78,18 +113,18 @@
       id 0 and only exists until the connection has been set up, see the
       ei_connection_setup.connection event.
 
-      Once set up, the connection setup hands over to the main
-      ei_connection object which is the top-level object for all future
-      requests and events.
+      Once the ei_connection.connection event has been sent the connection setup
+      is destroyed by the EIS implementation.
     </description>
 
+    <!-- ei_connection_setup client requests version 1 -->
+
     <request name="done" since="1">
       <description summary="done request">
         Notify the EIS implementation that configuration is complete.
 
-        The ei_conection_setup object will be destroyed by the
-        EIS implementation after this request is processed and
-        the client must not attempt to use it after that point.
+        In the future, the EIS implementation responds by sending the
+        ei_connection_setup.connection event.
       </description>
     </request>
 
@@ -110,7 +145,8 @@
         Notify the EIS implementation of the type of this context.
 
         This request is optional, the default client type is context_type.receiver.
-        This request must not be sent more than once.
+        This request must not be sent more than once and must be sent before
+        ei_connection_setup.done.
       </description>
       <arg name="context_type" type="uint" enum="context_type" summary="the client context type"/>
     </request>
@@ -122,7 +158,8 @@
         for the EIS implementation to use this name.
 
         This request is optional, the default client name is implementation-defined.
-        This request must not be sent more than once.
+        This request must not be sent more than once and must be sent before
+        ei_connection_setup.done.
       </description>
       <arg name="name" type="string" summary="the client name"/>
     </request>
@@ -146,12 +183,15 @@
         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.
+        This request must not be sent more than once per interface and must be
+        sent before ei_connection_setup.done.
       </description>
       <arg name="name" type="string" summary="the interface name"/>
       <arg name="version" type="uint" summary="the interface version"/>
     </request>
 
+    <!-- ei_connection_setup events version 1 -->
+
     <event name="version" since="1">
       <description summary="the connection setup version">
         The highest supported version of the ei_connection_setup
@@ -197,8 +237,13 @@
     <description summary="core global object">
       The core connection object. This is the top-level object for any communication
       with the EIS implementation.
+
+      Note that for a client to receive objects of this type, it must announce
+      support for this interface in ei_connection_setup.interface.
     </description>
 
+    <!-- ei_connection client requests version 1 -->
+
     <request name="sync" since="1">
       <description summary="asynchronous roundtrip">
         The sync request asks the EIS implementation to emit the 'done' event
@@ -214,6 +259,12 @@
         <!-- FIXME: this needs to be something useful, but we don't have anything
              useful to send yet -->
         The callback_data passed in the callback is always zero.
+
+        Note that for a client to use this request it must announce
+        support for this interface in ei_connection_setup.interface. It is
+        a protocol violation to request sync without having announced the
+        "ei_callback" interface and the EIS implementation must disconnect
+        the client.
       </description>
       <arg name="callback" type="new_id" interface="ei_callback"
            summary="callback object for the sync request"/>
@@ -225,12 +276,22 @@
         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.
+
+        Immediately after sending this request, the client may destroy the
+        ei_connection object and it should close the socket. The EIS implementation
+        will treat the connection as already disconnected on receipt and does not
+        send the ei_connection.disconnect event in response to this request.
       </description>>
     </request>
 
+    <!-- ei_connection events version 1 -->
+
     <enum name="disconnect_reason" since="1">
       <description summary="disconnection reason">
-        A reason why a client was disconnected.
+        A reason why a client was disconnected. This enum is intended to
+        provide information to the client on whether it was disconnected as
+        part of normal operations or as result of an error on either the client
+        or EIS implementation side.
       </description>
       <entry name="disconnected" value="0" help="client was purposely disconnected"/>
       <entry name="error" value="1" help="an error caused the disconnection"/>
@@ -265,6 +326,10 @@
       <description summary="Seat presence notification">
         Notification that a new seat has been added.
 
+        A seat is a set of input devices that logically belong together.
+
+        This event is only sent if the client announced support for the
+        "ei_seat" interface in ei_connection_setup.interface.
         The interface version is equal or less to the client-supported
         version in ei_connection_setup.interface for the "ei_seat"
         interface.
@@ -276,10 +341,16 @@
 
   <interface name="ei_callback" version="1">
     <description summary="callback object">
+      Interface for ensuring a roundtrip to the EIS implementation.
       Clients can handle the 'done' event to get notified when
-      the related request is done.
+      the related request that created the ei_callback object is done.
+
+      Note that for a client to receive objects of this type, it must announce
+      support for this interface in ei_connection_setup.interface.
     </description>
 
+    <!-- ei_callback events version 1 -->
+
     <event name="done" type="destructor" since="1">
       <description summary="done event">
         Notify the client when the related request is done. Immediately after this event
@@ -303,8 +374,13 @@
       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.
+
+      Note that for a client to receive objects of this type, it must announce
+      support for this interface in ei_connection_setup.interface.
     </description>
 
+    <!-- ei_seat client requests version 1 -->
+
     <request name="release" since="1">
       <description summary="Seat removal request">
         Notification that the client is no longer interested in this seat.
@@ -345,10 +421,16 @@
       <arg name="capabilities" type="uint" enum="capabilities"/>
     </request>
 
+    <!-- ei_seat events version 1 -->
+
     <event name="destroyed" type="destructor" since="1">
       <description summary="Seat removal notification">
         This seat has been removed and a client should release all
         associated resources.
+
+        This ei_seat object will be destroyed by the EIS implementation immmediately after
+        after this event is sent and as such the client must not attempt to use
+        it after that point.
       </description>
     </event>
 
@@ -356,6 +438,8 @@
       <description summary="Seat name notification">
         The name of this seat, if any. This event is optional and sent once immediately
         after object creation.
+
+        It is a protocol violation to send this event after the ei_seat.done event.
       </description>
       <arg name="name" type="string" help="the seat name"/>
     </event>
@@ -363,6 +447,8 @@
     <event name="capabilities" since="1">
       <description summary="Seat capability notification">
         A bitmask of the capabilities of this seat.
+
+        It is a protocol violation to send this event after the ei_seat.done event.
       </description>
       <arg name="capabilities" type="uint" enum="capabilities" help="the seat capabilities"/>
     </event>
@@ -371,6 +457,8 @@
       <description summary="Seat setup completion notification">
         Notification that the initial burst of events is complete and
         the client can set up this seat now.
+
+        It is a protocol violation to send this event more than once.
       </description>
     </event>
 
@@ -378,6 +466,8 @@
       <description summary="Device presence notification">
         Notification that a new device has been added.
 
+        This event is only sent if the client announced support for the
+        "ei_device" interface in ei_connection_setup.interface.
         The interface version is equal or less to the client-supported
         version in ei_connection_setup.interface for the "ei_device"
         interface.
@@ -388,30 +478,90 @@
   </interface>
 
   <interface name="ei_device" version="1">
+    <description summary="device object">
+      Note that for a client to receive objects of this type, it must announce
+      support for this interface in ei_connection_setup.interface.
+    </description>
+
+    <!-- ei_device client requests version 1 -->
+
     <request name="release" since="1">
       <description summary="Device removal request">
         Notification that the client is no longer interested in this device.
+
+        Note that releasing a device does not guarantee another device becomes available.
+
         The EIS implementation will release any resources related to this device and
         send the ei_device.destroyed event once complete.
       </description>
     </request>
 
     <request name="start_emulating" since="1">
+      <description summary="Device start emulating request">
+        Notify the EIS implementation that the given device is about to start
+        sending events. This should be seen more as a transactional boundary than a
+        time-based boundary. The primary use-cases for this are to allow for setup on
+        the EIS implementation side and/or UI updates to indicate that a device is
+        sending events now and for out-of-band information to sync with a given event
+        sequence.
+
+        There is no actual requirement that events start immediately once emulation
+        starts and there is no requirement that a client calls ei_device.stop_emulating
+        after the most recent events.
+        For example, in a synergy-like use-case the client would call
+        ei_device.start_emulating once the pointer moves into the the screen and
+        ei_device.stop_emulating once the pointer moves out of the screen.
+
+        The sequence number identifies this transaction between start/stop emulating.
+        It must go up by at least 1 on each call to ei_device.start_emulating.
+        Wraparound must be handled by the EIS implementation but Callers must ensure
+        that detection of wraparound is reasonably.
+
+        It is a protocol violation to request start_emulating after start_emulating without an
+        intermediate stop_emulating.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than sender.
+      </description>
       <arg name="sequence" type="uint"/>
     </request>
 
     <request name="stop_emulating" since="1">
+      <description summary="Device start emulating request">
+        Notify the EIS implementation that the given device is no longer sending
+        events. See ei_device.start_emulating for details.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than sender.
+      </description>
     </request>
 
     <request name="frame" since="1">
-      <arg name="timestamp" type="uint"/>
-      <arg name="micros" type="uint"/>
+      <description summary="Device frame request">
+        Generate a frame event to group the current set of events
+        into a logical hardware event. This function must be called after any
+        other event on any of ei_pointer, ei_keyboard or ei_touchscreen has been generated.
+
+        The given timestamp applies to all events in the current frame.
+        The timestamp must be in microseconds of CLOCK_MONOTONIC.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than sender.
+      </description>
+      <arg name="timestamp" type="uint" help="timestamp in milliseconds"/>
+      <arg name="micros" type="uint" help="microseconds in addition to the millis"/>
     </request>
 
+    <!-- ei_device events version 1 -->
+
     <event name="destroyed" type="destructor" since="1">
       <description summary="Device removal notification">
         This device has been removed and a client should release all
         associated resources.
+
+        This ei_device object will be destroyed by the EIS implementation immmediately after
+        after this event is sent and as such the client must not attempt to use
+        it after that point.
       </description>
     </event>
 
@@ -419,6 +569,8 @@
       <description summary="device name notification">
         The name of this device, if any. This event is optional and sent once immediately
         after object creation.
+
+        It is a protocol violation to send this event after the ei_device.done event.
       </description>
       <arg name="name" type="string" help="the device name"/>
     </event>
@@ -433,11 +585,28 @@
     <event name="capabilities" since="1">
       <description summary="device capability notification">
         A bitmask of the capabilties of this device.
+
+        This event must be is sent once immediately after object creation.
+        It is a protocol violation to send this event after the ei_device.done event.
       </description>
       <arg name="capabilities" type="uint" enum="capabilities" help="the device name"/>
     </event>
 
     <enum name="device_type" since="1">
+      <description summary="device type">
+        If the device type is device_type.virtual, the device is a
+        virtual device representing input as applied on the EIS implementation's
+        screen. A relative virtual device generates input events in logical pixels,
+        an absolute virtual device generates input events in logical pixels on one
+        of the device's regions. Virtual devices do not have a size.
+
+        If the device type is device_type.physical, the device is a
+        representation of a physical device as if connected to the EIS
+        implementation's host computer. A relative physical device generates input
+        events in mm, an absolute physical device generates input events in mm
+        within the device's specified physical size. Physical devices do not have
+        regions and no ei_device.region events are sent for such devices.
+      </description>
       <entry name="virtual" value="1"/>
       <entry name="physical" value="2"/>
     </enum>
@@ -445,37 +614,107 @@
     <event name="type" since="1">
       <description summary="device type notification">
         The device type, one of virtual or physical.
+
+        This event must be is sent once immediately after object creation.
+        It is a protocol violation to send this event after the ei_device.done event.
       </description>
       <arg name="type" type="uint" enum="device_type" help="the device type"/>
     </event>
 
     <event name="dimensions" since="1">
       <description summary="device dimensions notification">
-        The device dimensions  in mm.
+        The device dimensions in mm. This event is optional and sent once immediately
+        after object creation.
+
+        It is a protocol violation to send this event after the ei_device.done event.
       </description>
       <arg name="width" type="uint" help="the device physical width"/>
       <arg name="height" type="uint" help="the device physical height"/>
     </event>
 
     <event name="region" since="1">
-      <arg name="offset_x" type="uint"/>
-      <arg name="offset_y" type="uint"/>
-      <arg name="width" type="uint"/>
-      <arg name="hight" type="uint"/>
-      <arg name="scale" type="float"/>
+      <description summary="device dimensions notification">
+        Notifies the client of one region. The number of regions is constant for a device
+        and all regions are announced immediately after object creation.
+
+        A region is rectangular and defined by an x/y offset and a width and a height.
+        A region defines the area on an EIS desktop layout that is accessible by
+        this device - this region may not be the full area of the desktop.
+        Input events may only be sent for points within the regions.
+
+        The use of regions is private to the EIS compositor and coordinates may not
+        match the size of the actual desktop. For example, a compositor may set a
+        1920x1080 region to represent a 4K monitor and transparently map input
+        events into the respective true pixels.
+
+        Absolute devices may have different regions, it is up to the libei client
+        to send events through the correct device to target the right pixel. For
+        example, a dual-head setup my have two absolute devices, the first with a
+        zero offset region spanning the first screen, the second with a nonzero
+        offset spanning the second screen.
+
+        The physical scale denotes a constant factor that needs to be applied to
+        any relative movement on this region for that movement to match the same
+        *physical* movement on another region.
+
+        This event is optional and sent immediately after object creation. Where a device
+        has multiple regions, this event is sent once for each region.
+        It is a protocol violation to send this event after the ei_device.done event.
+      </description>
+      <arg name="offset_x" type="uint" help="region x offset in logical pixels"/>
+      <arg name="offset_y" type="uint" help="region y offset in logical pixels"/>
+      <arg name="width" type="uint" help="region width in logical pixels"/>
+      <arg name="hight" type="uint" help="region height in logical pixels"/>
+      <arg name="scale" type="float" help="the physical scale for this region"/>
     </event>
 
     <event name="pointer" since="1">
+      <description summary="device pointer interface notification">
+        Notification that a new device has a pointer interface.
+
+        This event is only sent if the client announced support for the
+        "ei_pointer" interface in ei_connection_setup.interface.
+        The interface version is equal or less to the client-supported
+        version in ei_connection_setup.interface for the "ei_pointer"
+        interface.
+
+        This event is optional and sent immediately after object creation.
+        It is a protocol violation to send this event after the ei_device.done event.
+      </description>
       <arg name="pointer" type="new_id" interface="ei_pointer"/>
       <arg name="version" type="uint" summary="the interface version"/>
     </event>
 
     <event name="keyboard" since="1">
+      <description summary="device pointer interface notification">
+        Notification that a new device has a keyboard interface.
+
+        This event is only sent if the client announced support for the
+        "ei_keyboard" interface in ei_connection_setup.interface.
+        The interface version is equal or less to the client-supported
+        version in ei_connection_setup.interface for the "ei_keyboard"
+        interface.
+
+        This event is optional and sent immediately after object creation.
+        It is a protocol violation to send this event after the ei_device.done event.
+      </description>
       <arg name="keyboard" type="new_id" interface="ei_keyboard"/>
       <arg name="version" type="uint" summary="the interface version"/>
     </event>
 
     <event name="touchscreen" since="1">
+      <description summary="device touchscreen interface notification">
+        Notification that a new device has a keyboard interface.
+
+        This event is only sent if the client announced support for the
+        "ei_touchscreen" interface in ei_connection_setup.interface.
+        The interface version is equal or less to the client-supported
+        version in ei_connection_setup.interface for the "ei_touchscreen"
+        interface.
+
+        This event is optional and sent immediately after object creation.
+        It is a protocol violation to send this event after the ei_device.done event.
+      </description>
       <arg name="touchscreen" type="new_id" interface="ei_touchscreen"/>
       <arg name="version" type="uint" summary="the interface version"/>
     </event>
@@ -484,6 +723,8 @@
       <description summary="device setup completion notification">
         Notification that the initial burst of events is complete and
         the client can set up this device now.
+
+        It is a protocol violation to send this event more than once per device.
       </description>
     </event>
 
@@ -494,22 +735,47 @@
     </event>
 
     <event name="start_emulating" since="1">
+      <description summary="Device start emulating event">
+        See the ei_device.start_emulating request for details.
+
+        It is a protocol violation to send this event for a client
+        of an ei_connection_setup.context_type other than receiver.
+      </description>>
       <arg name="sequence" type="uint"/>
     </event>
 
     <event name="stop_emulating" since="1">
+      <description summary="Device stop emulating event">
+        See the ei_device.stop_emulating request for details.
+
+        It is a protocol violation to send this event for a client
+        of an ei_connection_setup.context_type other than receiver.
+      </description>
     </event>
 
     <event name="frame" since="1">
-      <arg name="timestamp" type="uint"/>
-      <arg name="micros" type="uint"/>
+      <description summary="Device frame event">
+        See the ei_device.frame request for details.
+
+        It is a protocol violation to send this event for a client
+        of an ei_connection_setup.context_type other than receiver.
+      </description>
+      <arg name="timestamp" type="uint" help="timestamp in milliseconds"/>
+      <arg name="micros" type="uint" help="microseconds in addition to the millis"/>
     </event>
   </interface>
 
   <interface name="ei_pointer" version="1">
     <description summary="pointer object">
+      Interface for pointer and absolute pointer requests and events. This interface
+      is available on devices with the ei_device.capability pointer or pointer_absolute.
+
+      Note that for a client to receive objects of this type, it must announce
+      support for this interface in ei_connection_setup.interface.
     </description>
 
+    <!-- ei_pointer client requests version 1 -->
+
     <request name="release" since="1">
       <description summary="Pointer removal request">
         Notification that the client is no longer interested in this pointer.
@@ -519,29 +785,82 @@
     </request>
 
     <request name="motion_relative" since="1">
-      <arg name="x" type="float"/>
-      <arg name="y" type="float"/>
+      <description summary="Relative motion request">
+        Generate a relative motion event on this pointer.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than sender.
+      </description>
+      <arg name="x" type="float" help="the x movement in logical pixels"/>
+      <arg name="y" type="float" help="the y movement in logical pixels"/>
     </request>
 
     <request name="motion_absolute" since="1">
-      <arg name="x" type="float"/>
-      <arg name="y" type="float"/>
+      <description summary="Absolute motion request">
+        Generate an absolute motion event on this pointer. The x/y
+        coordinates must be within the device's regions or the event
+        is silently discarded.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than sender.
+      </description>
+      <arg name="x" type="float" help="the x position in logical pixels"/>
+      <arg name="y" type="float" help="the y position in logical pixels"/>
     </request>
 
     <request name="scroll" since="1">
-      <arg name="x" type="float"/>
-      <arg name="y" type="float"/>
+      <description summary="Scroll request">
+        Generate a a smooth (pixel-precise) scroll event on this pointer.
+        Clients must not send ei_pointer.scroll_discrete events for the same event,
+        the EIS implementation is responsible for emulation of discrete
+        scroll events.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than sender.
+      </description>
+      <arg name="x" type="float" help="the x movement in logical pixels"/>
+      <arg name="y" type="float" help="the y movement in logical pixels"/>
     </request>
 
     <request name="scroll_discrete" since="1">
-      <arg name="x" type="int"/>
-      <arg name="y" type="int"/>
+      <description summary="Scroll discrete request">
+        Generate a a discrete (e.g. wheel) scroll event on this pointer.
+        Clients must not send ei_pointer.scroll events for the same event,
+        the EIS implementation is responsible for emulation of smooth
+        scroll events.
+
+        A discrete scroll event is based logical scroll units (equivalent to one
+        mouse wheel click). The value for one scroll unit is 120, a fraction or
+        multiple thereof represents a fraction or multiple of a wheel click.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than sender.
+      </description>
+      <arg name="x" type="int" help="the x movement in fractions or multiple of 120"/>
+      <arg name="y" type="int" help="the y movement in fractions or multiple of 120"/>
     </request>
 
     <request name="scroll_stop" since="1">
-      <arg name="x" type="uint"/>
-      <arg name="y" type="uint"/>
-      <arg name="is_cancel" type="uint"/>
+      <description summary="Scroll stop request">
+        Generate a a scroll stop or cancel event on this pointer.
+
+        A scroll stop event notifies the server that the interaction causing a
+        scroll motion previously triggered with ei_pointer.scroll or
+        ei_pointer.scroll_discrete has stopped. For example, if all
+        fingers are lifted off a touchpad, two-finger scrolling has logically
+        stopped. The server may use this information to e.g. start kinetic scrolling
+        previously based on the previous finger speed.
+
+        If is_cancel is nonzero, the event represents a cancellation of the
+        current interaction. This indicates that the interaction has stopped to the
+        point where further (server-emulated) scroll events from this device are wrong.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than sender.
+      </description>
+      <arg name="x" type="uint" help="nonzero if this axis stopped scrolling"/>
+      <arg name="y" type="uint" help="nonzero if this axis stopped scrolling"/>
+      <arg name="is_cancel" type="uint" help="nonzero to indicate this is a cancel event"/>
     </request>
 
     <enum name="button_state" since="1">
@@ -550,44 +869,94 @@
     </enum>
 
     <request name="button" since="1">
-      <arg name="button" type="uint"/>
+      <description summary="Button state change request">
+        Generate a button event on this pointer.
+
+        The button codes must match the defines in linux/input-event-codes.h.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than sender.
+      </description>
+      <arg name="button" type="uint" help="button code"/>
       <arg name="state" type="uint" enum="button_state"/>
     </request>
 
+    <!-- ei_pointer events version 1 -->
+
     <event name="destroyed" type="destructor" since="1">
       <description summary="Seat removal notification">
         This pointer has been removed and a client should release all
         associated resources.
+
+        This ei_pointer object will be destroyed by the EIS implementation immmediately after
+        after this event is sent and as such the client must not attempt to use
+        it after that point.
       </description>
     </event>
 
     <event name="motion_relative" since="1">
+      <description summary="Relative motion event">
+        See the ei_pointer.motion_relative request for details.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than receiver.
+      </description>
       <arg name="x" type="float"/>
       <arg name="y" type="float"/>
     </event>
 
     <event name="motion_absolute" since="1">
+      <description summary="Absolute motion event">
+        See the ei_pointer.motion_absolute request for details.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than receiver.
+      </description>
       <arg name="x" type="float"/>
       <arg name="y" type="float"/>
     </event>
 
     <event name="scroll" since="1">
+      <description summary="Scroll event">
+        See the ei_pointer.scroll request for details.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than receiver.
+      </description>
       <arg name="x" type="float"/>
       <arg name="y" type="float"/>
     </event>
 
     <event name="scroll_discrete" since="1">
+      <description summary="Discrete scroll event">
+        See the ei_pointer.scroll_discrete request for details.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than receiver.
+      </description>
       <arg name="x" type="int"/>
       <arg name="y" type="int"/>
     </event>
 
     <event name="scroll_stop" since="1">
+      <description summary="Scroll stop event">
+
+        See the ei_pointer.scroll_stop request for details.
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than receiver.
+      </description>
       <arg name="x" type="uint"/>
       <arg name="y" type="uint"/>
       <arg name="is_cancel" type="uint"/>
     </event>
 
     <event name="button" since="1">
+      <description summary="Button state change event">
+        See the ei_pointer.button request for details.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than receiver.
+      </description>
       <arg name="button" type="uint"/>
       <arg name="state" type="uint" enum="button_state"/>
     </event>
@@ -596,8 +965,15 @@
 
   <interface name="ei_keyboard" version="1">
     <description summary="keyboard object">
+      Interface for keyboard requests and events. This interface
+      is available on devices with the ei_device.capability keyboard.
+
+      Note that for a client to receive objects of this type, it must announce
+      support for this interface in ei_connection_setup.interface.
     </description>
 
+    <!-- ei_keyboard client requests version 1 -->
+
     <request name="release" since="1">
       <description summary="keyboard removal request">
         Notification that the client is no longer interested in this keyboard.
@@ -607,10 +983,20 @@
     </request>
 
     <enum name="keymap_type" since="1">
-      <entry name="xkb" value="1" help="an XKB keymap" />
+      <entry name="xkb" value="1" help="a libxkbcommon-compatible XKB keymap" />
     </enum>
 
     <event name="keymap" since="1">
+      <description summary="keymap notification">
+        Notification that this device has a keymap.
+
+        The keymap is constant for the lifetime of the device. Key events on
+        this device correspond to the given keymap.
+
+        This event is sent immediately after the ei_keyboard object is created
+        and before the ei_device.done event. It is a protocol violation to send this
+        event after the ei_device.done event.
+      </description>
       <arg name="type" type="uint" enum="keymap_type" help="the keymap type"/>
       <arg name="size" type="uint" help="the keymap size in bytes"/>
       <arg name="keymap" type="fd" help="file descriptor to the keymap"/>
@@ -622,23 +1008,48 @@
     </enum>
 
     <request name="key" since="1">
+      <description summary="Key state change request">
+        Generate a key event on this keyboard.
+
+        The key codes must match the defines in linux/input-event-codes.h.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than sender.
+      </description>
       <arg name="key" type="uint"/>
       <arg name="state" type="uint" enum="key_state"/>
     </request>
 
+    <!-- ei_keyboard events version 1 -->
+
     <event name="destroyed" type="destructor" since="1">
       <description summary="Seat removal notification">
         This keyboard has been removed and a client should release all
         associated resources.
+
+        This ei_keyboard object will be destroyed by the EIS implementation immmediately after
+        after this event is sent and as such the client must not attempt to use
+        it after that point.
       </description>
     </event>
 
     <event name="key" since="1">
+      <description summary="Key state change event">
+        See the ei_keyboard.key request for details.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than receiver.
+      </description>
       <arg name="key" type="uint"/>
       <arg name="state" type="uint" enum="key_state"/>
     </event>
 
     <event name="modifiers" since="1">
+      <description summary="Modifier change event">
+        Notification that the EIS implementation has changed modifier
+        states on this device. Future ei_keyboard.key requests must take the
+        new modifier state into account.
+      </description>
       <arg name="depressed" type="uint"/>
       <arg name="locked" type="uint"/>
       <arg name="latched" type="uint"/>
@@ -648,8 +1059,15 @@
 
   <interface name="ei_touchscreen" version="1">
     <description summary="touchscreen object">
+      Interface for touchscreen requests and events. This interface
+      is available on devices with the ei_device.capability touchscreen.
+
+      Note that for a client to receive objects of this type, it must announce
+      support for this interface in ei_connection_setup.interface.
     </description>
 
+    <!-- ei_touchscreen client requests version 1 -->
+
     <request name="release" since="1">
       <description summary="touch removal request">
         Notification that the client is no longer interested in this touch.
@@ -663,10 +1081,13 @@
         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.
+
+        The x/y coordinates must be within the device's regions or the event and future
+        ei_touchscreen.motion events with the same touchid are silently discarded.
       </description>
       <arg name="touchid" type="uint"/>
-      <arg name="x" type="float"/>
-      <arg name="y" type="float"/>
+      <arg name="x" type="float" help="touch x coordinate in logical pixels"/>
+      <arg name="y" type="float" help="touch y coordinate in logical pixels"/>
     </request>
 
     <request name="motion" since="1">
@@ -674,10 +1095,13 @@
         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.
+
+        The x/y coordinates must be within the device's regions or the event is
+        silently discarded.
       </description>
       <arg name="touchid" type="uint"/>
-      <arg name="x" type="float"/>
-      <arg name="y" type="float"/>
+      <arg name="x" type="float" help="touch x coordinate in logical pixels"/>
+      <arg name="y" type="float" help="touch y coordinate in logical pixels"/>
     </request>
 
     <request name="up" since="1">
@@ -691,17 +1115,25 @@
       <arg name="touchid" type="uint"/>
     </request>
 
+    <!-- ei_touchscreen events version 1 -->
+
     <event name="destroyed" type="destructor" since="1">
       <description summary="Seat removal notification">
         This touch has been removed and a client should release all
         associated resources.
+
+        This ei_touchscreen object will be destroyed by the EIS implementation immmediately after
+        after this event is sent and as such the client must not attempt to use
+        it after that point.
       </description>
     </event>
 
     <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.
+        See the ei_touchscreen.down request for details.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than receiver.
       </description>
       <arg name="touchid" type="uint"/>
       <arg name="x" type="float"/>
@@ -710,8 +1142,10 @@
 
     <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.
+        See the ei_touchscreen.motion request for details.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than receiver.
       </description>
       <arg name="touchid" type="uint"/>
       <arg name="x" type="float"/>
@@ -720,8 +1154,10 @@
 
     <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.
+        See the ei_touchscreen.up request for details.
+
+        It is a protocol violation to send this request for a client
+        of an ei_connection_setup.context_type other than receiver.
       </description>
       <arg name="touchid" type="uint"/>
     </event>