docs: astal3 and io comments

25 files changed, 397 insertions, 58 deletions

diff --git a/lib/astal/gtk3/gir.py b/lib/astal/gtk3/gir.py
new file mode 120000
index 0000000..16a3a64
--- /dev/null
+++ b/lib/astal/gtk3/gir.py
@@ -0,0 +1 @@
+../../gir.py
\ No newline at end of file
diff --git a/lib/astal/gtk3/meson.build b/lib/astal/gtk3/meson.build
index b1a0b43..48d3058 100644
--- a/lib/astal/gtk3/meson.build
+++ b/lib/astal/gtk3/meson.build
@@ -13,5 +13,6 @@ project(
 
 libdir = get_option('prefix') / get_option('libdir')
 pkgdatadir = get_option('prefix') / get_option('datadir') / 'astal'
+girpy = files('gir.py')
 
 subdir('src')
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();
diff --git a/lib/astal/gtk3/src/meson.build b/lib/astal/gtk3/src/meson.build
index c8c7df2..bf8f72a 100644
--- a/lib/astal/gtk3/src/meson.build
+++ b/lib/astal/gtk3/src/meson.build
@@ -60,8 +60,7 @@ foreach protocol : protocols
   client_protocol_srcs += [client_header, code]
 endforeach
 
-sources = [
-  config,
+vala_sources = [config] + files(
   'widget/box.vala',
   'widget/button.vala',
   'widget/centerbox.vala',
@@ -77,31 +76,47 @@ sources = [
   'widget/widget.vala',
   'widget/window.vala',
   'application.vala',
-  'idle-inhibit.h',
   'idle-inhibit.c',
-] + client_protocol_srcs
+)
+
+sources = vala_sources + client_protocol_srcs + files(
+  'idle-inhibit.h',
+)
 
 lib = library(
   meson.project_name(),
   sources,
   dependencies: deps,
-  vala_args: ['--pkg', 'AstalInhibitManager'],
+  vala_args: ['--vapi-comments', '--pkg', 'AstalInhibitManager'],
   vala_header: meson.project_name() + '.h',
   vala_vapi: meson.project_name() + '-' + api_version + '.vapi',
-  vala_gir: gir,
   version: meson.project_version(),
   install: true,
-  install_dir: [true, true, true, true],
+  install_dir: [true, true, true],
 )
 
-import('pkgconfig').generate(
-  lib,
-  name: meson.project_name(),
-  filebase: meson.project_name() + '-' + api_version,
-  version: meson.project_version(),
-  subdirs: meson.project_name(),
-  requires: pkgconfig_deps,
-  install_dir: libdir / 'pkgconfig',
+pkgs = []
+foreach dep : pkgconfig_deps
+  pkgs += ['--pkg=' + dep.name()]
+endforeach
+
+gir_tgt = custom_target(
+  gir,
+  command: [
+    find_program('python3'),
+    girpy,
+    meson.project_name(),
+    gir + ':src/' + gir,
+  ]
+  + pkgs
+  + vala_sources
+  + [meson.project_source_root() / 'src' / 'vapi' / 'AstalInhibitManager.vapi'],
+
+  input: sources,
+  depends: lib,
+  output: gir,
+  install: true,
+  install_dir: get_option('datadir') / 'gir-1.0',
 )
 
 custom_target(
@@ -114,7 +129,17 @@ custom_target(
   ],
   input: lib,
   output: typelib,
-  depends: lib,
+  depends: [lib, gir_tgt],
   install: true,
   install_dir: libdir / 'girepository-1.0',
 )
+
+import('pkgconfig').generate(
+  lib,
+  name: meson.project_name(),
+  filebase: meson.project_name() + '-' + api_version,
+  version: meson.project_version(),
+  subdirs: meson.project_name(),
+  requires: pkgconfig_deps,
+  install_dir: libdir / 'pkgconfig',
+)
diff --git a/lib/astal/gtk3/src/vapi/AstalInhibitManager.vapi b/lib/astal/gtk3/src/vapi/AstalInhibitManager.vapi
index 6232a3c..b2b3b34 100644
--- a/lib/astal/gtk3/src/vapi/AstalInhibitManager.vapi
+++ b/lib/astal/gtk3/src/vapi/AstalInhibitManager.vapi
@@ -5,9 +5,8 @@ namespace Astal {
         public static unowned InhibitManager? get_default();
         public Inhibitor inhibit (Gtk.Window window);
     }
-  
+
     [CCode (cheader_filename = "idle-inhibit.h", free_function = "zwp_idle_inhibitor_v1_destroy")]
     [Compact]
-    public class Inhibitor {
-    }
+    public class Inhibitor { }
 }
diff --git a/lib/astal/gtk3/src/widget/box.vala b/lib/astal/gtk3/src/widget/box.vala
index d23a799..d049161 100644
--- a/lib/astal/gtk3/src/widget/box.vala
+++ b/lib/astal/gtk3/src/widget/box.vala
@@ -1,4 +1,7 @@
 public class Astal.Box : Gtk.Box {
+    /**
+     * Corresponds to [[email protected] :orientation].
+     */
     [CCode (notify = false)]
     public bool vertical {
         get { return orientation == Gtk.Orientation.VERTICAL; }
diff --git a/lib/astal/gtk3/src/widget/button.vala b/lib/astal/gtk3/src/widget/button.vala
index bc10577..2d3095a 100644
--- a/lib/astal/gtk3/src/widget/button.vala
+++ b/lib/astal/gtk3/src/widget/button.vala
@@ -1,3 +1,9 @@
+/**
+ * This button has no extra functionality on top if its base [[email protected]] class.
+ *
+ * The purpose of this Button subclass is to have a destructable
+ * struct as the argument in GJS event handlers.
+ */
 public class Astal.Button : Gtk.Button {
     public signal void hover (HoverEvent event);
     public signal void hover_lost (HoverEvent event);
@@ -39,9 +45,9 @@ public enum Astal.MouseButton {
     FORWARD = 5,
 }
 
-// these structs are here because gjs converts every event
-// into a union Gdk.Event, which cannot be destructured
-// and are not as convinent to work with as a struct
+/**
+ * Struct for [[email protected]]
+ */
 public struct Astal.ClickEvent {
     bool release;
     uint time;
@@ -59,6 +65,9 @@ public struct Astal.ClickEvent {
     }
 }
 
+/**
+ * Struct for [[email protected]]
+ */
 public struct Astal.HoverEvent {
     bool lost;
     uint time;
@@ -78,6 +87,9 @@ public struct Astal.HoverEvent {
     }
 }
 
+/**
+ * Struct for [[email protected]]
+ */
 public struct Astal.ScrollEvent {
     uint time;
     double x;
diff --git a/lib/astal/gtk3/src/widget/centerbox.vala b/lib/astal/gtk3/src/widget/centerbox.vala
index 89bf50b..d74a2c4 100644
--- a/lib/astal/gtk3/src/widget/centerbox.vala
+++ b/lib/astal/gtk3/src/widget/centerbox.vala
@@ -1,4 +1,7 @@
 public class Astal.CenterBox : Gtk.Box {
+    /**
+     * Corresponds to [[email protected] :orientation].
+     */
     [CCode (notify = false)]
     public bool vertical {
         get { return orientation == Gtk.Orientation.VERTICAL; }
diff --git a/lib/astal/gtk3/src/widget/circularprogress.vala b/lib/astal/gtk3/src/widget/circularprogress.vala
index dd7c97b..a3ecdf1 100644
--- a/lib/astal/gtk3/src/widget/circularprogress.vala
+++ b/lib/astal/gtk3/src/widget/circularprogress.vala
@@ -1,8 +1,34 @@
+/**
+ * CircularProgress is a subclass of [[email protected]] which provides a circular progress bar
+ * with customizable properties such as starting and ending points,
+ * progress value, and visual features like rounded ends and inversion of progress direction.
+ */
 public class Astal.CircularProgress : Gtk.Bin {
+    /**
+     * The starting point of the progress circle,
+     * where 0 represents 3 o'clock position or 0° degrees and 1 represents 360°.
+     */
     public double start_at { get; set; }
+
+    /**
+     * The cutoff point of the background color of the progress circle.
+     */
     public double end_at { get; set; }
+
+    /**
+     * The value which determines the arc of the drawn foreground color.
+     * Should be a value between 0 and 1.
+     */
     public double value { get; set; }
+
+    /**
+     * Inverts the progress direction, making it draw counterclockwise.
+     */
     public bool inverted { get; set; }
+
+    /**
+     *  Renders rounded ends at both the start and the end of the progress bar.
+     */
     public bool rounded { get; set; }
 
     construct {
diff --git a/lib/astal/gtk3/src/widget/eventbox.vala b/lib/astal/gtk3/src/widget/eventbox.vala
index 611da2a..0b588e9 100644
--- a/lib/astal/gtk3/src/widget/eventbox.vala
+++ b/lib/astal/gtk3/src/widget/eventbox.vala
@@ -1,3 +1,9 @@
+/**
+ * EventBox is a [[email protected]] subclass which is meant to fix an issue with its
+ * [[email protected]::enter_notify_event] and [[email protected]::leave_notify_event] when nesting EventBoxes
+ *
+ * Its css selector is `eventbox`.
+ */
 public class Astal.EventBox : Gtk.EventBox {
     public signal void hover (HoverEvent event);
     public signal void hover_lost (HoverEvent event);
@@ -49,6 +55,9 @@ public class Astal.EventBox : Gtk.EventBox {
     }
 }
 
+/**
+ * Struct for [[email protected]]
+ */
 public struct Astal.MotionEvent {
     uint time;
     double x;
diff --git a/lib/astal/gtk3/src/widget/icon.vala b/lib/astal/gtk3/src/widget/icon.vala
index f2d59a2..9a20359 100644
--- a/lib/astal/gtk3/src/widget/icon.vala
+++ b/lib/astal/gtk3/src/widget/icon.vala
@@ -1,10 +1,20 @@
+/**
+ * [[email protected]] subclass meant to be used only for icons.
+ *
+ * It's size is calculated from `font-size` css property.
+ * Its css selector is `icon`.
+ */
 public class Astal.Icon : Gtk.Image {
     private IconType type = IconType.NAMED;
     private double size { get; set; default = 14; }
 
     public new Gdk.Pixbuf pixbuf { get; set; }
+    public GLib.Icon g_icon { get; set; }
+
+    /**
+     * Either a named icon or a path to a file.
+     */
     public string icon { get; set; default = ""; }
-    public GLib.Icon g_icon {get; set;}
 
     public static Gtk.IconInfo? lookup_icon(string icon) {
         var theme = Gtk.IconTheme.get_default();
diff --git a/lib/astal/gtk3/src/widget/label.vala b/lib/astal/gtk3/src/widget/label.vala
index 4063b6f..899cba9 100644
--- a/lib/astal/gtk3/src/widget/label.vala
+++ b/lib/astal/gtk3/src/widget/label.vala
@@ -1,11 +1,17 @@
 using Pango;
 
 public class Astal.Label : Gtk.Label {
+    /**
+     * Shortcut for setting [[email protected]:ellipsize] to [[email protected]]
+     */
     public bool truncate {
         set { ellipsize = value ? EllipsizeMode.END : EllipsizeMode.NONE; }
         get { return ellipsize == EllipsizeMode.END; }
     }
 
+    /**
+     * Shortcut for setting [[email protected]:justify] to [[email protected]]
+     */
     public new bool justify_fill {
         set { justify = value ? Gtk.Justification.FILL : Gtk.Justification.LEFT; }
         get { return justify == Gtk.Justification.FILL; }
diff --git a/lib/astal/gtk3/src/widget/levelbar.vala b/lib/astal/gtk3/src/widget/levelbar.vala
index 9b61957..3e98afb 100644
--- a/lib/astal/gtk3/src/widget/levelbar.vala
+++ b/lib/astal/gtk3/src/widget/levelbar.vala
@@ -1,4 +1,7 @@
 public class Astal.LevelBar : Gtk.LevelBar {
+    /**
+     * Corresponds to [[email protected] :orientation].
+     */
     [CCode (notify = false)]
     public bool vertical {
         get { return orientation == Gtk.Orientation.VERTICAL; }
diff --git a/lib/astal/gtk3/src/widget/overlay.vala b/lib/astal/gtk3/src/widget/overlay.vala
index 603ee66..ed5f03b 100644
--- a/lib/astal/gtk3/src/widget/overlay.vala
+++ b/lib/astal/gtk3/src/widget/overlay.vala
@@ -1,6 +1,11 @@
 public class Astal.Overlay : Gtk.Overlay {
     public bool pass_through { get; set; }
 
+    /**
+     * First [[email protected]:overlays] element.
+     *
+     * WARNING: setting this value will remove every overlay but the first.
+     */
     public Gtk.Widget? overlay {
         get { return overlays.nth_data(0); }
         set {
@@ -14,6 +19,9 @@ public class Astal.Overlay : Gtk.Overlay {
         }
     }
 
+    /**
+     * Sets the overlays of this Overlay. [[email protected]_overlay].
+     */
     public List<weak Gtk.Widget> overlays {
         owned get { return get_children(); }
         set {
diff --git a/lib/astal/gtk3/src/widget/scrollable.vala b/lib/astal/gtk3/src/widget/scrollable.vala
index 57afb6e..57a440c 100644
--- a/lib/astal/gtk3/src/widget/scrollable.vala
+++ b/lib/astal/gtk3/src/widget/scrollable.vala
@@ -1,3 +1,11 @@
+/**
+ * Subclass of [[email protected]] which has its policy default to
+ * [[email protected]].
+ *
+ * Its css selector is `scrollable`.
+ * Its child getter returns the child of the inner
+ * [[email protected]], instead of the viewport.
+ */
 public class Astal.Scrollable : Gtk.ScrolledWindow {
     private Gtk.PolicyType _hscroll = Gtk.PolicyType.AUTOMATIC;
     private Gtk.PolicyType _vscroll = Gtk.PolicyType.AUTOMATIC;
diff --git a/lib/astal/gtk3/src/widget/slider.vala b/lib/astal/gtk3/src/widget/slider.vala
index 466275b..97cfb69 100644
--- a/lib/astal/gtk3/src/widget/slider.vala
+++ b/lib/astal/gtk3/src/widget/slider.vala
@@ -1,12 +1,20 @@
+/**
+ * Subclass of [[email protected]] which adds a signal and property for the drag state.
+ */
 public class Astal.Slider : Gtk.Scale {
+    /**
+     * Corresponds to [[email protected] :orientation].
+     */
     [CCode (notify = false)]
     public bool vertical {
         get { return orientation == Gtk.Orientation.VERTICAL; }
         set { orientation = value ? Gtk.Orientation.VERTICAL : Gtk.Orientation.HORIZONTAL; }
     }
 
-    // emitted when the user drags the slider
-    public signal void dragged ();
+    /**
+     * Emitted when the user drags the slider or uses keyboard arrows and its value changes.
+     */
+    public signal void dragged();
 
     construct {
         draw_value = false;
@@ -45,23 +53,38 @@ public class Astal.Slider : Gtk.Scale {
         });
     }
 
+    /**
+     * `true` when the user drags the slider or uses keyboard arrows.
+     */
     public bool dragging { get; private set; }
 
+    /**
+     * Value of this slider. Defaults to `0`.
+     */
     public double value {
         get { return adjustment.value; }
         set { if (!dragging) adjustment.value = value; }
     }
 
+    /**
+     * Minimum possible value of this slider. Defaults to `0`.
+     */
     public double min {
         get { return adjustment.lower; }
         set { adjustment.lower = value; }
     }
 
+    /**
+     * Maximum possible value of this slider. Defaults to `1`.
+     */
     public double max {
         get { return adjustment.upper; }
         set { adjustment.upper = value; }
     }
 
+    /**
+     * Size of step increments. Defaults to `0.05`.
+     */
     public double step {
         get { return adjustment.step_increment; }
         set { adjustment.step_increment = value; }
diff --git a/lib/astal/gtk3/src/widget/stack.vala b/lib/astal/gtk3/src/widget/stack.vala
index 02f9959..4e856a6 100644
--- a/lib/astal/gtk3/src/widget/stack.vala
+++ b/lib/astal/gtk3/src/widget/stack.vala
@@ -1,4 +1,12 @@
+/**
+ * Subclass of [[email protected]] that has a children setter which
+ * invokes [[email protected]_named] with the child's [[email protected]:name] property.
+ */
 public class Astal.Stack : Gtk.Stack {
+    /**
+     * Same as [[email protected]:visible-child-name].
+     */
+    [CCode (notify = false)]
     public string shown {
         get { return visible_child_name; }
         set { visible_child_name = value; }
@@ -23,4 +31,10 @@ public class Astal.Stack : Gtk.Stack {
             }
         }
     }
+
+    construct {
+        notify["visible_child_name"].connect(() => {
+            notify_property("shown");
+        });
+    }
 }
diff --git a/lib/astal/gtk3/src/widget/window.vala b/lib/astal/gtk3/src/widget/window.vala
index 2690365..e513242 100644
--- a/lib/astal/gtk3/src/widget/window.vala
+++ b/lib/astal/gtk3/src/widget/window.vala
@@ -10,7 +10,13 @@ public enum Astal.WindowAnchor {
 
 public enum Astal.Exclusivity {
     NORMAL,
+    /**
+     * Request the compositor to allocate space for this window.
+     */
     EXCLUSIVE,
+    /**
+     * Request the compositor to stack layers on top of each other.
+     */
     IGNORE,
 }
 
@@ -22,11 +28,23 @@ public enum Astal.Layer {
 }
 
 public enum Astal.Keymode {
+    /**
+     * Window should not receive keyboard events.
+     */
     NONE = 0, // GtkLayerShell.KeyboardMode.NONE
+    /**
+     * Window should have exclusive focus if it is on the top or overlay layer.
+     */
     EXCLUSIVE = 1, // GtkLayerShell.KeyboardMode.EXCLUSIVE
+    /**
+     * Focus and Unfocues the window as needed.
+     */
     ON_DEMAND = 2, // GtkLayerShell.KeyboardMode.ON_DEMAND
 }
 
+/**
+ * Subclass of [[email protected]] which integrates GtkLayerShell as class fields.
+ */
 public class Astal.Window : Gtk.Window {
     private static bool check(string action) {
         if (!is_supported()) {
@@ -44,12 +62,18 @@ public class Astal.Window : Gtk.Window {
         if (check("initialize layer shell"))
             return;
 
+        // If the window has no size allocatoted when it gets mapped.
+        // It won't show up later either when it size changes by adding children.
         height_request = 1;
         width_request = 1;
+
         init_for_window(this);
         inhibit_manager = InhibitManager.get_default();
     }
 
+    /**
+     * When `true` it will permit inhibiting the idle behavior such as screen blanking, locking, and screensaving.
+     */
     public bool inhibit {
         set {
             if (inhibit_manager == null) {
@@ -74,11 +98,20 @@ public class Astal.Window : Gtk.Window {
         }
     }
 
+    /**
+     * Namespace of this window. This can be used to target the layer in compositor rules.
+     */
     public string namespace {
         get { return get_namespace(this); }
         set { set_namespace(this, value); }
     }
 
+    /**
+     * Edges to anchor the window to.
+     *
+     * If two perpendicular edges are anchored, the surface will be anchored to that corner.
+     * If two opposite edges are anchored, the window will be stretched across the screen in that direction.
+     */
     public int anchor {
         set {
             if (check("set anchor"))
@@ -107,6 +140,9 @@ public class Astal.Window : Gtk.Window {
         }
     }
 
+    /**
+     * Exclusivity of this window.
+     */
     public Exclusivity exclusivity {
         set {
             if (check("set exclusivity"))
@@ -135,6 +171,9 @@ public class Astal.Window : Gtk.Window {
         }
     }
 
+    /**
+     * Which layer to appear this window on.
+     */
     public Layer layer {
         get { return (Layer)get_layer(this); }
         set {
@@ -145,6 +184,9 @@ public class Astal.Window : Gtk.Window {
         }
     }
 
+    /**
+     * Keyboard mode of this window.
+     */
     public Keymode keymode {
         get { return (Keymode)get_keyboard_mode(this); }
         set {
@@ -155,6 +197,9 @@ public class Astal.Window : Gtk.Window {
         }
     }
 
+    /**
+     * Which monitor to appear this window on.
+     */
     public Gdk.Monitor gdkmonitor {
         get { return get_monitor(this); }
         set {
@@ -218,8 +263,9 @@ public class Astal.Window : Gtk.Window {
     }
 
     /**
-     * CAUTION: the id might not be the same mapped by the compositor
-     * to reset and let the compositor map it pass a negative number
+     * Which monitor to appear this window on.
+     *
+     * CAUTION: the id might not be the same mapped by the compositor.
      */
     public int monitor {
         set {
diff --git a/lib/astal/io/application.vala b/lib/astal/io/application.vala
index a420128..c7bd311 100644
--- a/lib/astal/io/application.vala
+++ b/lib/astal/io/application.vala
@@ -21,8 +21,8 @@ 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].
+ * 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;
@@ -186,7 +186,7 @@ public async string read_sock(SocketConnection conn) throws IOError {
  * 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);
+    yield conn.output_stream.write_async(@"$response\x04".data, Priority.DEFAULT);
 }
 
 [DBus (name="io.Astal.Application")]
diff --git a/lib/astal/io/file.vala b/lib/astal/io/file.vala
index e57f449..57b6dc0 100644
--- a/lib/astal/io/file.vala
+++ b/lib/astal/io/file.vala
@@ -48,7 +48,7 @@ public async void write_file_async(string path, string content) throws Error {
 /**
  * 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.
+ * that changed and an [[email protected]] indicating the reason.
  */
 public FileMonitor? monitor_file(string path, Closure callback) {
     try {
diff --git a/lib/astal/io/gir.py b/lib/astal/io/gir.py
new file mode 100644
index 0000000..9ef680f
--- /dev/null
+++ b/lib/astal/io/gir.py
@@ -0,0 +1,58 @@
+"""
+Vala's generated gir does not contain comments,
+so we use valadoc to generate them. However, they are formatted
+for valadoc and not gi-docgen so we need to fix it.
+"""
+
+import xml.etree.ElementTree as ET
+import html
+import sys
+import subprocess
+
+
+def fix_gir(name: str, gir: str, out: str):
+    namespaces = {
+        "": "http://www.gtk.org/introspection/core/1.0",
+        "c": "http://www.gtk.org/introspection/c/1.0",
+        "glib": "http://www.gtk.org/introspection/glib/1.0",
+    }
+    for prefix, uri in namespaces.items():
+        ET.register_namespace(prefix, uri)
+
+    tree = ET.parse(gir)
+    root = tree.getroot()
+
+    for doc in root.findall(".//doc", namespaces):
+        if doc.text:
+            doc.text = (
+                html.unescape(doc.text).replace("<para>", "").replace("</para>", "")
+            )
+
+    if (inc := root.find("c:include", namespaces)) is not None:
+        inc.set("name", f"{name}.h")
+    else:
+        print("no c:include tag found", file=sys.stderr)
+        exit(1)
+
+    tree.write(out, encoding="utf-8", xml_declaration=True)
+
+
+def valadoc(name: str, gir: str, args: list[str]):
+    cmd = ["valadoc", "-o", "docs", "--package-name", name, "--gir", gir, *args]
+    try:
+        subprocess.run(cmd, check=True, text=True, capture_output=True)
+    except subprocess.CalledProcessError as e:
+        print(e.stderr, file=sys.stderr)
+        exit(1)
+
+
+if __name__ == "__main__":
+    name = sys.argv[1]
+    in_out = sys.argv[2].split(":")
+    args = sys.argv[3:]
+
+    gir = in_out[0]
+    out = in_out[1] if len(in_out) > 1 else gir
+
+    valadoc(name, gir, args)
+    fix_gir(name, gir, out)
diff --git a/lib/astal/io/meson.build b/lib/astal/io/meson.build
index 426a6d6..023dece 100644
--- a/lib/astal/io/meson.build
+++ b/lib/astal/io/meson.build
@@ -36,35 +36,41 @@ deps = [
   dependency('gio-2.0'),
 ]
 
-sources = [
-  config,
+sources = [config] + files(
   'application.vala',
   'file.vala',
   'process.vala',
   'time.vala',
   'variable.vala',
-]
+)
 
 lib = library(
   meson.project_name(),
   sources,
   dependencies: deps,
+  vala_args: ['--vapi-comments'],
   vala_header: meson.project_name() + '.h',
   vala_vapi: meson.project_name() + '-' + api_version + '.vapi',
-  vala_gir: gir,
   version: meson.project_version(),
   install: true,
-  install_dir: [true, true, true, true],
+  install_dir: [true, true, true],
 )
 
-import('pkgconfig').generate(
-  lib,
-  name: meson.project_name(),
-  filebase: meson.project_name() + '-' + api_version,
-  version: meson.project_version(),
-  subdirs: meson.project_name(),
-  requires: deps,
-  install_dir: libdir / 'pkgconfig',
+pkgs = []
+foreach dep : deps
+  pkgs += ['--pkg=' + dep.name()]
+endforeach
+
+gir_tgt = custom_target(
+  gir,
+  command: [find_program('python3'), files('gir.py'), meson.project_name(), gir]
+  + pkgs
+  + sources,
+  input: sources,
+  depends: lib,
+  output: gir,
+  install: true,
+  install_dir: get_option('datadir') / 'gir-1.0',
 )
 
 custom_target(
@@ -72,14 +78,24 @@ custom_target(
   command: [
     find_program('g-ir-compiler'),
     '--output', '@OUTPUT@',
-    '--shared-library', libdir / '@PLAINNAME@',
+    '--shared-library', get_option('prefix') / get_option('libdir') / '@PLAINNAME@',
     meson.current_build_dir() / gir,
   ],
   input: lib,
   output: typelib,
-  depends: lib,
+  depends: [lib, gir_tgt],
   install: true,
-  install_dir: libdir / 'girepository-1.0',
+  install_dir: get_option('libdir') / 'girepository-1.0',
+)
+
+import('pkgconfig').generate(
+  lib,
+  name: meson.project_name(),
+  filebase: meson.project_name() + '-' + api_version,
+  version: meson.project_version(),
+  subdirs: meson.project_name(),
+  requires: deps,
+  install_dir: get_option('libdir') / 'pkgconfig',
 )
 
 executable(
diff --git a/lib/astal/io/process.vala b/lib/astal/io/process.vala
index 8767012..cfd05b9 100644
--- a/lib/astal/io/process.vala
+++ b/lib/astal/io/process.vala
@@ -1,5 +1,5 @@
 /**
- * `Process` provides shortcuts for [[email protected]] with sane defaults.
+ * `Process` provides shortcuts for [[email protected]] with sane defaults.
  */
 public class AstalIO.Process : Object {
     private void read_stream(DataInputStream stream, bool err) {
@@ -92,7 +92,7 @@ public class AstalIO.Process : Object {
 
     /**
      * Start a new subprocess with the given command
-     * which is parsed using [[email protected]_argv].
+     * which is parsed using [[email protected]_parse_argv].
      */
     public static Process subprocess(string cmd) throws Error {
         string[] argv;
@@ -125,7 +125,7 @@ public class AstalIO.Process : Object {
 
     /**
      * Execute a command synchronously.
-     * The command is parsed using [[email protected]_argv].
+     * The command is parsed using [[email protected]_parse_argv].
      *
      * @return stdout of the subprocess
      */
@@ -160,7 +160,7 @@ public class AstalIO.Process : Object {
 
     /**
      * Execute a command asynchronously.
-     * The command is parsed using [[email protected]_argv].
+     * The command is parsed using [[email protected]_parse_argv].
      *
      * @return stdout of the subprocess
      */
diff --git a/lib/astal/io/time.vala b/lib/astal/io/time.vala
index 29e7e1f..a799f2b 100644
--- a/lib/astal/io/time.vala
+++ b/lib/astal/io/time.vala
@@ -38,7 +38,7 @@ public class AstalIO.Time : Object {
     }
 
     /**
-     * Start an interval timer with a [[email protected]].
+     * Start an interval timer with default Priority.
      */
     public Time.interval_prio(uint interval, int prio = Priority.DEFAULT, Closure? fn) {
         connect_closure(fn);
@@ -50,7 +50,7 @@ public class AstalIO.Time : Object {
     }
 
     /**
-     * Start a timeout timer with a [[email protected]].
+     * Start a timeout timer with default Priority.
      */
     public Time.timeout_prio(uint timeout, int prio = Priority.DEFAULT, Closure? fn) {
         connect_closure(fn);
@@ -62,7 +62,7 @@ public class AstalIO.Time : Object {
     }
 
     /**
-     * Start an idle timer with a [[email protected]].
+     * Start an idle timer with default priority.
      */
     public Time.idle_prio(int prio = Priority.DEFAULT_IDLE, Closure? fn) {
         connect_closure(fn);
diff --git a/lib/gir.py b/lib/gir.py
index ccfbbc1..9ef680f 100644
--- a/lib/gir.py
+++ b/lib/gir.py
@@ -10,7 +10,7 @@ import sys
 import subprocess
 
 
-def fix_gir(name: str, gir: str):
+def fix_gir(name: str, gir: str, out: str):
     namespaces = {
         "": "http://www.gtk.org/introspection/core/1.0",
         "c": "http://www.gtk.org/introspection/c/1.0",
@@ -34,7 +34,7 @@ def fix_gir(name: str, gir: str):
         print("no c:include tag found", file=sys.stderr)
         exit(1)
 
-    tree.write(gir, encoding="utf-8", xml_declaration=True)
+    tree.write(out, encoding="utf-8", xml_declaration=True)
 
 
 def valadoc(name: str, gir: str, args: list[str]):
@@ -48,8 +48,11 @@ def valadoc(name: str, gir: str, args: list[str]):
 
 if __name__ == "__main__":
     name = sys.argv[1]
-    gir = sys.argv[2]
+    in_out = sys.argv[2].split(":")
     args = sys.argv[3:]
 
+    gir = in_out[0]
+    out = in_out[1] if len(in_out) > 1 else gir
+
     valadoc(name, gir, args)
-    fix_gir(name, gir)
+    fix_gir(name, gir, out)