docs: astal-io doc comments

1 files changed, 42 insertions, 2 deletions

diff --git a/lib/astal/io/time.vala b/lib/astal/io/time.vala
index 1446441..29e7e1f 100644
--- a/lib/astal/io/time.vala
+++ b/lib/astal/io/time.vala
@@ -1,10 +1,21 @@
+/**
+ * `Time` provides shortcuts for GLib timeout functions.
+ */
 public class AstalIO.Time : Object {
-    public signal void now ();
-    public signal void cancelled ();
     private Cancellable cancellable;
     private uint timeout_id;
     private bool fulfilled = false;
 
+    /**
+     * Emitted when the timer ticks.
+     */
+    public signal void now ();
+
+    /**
+     * Emitted when the timere is cancelled.
+     */
+    public signal void cancelled ();
+
     construct {
         cancellable = new Cancellable();
         cancellable.cancelled.connect(() => {
@@ -26,6 +37,9 @@ public class AstalIO.Time : Object {
         });
     }
 
+    /**
+     * Start an interval timer with a [[email protected]].
+     */
     public Time.interval_prio(uint interval, int prio = Priority.DEFAULT, Closure? fn) {
         connect_closure(fn);
         Idle.add_once(() => now());
@@ -35,6 +49,9 @@ public class AstalIO.Time : Object {
         }, prio);
     }
 
+    /**
+     * Start a timeout timer with a [[email protected]].
+     */
     public Time.timeout_prio(uint timeout, int prio = Priority.DEFAULT, Closure? fn) {
         connect_closure(fn);
         timeout_id = Timeout.add(timeout, () => {
@@ -44,6 +61,9 @@ public class AstalIO.Time : Object {
         }, prio);
     }
 
+    /**
+     * Start an idle timer with a [[email protected]].
+     */
     public Time.idle_prio(int prio = Priority.DEFAULT_IDLE, Closure? fn) {
         connect_closure(fn);
         timeout_id = Idle.add(() => {
@@ -53,18 +73,38 @@ public class AstalIO.Time : Object {
         }, prio);
     }
 
+    /**
+     * Start an interval timer. Ticks immediately then every `interval` milliseconds.
+     *
+     * @param interval Tick every milliseconds.
+     * @param fn Optional callback.
+     */
     public static Time interval(uint interval, Closure? fn) {
         return new Time.interval_prio(interval, Priority.DEFAULT, fn);
     }
 
+    /**
+     * Start a timeout timer which ticks after `timeout` milliseconds.
+     *
+     * @param timeout Tick after milliseconds.
+     * @param fn Optional callback.
+     */
     public static Time timeout(uint timeout, Closure? fn) {
         return new Time.timeout_prio(timeout, Priority.DEFAULT, fn);
     }
 
+    /**
+     * Start a timer which will tick when there are no higher priority tasks pending.
+     *
+     * @param fn Optional callback.
+     */
     public static Time idle(Closure? fn) {
         return new Time.idle_prio(Priority.DEFAULT_IDLE, fn);
     }
 
+    /**
+     * Cancel timer and emit [[email protected]::cancelled]
+     */
     public void cancel() {
         cancellable.cancel();
     }