docs: astal3 and io comments

1 files changed, 65 insertions, 0 deletions

diff --git a/lib/astal/gtk3/src/application.vala b/lib/astal/gtk3/src/application.vala
index 1210d88..82ee797 100644
--- a/lib/astal/gtk3/src/application.vala
+++ b/lib/astal/gtk3/src/application.vala
@@ -6,15 +6,28 @@ public class Astal.Application : Gtk.Application, AstalIO.Application {
     private string _instance_name = "astal";
     private string socket_path { get; private set; }
 
+    /**
+     * Emitted when a new monitor is added to [[email protected]].
+     */
     [DBus (visible=false)]
     public signal void monitor_added(Gdk.Monitor monitor);
 
+    /**
+     * Emitted when a monitor is disconnected from [[email protected]].
+     */
     [DBus (visible=false)]
     public signal void monitor_removed(Gdk.Monitor monitor);
 
+    /**
+     * Emitted when a window that has been added using
+     * [[email protected]_window] changes its visibility .
+     */
     [DBus (visible=false)]
     public signal void window_toggled(Gtk.Window window);
 
+    /**
+     * Get all monitors from [[email protected]].
+     */
     [DBus (visible=false)]
     public List<weak Gdk.Monitor> monitors {
         owned get {
@@ -30,6 +43,11 @@ public class Astal.Application : Gtk.Application, AstalIO.Application {
         }
     }
 
+    /**
+     * A unique instance name.
+     *
+     * This is the identifier used by the AstalIO package and the CLI.
+     */
     [DBus (visible=false)]
     public string instance_name {
         owned get { return _instance_name; }
@@ -39,6 +57,9 @@ public class Astal.Application : Gtk.Application, AstalIO.Application {
         }
     }
 
+    /**
+     * Windows that has been added to this app using [[email protected]_window].
+     */
     [DBus (visible=false)]
     public List<Gtk.Window> windows {
         get { return get_windows(); }
@@ -52,24 +73,36 @@ public class Astal.Application : Gtk.Application, AstalIO.Application {
         get { return Gdk.Screen.get_default(); }
     }
 
+    /**
+     * Shortcut for [[email protected]:gtk_theme_name]
+     */
     [DBus (visible=false)]
     public string gtk_theme {
         owned get { return settings.gtk_theme_name; }
         set { settings.gtk_theme_name = value; }
     }
 
+    /**
+     * Shortcut for [[email protected]:gtk_icon_theme_name]
+     */
     [DBus (visible=false)]
     public string icon_theme {
         owned get { return settings.gtk_icon_theme_name; }
         set { settings.gtk_icon_theme_name = value; }
     }
 
+    /**
+     * Shortcut for [[email protected]:gtk_cursor_theme_name]
+     */
     [DBus (visible=false)]
     public string cursor_theme {
         owned get { return settings.gtk_cursor_theme_name; }
         set { settings.gtk_cursor_theme_name = value; }
     }
 
+    /**
+     * Remove all [[email protected]] providers.
+     */
     [DBus (visible=false)]
     public void reset_css() {
         foreach(var provider in css_providers) {
@@ -78,10 +111,17 @@ public class Astal.Application : Gtk.Application, AstalIO.Application {
         css_providers = new List<Gtk.CssProvider>();
     }
 
+    /**
+     * Shortcut for [[email protected]_interactive_debugging].
+     */
     public void inspector() throws DBusError, IOError {
         Gtk.Window.set_interactive_debugging(true);
     }
 
+    /**
+     * Get a window by its [[email protected]:name] that has been added to this app
+     * using [[email protected]_window].
+     */
     [DBus (visible=false)]
     public Gtk.Window? get_window(string name) {
         foreach(var win in windows) {
@@ -93,6 +133,10 @@ public class Astal.Application : Gtk.Application, AstalIO.Application {
         return null;
     }
 
+    /**
+     * Toggle the visibility of a window by its [[email protected]:name]
+     * that has been added to this app using [[email protected]_window].
+     */
     public void toggle_window(string window) throws Error {
         var win = get_window(window);
         if (win != null) {
@@ -102,6 +146,11 @@ public class Astal.Application : Gtk.Application, AstalIO.Application {
         }
     }
 
+    /**
+     * Add a new [[email protected]] provider.
+     *
+     * @param style Css string or a path to a css file.
+     */
     [DBus (visible=false)]
     public void apply_css(string style, bool reset = false) {
         var provider = new Gtk.CssProvider();
@@ -124,6 +173,9 @@ public class Astal.Application : Gtk.Application, AstalIO.Application {
         css_providers.append(provider);
     }
 
+    /**
+     * Shortcut for [[email protected]_search_path].
+     */
     [DBus (visible=false)]
     public void add_icons(string? path) {
         if (path != null) {
@@ -131,11 +183,21 @@ public class Astal.Application : Gtk.Application, AstalIO.Application {
         }
     }
 
+    /**
+     * Handler for an incoming request.
+     *
+     * @param msg Body of the message
+     * @param conn The connection which expects the response.
+     */
     [DBus (visible=false)]
     public virtual void request(string msg, SocketConnection conn) {
         AstalIO.write_sock.begin(conn, @"missing response implementation on $application_id");
     }
 
+    /**
+     * Attempt to acquire the astal socket for this app identified by its [[email protected]:instance_name].
+     * If the socket is in use by another app with the same name an [[email protected]_OCCUPIED] is thrown.
+     */
     [DBus (visible=false)]
     public void acquire_socket() throws Error {
         string path;
@@ -159,6 +221,9 @@ public class Astal.Application : Gtk.Application, AstalIO.Application {
         );
     }
 
+    /**
+     * Quit and stop the socket if it was acquired.
+     */
     public new void quit() throws DBusError, IOError {
         if (service != null) {
             service.stop();