From 6e89992b26bed6376404186441c594a69933227a Mon Sep 17 00:00:00 2001
From: "Anna (navi) Figueiredo Gomes" <navi@vlhl.dev>
Date: Mon, 26 Feb 2024 03:06:36 +0100
Subject: ext-action-binder: update descriptions

Signed-off-by: Anna (navi) Figueiredo Gomes <navi@vlhl.dev>
---
 staging/ext-action-binder/ext-action-binder-v1.xml | 55 +++++++++++++++-------
 1 file changed, 38 insertions(+), 17 deletions(-)

diff --git a/staging/ext-action-binder/ext-action-binder-v1.xml b/staging/ext-action-binder/ext-action-binder-v1.xml
index 1692b84..5a8d513 100644
--- a/staging/ext-action-binder/ext-action-binder-v1.xml
+++ b/staging/ext-action-binder/ext-action-binder-v1.xml
@@ -26,17 +26,19 @@
     THIS SOFTWARE.
   </copyright>
 
+  <description summary="binds actions">
+    This protocol allows clients to register "actions" as a set of triggers
+    and metadata, and get notified when those actions are triggered by the user.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
   <interface name="ext_action_binder_v1" version="1">
     <description summary="action binder">
-      This interface is designed to allow any application to bind
-      an action.
-
-      An action is an arbitrary couple of a namespace and a name describing the
-      wanted behaviour. These two strings are not meant to be user-visible.
-      Some namespaces are well-known and shared by applications while each
-      application can have its own namespaces for internal actions.
-      It is possible to have the same action in several namespaces, e.g. to
-      allow application-specific bindings in addition to global actions.
+      This interface is designed to allow any application to bind an action.
 
       It is left to the compositor to determine which client will get events.
       The choice can be based on policy, heuristic, user configuration, or any
@@ -54,7 +56,12 @@
     </request>
 
     <request name="create_binding">
-      <description summary="create a binding"/>
+      <description summary="create a binding">
+        Creates a binding.
+
+        After setting the metadata on all bindings created, the client must
+        call ext_action_binder_v1.commit for the binding to take effect.
+      </description>
       <arg name="binding" type="new_id" interface="ext_action_binding_v1" summary="the new binding" />
     </request>
 
@@ -77,6 +84,10 @@
   </interface>
 
   <interface name="ext_action_binding_v1" version="1">
+    <description summary="a binding for an action">
+      This interface defines an individual binding, allowing the client to register metadata about
+      the action and receive triggered events.
+    </description>
     <request name="destroy" type="destructor">
       <description summary="unbind the actions">
         The client no longer wants to receive events for this binding.
@@ -85,30 +96,40 @@
 
     <request name="set_name">
       <description summary="sets the namespace:name of a binding">
-        This an action.
-        Sets the namespace:name of the binding.
+        Sets an arbitrary couple of a namespace and a name describing the
+        wanted behaviour. These two strings are not meant to be user-visible.
+        Some namespaces are well-known and shared by applications while each
+        application can have its own namespaces for internal actions.
+        It is possible to have the same action in several namespaces, e.g. to
+        allow application-specific bindings in addition to global actions.
+
+        A name must be set before attempting to commit a binding.
 
-        Attempting to send this request twice or after the binding was bound raises an already set error
+        Attempting to send this request twice or after the binding was bound raises an already set error.
       </description>
       <arg name="namespace" type="string" summary="the action namespace" />
       <arg name="name" type="string" summary="the action name" />
     </request>
 
     <request name="set_description">
-      <description summary="sets the human-readable description of a binding">
+      <description summary="set the human-readable description of a binding">
         This setting is optional.
         This description may be used by the compositor to render a ui for bindings.
 
-        Attempting to send this request twice or after the binding was bound raises an already_set error
+        Attempting to send this request twice or after the binding was bound raises an already_set error.
       </description>
       <arg name="description" type="string" summary="a human-readable description of what the binding does" />
     </request>
 
     <request name="set_app_id">
-      <description summary="sets an app_id for this binding">
+      <description summary="set the application ID">
         This setting is optional.
 
-        Attempting to send this request twice or after the binding was bound raises an already_set error
+        The app ID identifies the general class of applications to which
+        the binding belongs. The compositor can use this to select which
+        client will receive an event.
+
+        Attempting to send this request twice or after the binding was bound raises an already_set error.
       </description>
       <arg name="app_id" type="string" summary="app_id of the application requesting this bind"/>
     </request>
-- 
cgit v1.2.3