From 1b64353427f2b42776c247bae62687c8a4771d0d Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Thu, 23 May 2024 11:35:45 +0100
Subject: [PATCH] dbus-interfaces: Add some docs to the IdleMonitor interface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

They’re not complete, but they’re something.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3768>
---
 .../org.gnome.Mutter.IdleMonitor.xml          | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/data/dbus-interfaces/org.gnome.Mutter.IdleMonitor.xml b/data/dbus-interfaces/org.gnome.Mutter.IdleMonitor.xml
index 374af4dc4..3db76c806 100644
--- a/data/dbus-interfaces/org.gnome.Mutter.IdleMonitor.xml
+++ b/data/dbus-interfaces/org.gnome.Mutter.IdleMonitor.xml
@@ -15,11 +15,39 @@
       <arg name="idletime" direction="out" type="t"/>
     </method>
 
+    <!--
+        AddIdleWatch:
+        @interval: Interval, in milliseconds
+        @id: Watch ID, guaranteed to be greater than zero
+
+        Add a new idle watch for a specific idle time. When the user has been
+        idle for @interval milliseconds in a row, #org.gnome.Mutter.IdleMonitor.WatchFired
+        will be emitted with the returned watch @id.
+
+        The watch will continue emitting the signal every time the
+        idle time condition is reached until it is removed.
+
+        The returned @id can be used to remove the watch by calling
+        #org.gnome.Mutter.IdleMonitor.RemoveWatch.
+    -->
     <method name="AddIdleWatch">
       <arg name="interval" direction="in" type="t" />
       <arg name="id" direction="out" type="u" />
     </method>
 
+    <!--
+        AddUserActiveWatch:
+        @id: Watch ID, guaranteed to be greater than zero
+
+        Add a new active watch. When the user has been idle and becomes
+        active again, #org.gnome.Mutter.IdleMonitor.WatchFired will be
+        emitted with the returned watch @id, and the watch will be removed.
+
+        Unlike idle watches, an active watch is fired only once.
+
+        The returned @id can be used to remove the watch (before it’s fired)
+        by calling #org.gnome.Mutter.IdleMonitor.RemoveWatch.
+    -->
     <method name="AddUserActiveWatch">
       <arg name="id" direction="out" type="u" />
     </method>