From 70c3348dfe28d95cd05a07f57f8104d8840b2e90 Mon Sep 17 00:00:00 2001
From: Axel Karjalainen <axel@axka.fi>
Date: Thu, 10 Jul 2025 20:15:34 +0300
Subject: [PATCH] docs: Extend summaries

Part-of: <https://gitlab.freedesktop.org/libinput/libei/-/merge_requests/344>
---
 proto/protocol.xml | 33 +++++++++++++++++----------------
 1 file changed, 17 insertions(+), 16 deletions(-)

diff --git a/proto/protocol.xml b/proto/protocol.xml
index b4484a6..2220121 100644
--- a/proto/protocol.xml
+++ b/proto/protocol.xml
@@ -183,7 +183,7 @@
     </event>
 
     <event name="connection" type="destructor" since="1">
-      <description summary="the core connection object">
+      <description summary="initialization of the connection object">
         Provides the client with the connection object that is the top-level
         object for all future requests and events.
 
@@ -211,7 +211,7 @@
   </interface>
 
   <interface name="ei_connection" version="1">
-    <description summary="core global object">
+    <description summary="core connection object">
       The core connection object. This is the top-level object for any communication
       with the EIS implementation.
 
@@ -420,7 +420,7 @@
   </interface>
 
   <interface name="ei_seat" version="1">
-    <description summary="seat object">
+    <description summary="set of input devices that logically belong together">
       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.
@@ -550,10 +550,10 @@
   </interface>
 
   <interface name="ei_device" version="2">
-    <description summary="device object">
-      An ei_device represents a single logical input devices. Like physical input devices
-      an ei_device may have multiple capabilities and may e.g. function as pointer
-      and keyboard.
+    <description summary="logical input device">
+      An ei_device represents a single logical input device. Like physical input
+      devices an ei_device may have multiple capabilities and may e.g. function
+      as pointer and keyboard.
 
       Depending on the ei_handshake.context_type, an ei_device can
       emulate events via client requests or receive events. It is a protocol violation
@@ -691,8 +691,8 @@
       <description summary="device type notification">
         The device type, one of virtual or physical.
 
-        Devices of type ei_device.device_type.physical are supported only clients of
-        type ei_handshake.context_type.receiver.
+        Devices of type ei_device.device_type.physical are only supported for
+        clients of type ei_handshake.context_type.receiver.
 
         This event is sent once immediately after object creation.
         It is a protocol violation to send this event after the ei_device.done event.
@@ -714,7 +714,7 @@
     </event>
 
     <event name="region" since="1">
-      <description summary="device dimensions notification">
+      <description summary="device region 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.
 
@@ -893,8 +893,9 @@
   </interface>
 
   <interface name="ei_pointer" version="1">
-    <description summary="pointer object">
-      Interface for pointer motion requests and events.
+    <description summary="device sub-interface for relative pointer motion">
+      Interface for relative pointer motion requests and events, originating
+      from physical devices like computer mice.
 
       This interface is only provided once per device and where a client
       requests ei_pointer.release the interface does not get re-initialized. An
@@ -908,7 +909,7 @@
     <!-- ei_pointer client requests version 1 -->
 
     <request name="release" since="1">
-      <description summary="Pointer removal request">
+      <description summary="pointer sub-interface removal request">
         Notification that the client is no longer interested in this pointer.
         The EIS implementation will release any resources related to this pointer and
         send the ei_pointer.destroyed event once complete.
@@ -957,8 +958,8 @@
   </interface>
 
   <interface name="ei_pointer_absolute" version="1">
-    <description summary="absolute pointer object">
-      Interface for absolute pointer requests and events.
+    <description summary="device sub-interface for absolute pointer motion">
+      Interface for absolute pointer motion.
 
       This interface is only provided once per device and where a client
       requests ei_pointer_absolute.release the interface does not get
@@ -972,7 +973,7 @@
     <!-- ei_pointer_absolute client requests version 1 -->
 
     <request name="release" since="1">
-      <description summary="Pointer absolute removal request">
+      <description summary="absolute pointer sub-interface removal request">
         Notification that the client is no longer interested in this object.
         The EIS implementation will release any resources related to this object and
         send the ei_pointer_absolute.destroyed event once complete.