docs: astal3 and io comments

13 files changed, 179 insertions, 8 deletions

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 {