docs: astal-io doc comments

6 files changed, 170 insertions, 22 deletions

diff --git a/lib/astal/io/application.vala b/lib/astal/io/application.vala
index b32de34..60a7d3e 100644
--- a/lib/astal/io/application.vala
+++ b/lib/astal/io/application.vala
@@ -4,6 +4,10 @@ public errordomain AppError {
     TAKEOVER_FAILED,
 }
 
+/**
+ * This interface is used as a placeholder for the Astal Application class.
+ * It is not meant to be used by consumers.
+ */
 public interface Application : Object {
     public abstract void quit() throws Error;
     public abstract void inspector() throws Error;
@@ -16,6 +20,10 @@ public interface Application : Object {
     }
 }
 
+/**
+ * Starts a [[email protected]] and binds `XDG_RUNTIME_DIR/astal/<instance_name>.sock`.
+ * This socket is then used by the astal cli. Not meant for public usage, but for [[email protected]_socket].
+ */
 public SocketService acquire_socket(Application app, out string sock) throws Error {
     var name = app.instance_name;
     foreach (var instance in get_instances()) {
@@ -65,6 +73,10 @@ public SocketService acquire_socket(Application app, out string sock) throws Err
     return service;
 }
 
+/**
+ * Get a list of running Astal.Application instances.
+ * It is the equivalent of `astal --list`.
+ */
 public static List<string> get_instances() {
     var list = new List<string>();
     var prefix = "io.Astal.";
@@ -87,6 +99,10 @@ public static List<string> get_instances() {
     return list;
 }
 
+/**
+ * Quit an an Astal instances.
+ * It is the equivalent of `astal --quit -i instance`.
+ */
 public static void quit_instance(string instance) {
     try {
         IApplication proxy = Bus.get_proxy_sync(
@@ -101,6 +117,10 @@ public static void quit_instance(string instance) {
     }
 }
 
+/**
+ * Open the Gtk debug tool of an an Astal instances.
+ * It is the equivalent of `astal --inspector -i instance`.
+ */
 public static void open_inspector(string instance) {
     try {
         IApplication proxy = Bus.get_proxy_sync(
@@ -115,6 +135,10 @@ public static void open_inspector(string instance) {
     }
 }
 
+/**
+ * Toggle a Window of an Astal instances.
+ * It is the equivalent of `astal -i instance --toggle window`.
+ */
 public static void toggle_window_by_name(string instance, string window) {
     try {
         IApplication proxy = Bus.get_proxy_sync(
@@ -129,7 +153,11 @@ public static void toggle_window_by_name(string instance, string window) {
     }
 }
 
-public static string send_message(string instance_name, string msg) {
+/**
+ * Send a message to an Astal instances.
+ * It is the equivalent of `astal -i instance content of the message`.
+ */
+public static string send_message(string instance, string msg) {
     var rundir = Environment.get_user_runtime_dir();
     var socket_path = @"$rundir/astal/$instance_name.sock";
     var client = new SocketClient();
@@ -146,11 +174,17 @@ public static string send_message(string instance_name, string msg) {
     }
 }
 
+/**
+ * Read the socket of an Astal.Application instance.
+ */
 public async string read_sock(SocketConnection conn) throws IOError {
     var stream = new DataInputStream(conn.input_stream);
     return yield stream.read_upto_async("\x04", -1, Priority.DEFAULT, null, null);
 }
 
+/**
+ * Write the socket of an Astal.Application instance.
+ */
 public async void write_sock(SocketConnection conn, string response) throws IOError  {
     yield conn.output_stream.write_async(response.concat("\x04").data, Priority.DEFAULT);
 }
diff --git a/lib/astal/io/cli.vala b/lib/astal/io/cli.vala
index 1db0b2e..8fc0523 100644
--- a/lib/astal/io/cli.vala
+++ b/lib/astal/io/cli.vala
@@ -1,12 +1,12 @@
-private static bool version;
-private static bool help;
-private static bool list;
-private static bool quit;
-private static bool inspector;
-private static string? toggle_window;
-private static string? instance_name;
+static bool version;
+static bool help;
+static bool list;
+static bool quit;
+static bool inspector;
+static string? toggle_window;
+static string? instance_name;
 
-private const OptionEntry[] options = {
+const OptionEntry[] options = {
     { "version", 'v', OptionFlags.NONE, OptionArg.NONE, ref version, null, null },
     { "help", 'h', OptionFlags.NONE, OptionArg.NONE, ref help, null, null },
     { "list", 'l', OptionFlags.NONE, OptionArg.NONE, ref list, null, null },
diff --git a/lib/astal/io/file.vala b/lib/astal/io/file.vala
index b2d480c..e57f449 100644
--- a/lib/astal/io/file.vala
+++ b/lib/astal/io/file.vala
@@ -1,4 +1,7 @@
 namespace AstalIO {
+/**
+ * Read the contents of a file synchronously.
+ */
 public string read_file(string path) {
     var str = "";
     try {
@@ -9,12 +12,18 @@ public string read_file(string path) {
     return str;
 }
 
+/**
+ * Read the contents of a file asynchronously.
+ */
 public async string read_file_async(string path) throws Error {
     uint8[] content;
     yield File.new_for_path(path).load_contents_async(null, out content, null);
     return (string)content;
 }
 
+/**
+ * Write content to a file synchronously.
+ */
 public void write_file(string path, string content) {
     try {
         FileUtils.set_contents(path, content);
@@ -23,6 +32,9 @@ public void write_file(string path, string content) {
     }
 }
 
+/**
+ * Write content to a file asynchronously.
+ */
 public async void write_file_async(string path, string content) throws Error {
     yield File.new_for_path(path).replace_contents_async(
         content.data,
@@ -33,6 +45,11 @@ public async void write_file_async(string path, string content) throws Error {
         null);
 }
 
+/**
+ * Monitor a file for changes. If the path is a directory, monitor it recursively.
+ * The callback will be called passed two parameters: the path of the file
+ * that changed and an [[email protected]] indicating the reason.
+ */
 public FileMonitor? monitor_file(string path, Closure callback) {
     try {
         var file = File.new_for_path(path);
diff --git a/lib/astal/io/process.vala b/lib/astal/io/process.vala
index e8637ab..8767012 100644
--- a/lib/astal/io/process.vala
+++ b/lib/astal/io/process.vala
@@ -1,3 +1,6 @@
+/**
+ * `Process` provides shortcuts for [[email protected]] with sane defaults.
+ */
 public class AstalIO.Process : Object {
     private void read_stream(DataInputStream stream, bool err) {
         stream.read_line_utf8_async.begin(Priority.DEFAULT, null, (_, res) => {
@@ -23,34 +26,56 @@ public class AstalIO.Process : Object {
     private Subprocess process;
     public string[] argv { construct; get; }
 
+
+    /**
+     * When the underlying subprocess writes to its stdout
+     * this signal is emitted with that line.
+     */
     public signal void stdout (string out);
+
+    /**
+     * When the underlying subprocess writes to its stderr
+     * this signal is emitted with that line.
+     */
     public signal void stderr (string err);
 
+    /**
+     * Force quit the subprocess.
+     */
     public void kill() {
         process.force_exit();
     }
 
+    /**
+     * Send a signal to the subprocess.
+     */
     public void signal(int signal_num) {
         process.send_signal(signal_num);
     }
 
+    /**
+     * Write a line to the subprocess' stdin synchronously.
+     */
     public void write(string in) throws Error {
         in_stream.put_string(in);
     }
 
-    public void write_async(string in) {
-        in_stream.write_all_async.begin(
-            in.data,
-            Priority.DEFAULT, null, (_, res) => {
-                try {
-                    in_stream.write_all_async.end(res, null);
-                } catch (Error err) {
-                    printerr("%s\n", err.message);
-                }
-            }
-        );
+    /**
+     * Write a line to the subprocess' stdin asynchronously.
+     */
+    public async void write_async(string in) {
+        try {
+            yield in_stream.write_all_async(in.data, in.data.length, null, null);
+        } catch (Error err) {
+            printerr("%s\n", err.message);
+        }
     }
 
+    /**
+     * Start a new subprocess with the given command.
+     *
+     * The first element of the vector is executed with the remaining elements as the argument list.
+     */
     public Process.subprocessv(string[] cmd) throws Error {
         Object(argv: cmd);
         process = new Subprocess.newv(cmd,
@@ -65,12 +90,22 @@ public class AstalIO.Process : Object {
         read_stream(err_stream, false);
     }
 
+    /**
+     * Start a new subprocess with the given command
+     * which is parsed using [[email protected]_argv].
+     */
     public static Process subprocess(string cmd) throws Error {
         string[] argv;
         Shell.parse_argv(cmd, out argv);
         return new Process.subprocessv(argv);
     }
 
+    /**
+     * Execute a command synchronously.
+     * The first element of the vector is executed with the remaining elements as the argument list.
+     *
+     * @return stdout of the subprocess
+     */
     public static string execv(string[] cmd) throws Error {
         var process = new Subprocess.newv(
             cmd,
@@ -88,12 +123,24 @@ public class AstalIO.Process : Object {
             throw new IOError.FAILED(err_str.strip());
     }
 
+    /**
+     * Execute a command synchronously.
+     * The command is parsed using [[email protected]_argv].
+     *
+     * @return stdout of the subprocess
+     */
     public static string exec(string cmd) throws Error {
         string[] argv;
         Shell.parse_argv(cmd, out argv);
         return Process.execv(argv);
     }
 
+    /**
+     * Execute a command asynchronously.
+     * The first element of the vector is executed with the remaining elements as the argument list.
+     *
+     * @return stdout of the subprocess
+     */
     public static async string exec_asyncv(string[] cmd) throws Error {
         var process = new Subprocess.newv(
             cmd,
@@ -111,6 +158,12 @@ public class AstalIO.Process : Object {
             throw new IOError.FAILED(err_str.strip());
     }
 
+    /**
+     * Execute a command asynchronously.
+     * The command is parsed using [[email protected]_argv].
+     *
+     * @return stdout of the subprocess
+     */
     public static async string exec_async(string cmd) throws Error {
         string[] argv;
         Shell.parse_argv(cmd, out argv);
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();
     }
diff --git a/lib/astal/io/variable.vala b/lib/astal/io/variable.vala
index 2a395b4..312a27a 100644
--- a/lib/astal/io/variable.vala
+++ b/lib/astal/io/variable.vala
@@ -1,3 +1,7 @@
+/*
+ * Base class for [[email protected]] mainly meant to be used
+ * in higher level language bindings such as Lua and Gjs.
+ */
 public class AstalIO.VariableBase : Object {
     public signal void changed ();
     public signal void dropped ();