From 36cee4bdbcaf3a75f567315809953b5e21d703da Mon Sep 17 00:00:00 2001
From: Simon Ser <contact@emersion.fr>
Date: Wed, 2 Jun 2021 20:42:27 +0200
Subject: xdg-activation-v1: clarify set_{serial,surface}

Make it clearer what the requests are used for.

Signed-off-by: Simon Ser <contact@emersion.fr>
---
 staging/xdg-activation/xdg-activation-v1.xml | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/staging/xdg-activation/xdg-activation-v1.xml b/staging/xdg-activation/xdg-activation-v1.xml
index 377d690..df40629 100644
--- a/staging/xdg-activation/xdg-activation-v1.xml
+++ b/staging/xdg-activation/xdg-activation-v1.xml
@@ -120,6 +120,14 @@
         Provides information about the seat and serial event that requested the
         token.
 
+        The serial can come from an input or focus event. For instance, if a
+        click triggers the launch of a third-party client, the launcher client
+        should send a set_serial request with the serial and seat from the
+        wl_pointer.button event.
+
+        Some compositors might refuse to activate toplevels when the token
+        doesn't have a valid and recent enough event serial.
+
         Must be sent before commit. This information is optional.
       </description>
       <arg name="serial" type="uint"
@@ -140,11 +148,14 @@
     </request>
 
     <request name="set_surface">
-      <description summary="specifies the application being activated">
-        The requesting client can specify a surface to associate the token
-        being created with it.
+      <description summary="specifies the surface requesting activation">
+        This request sets the surface requesting the activation. Note, this is
+        different from the surface that will be activated.
+
+        Some compositors might refuse to activate toplevels when the token
+        doesn't have a requesting surface.
 
-        Must be triggered before commit. This information is optional.
+        Must be sent before commit. This information is optional.
       </description>
       <arg name="surface" type="object" interface="wl_surface"
 	   summary="the requesting surface"/>
-- 
cgit v1.2.3