docs: battery doc comments

7 files changed, 290 insertions, 65 deletions

diff --git a/lib/apps/application.vala b/lib/apps/application.vala
index c137183..0a2f73c 100644
--- a/lib/apps/application.vala
+++ b/lib/apps/application.vala
@@ -25,8 +25,8 @@ public class AstalApps.Application : Object {
     public string description { get { return app.get_description(); } }
 
     /**
-     * The StartupWMClass field from the desktop file.
-     * This represents the WM_CLASS property of the main window of the application.
+     * `StartupWMClass` field from the desktop file.
+     * This represents the `WM_CLASS` property of the main window of the application.
      */
     public string wm_class { get { return app.get_startup_wm_class(); } }
 
diff --git a/lib/battery/device.vala b/lib/battery/device.vala
index a39d789..db69574 100644
--- a/lib/battery/device.vala
+++ b/lib/battery/device.vala
@@ -1,70 +1,250 @@
 namespace AstalBattery {
-public Device get_default() {
-    return Device.get_default();
+    /** Get the DisplayDevice. */
+    public Device get_default() {
+        return Device.get_default();
+    }
 }
 
-public class Device : Object {
+/**
+ * Client for a UPower [[https://upower.freedesktop.org/docs/Device.html|device]].
+ */
+public class AstalBattery.Device : Object {
     private static Device display_device;
+
+    /** Get the DisplayDevice. */
     public static Device? get_default() {
-        if (display_device != null)
+        if (display_device != null) {
             return display_device;
+        }
 
         try {
-            display_device = new Device("/org/freedesktop/UPower/devices/DisplayDevice");
-
+            display_device = new Device((ObjectPath)"/org/freedesktop/UPower/devices/DisplayDevice");
             return display_device;
         } catch (Error error) {
             critical(error.message);
         }
+
         return null;
     }
 
     private IUPowerDevice proxy;
 
-    public Device(string path) throws Error {
+    public Device(ObjectPath path) throws Error {
         proxy = Bus.get_proxy_sync(BusType.SYSTEM, "org.freedesktop.UPower", path);
         proxy.g_properties_changed.connect(sync);
         sync();
     }
 
+    /**
+     * If it is [[email protected]], you will need to verify that the
+     * property power-supply has the value `true` before considering it as a laptop battery.
+     * Otherwise it will likely be the battery for a device of an unknown type.
+     */
     public Type device_type { get; private set; }
+
+    /**
+     * Native path of the power source. This is the sysfs path,
+     * for example /sys/devices/LNXSYSTM:00/device:00/PNP0C0A:00/power_supply/BAT0.
+     * It is blank if the device is being driven by a user space driver.
+     */
     public string native_path { owned get; private set; }
+
+    /** Name of the vendor of the battery. */
     public string vendor { owned get; private set; }
+
+    /** Name of the model of this battery. */
     public string model { owned get; private set; }
+
+    /** Unique serial number of the battery. */
     public string serial { owned get; private set; }
+
+    /**
+     * The point in time (seconds since the Epoch)
+     * that data was read from the power source.
+     */
     public uint64 update_time { get; private set; }
+
+    /**
+     * If the power device is used to supply the system.
+     * This would be set `true` for laptop batteries and UPS devices,
+     * but set to `false` for wireless mice or PDAs.
+     */
     public bool power_supply { get; private set; }
-    public bool has_history { get; private set; }
-    public bool has_statistics { get; private set; }
+
+    /** If the power device has history. */
+    // TODO: public bool has_history { get; private set; }
+
+    /** If the power device has statistics. */
+    // TODO: public bool has_statistics { get; private set; }
+
+    /**
+     * Whether power is currently being provided through line power.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]_POWER].
+     */
     public bool online { get; private set; }
+
+    /**
+     * Amount of energy (measured in Wh) currently available in the power source.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public double energy { get; private set; }
+
+    /**
+     * Amount of energy (measured in Wh) in the power source when it's considered to be empty.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public double energy_empty { get; private set; }
+
+    /**
+     * Amount of energy (measured in Wh) in the power source when it's considered full.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public double energy_full { get; private set; }
+
+    /**
+     * Amount of energy (measured in Wh) the power source is designed to hold when it's considered full.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public double energy_full_design { get; private set; }
+
+    /**
+     * Amount of energy being drained from the source, measured in W.
+     * If positive, the source is being discharged, if negative it's being charged.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public double energy_rate { get; private set; }
+
+    /** Voltage in the Cell or being recorded by the meter. */
     public double voltage { get; private set; }
+
+    /**
+     * The number of charge cycles as defined by the TCO certification,
+     * or -1 if that value is unknown or not applicable.
+     */
     public int charge_cycles { get; private set; }
+
+    /** Luminosity being recorded by the meter. */
     public double luminosity { get; private set; }
+
+    /**
+     * Number of seconds until the power source is considered empty. Is set to 0 if unknown.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public int64 time_to_empty { get; private set; }
+
+    /**
+     * Number of seconds until the power source is considered full. Is set to 0 if unknown.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public int64 time_to_full { get; private set;}
+
+    /**
+     * The amount of energy left in the power source expressed as a percentage between 0 and 1.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     * The percentage will be an approximation if [[email protected]:battery_level]
+     * is set to something other than None.
+     */
     public double percentage { get; private set; }
+
+    /**
+     * The temperature of the device in degrees Celsius.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public double temperature { get; private set; }
+
+    /**
+     * If the power source is present in the bay.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public bool is_present { get; private set; }
+
+    /**
+     * The battery power state.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public State state { get; private set; }
+
+    /**
+     * If the power source is rechargeable.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public bool is_rechargable { get; private set; }
+
+    /**
+     * The capacity of the power source expressed as a percentage between 0 and 1.
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public double capacity { get; private set; }
+
+    /**
+     * Technology used in the battery:
+     *
+     * This property is only valid if [[email protected]:device_type] is [[email protected]].
+     */
     public Technology technology { get; private set; }
+
+    /** Warning level of the battery. */
     public WarningLevel warning_level { get; private set; }
+
+    /**
+     * The level of the battery for devices which do not report a percentage
+     * but rather a coarse battery level. If the value is None.
+     * then the device does not support coarse battery reporting,
+     * and the [[email protected]:percentage] should be used instead.
+     */
     public BatteryLevel battery_level { get; private set; }
+
+    /**
+     * An icon name representing this Device.
+     *
+     * NOTE: [[email protected]:battery_icon_name] might be a better fit
+     * as it is calculated from percentage.
+     */
     public string icon_name { owned get; private set; }
 
+    /**
+     * Indicates if [[email protected]:state] is charging or fully charged.
+     */
     public bool charging { get; private set; }
+
+    /**
+     * Indicates if [[email protected]:device_type] is not line power or unknown.
+     */
     public bool is_battery { get; private set; }
+
+    /**
+     * An icon name in the form of "battery-level-$percentage-$state-symbolic".
+     */
     public string battery_icon_name { get; private set; }
+
+    /**
+     * A string representation of this device's [[email protected]:device_type].
+     */
     public string device_type_name { get; private set; }
+
+    /**
+     * An icon name that can be used to represent this device's [[email protected]:device_type].
+     */
     public string device_type_icon { get; private set; }
 
-    public void sync() {
+    // TODO: get_history
+    // TODO: get_statistics
+
+    private void sync() {
         device_type = (Type)proxy.Type;
         native_path = proxy.native_path;
         vendor = proxy.vendor;
@@ -72,8 +252,8 @@ public class Device : Object {
         serial = proxy.serial;
         update_time = proxy.update_time;
         power_supply = proxy.power_supply;
-        has_history = proxy.has_history;
-        has_statistics = proxy.has_statistics;
+        // TODO: has_history = proxy.has_history;
+        // TODO: has_statistics = proxy.has_statistics;
         online = proxy.online;
         energy = proxy.energy;
         energy_empty = proxy.energy_empty;
@@ -90,7 +270,7 @@ public class Device : Object {
         is_present = proxy.is_present;
         state = (State)proxy.state;
         is_rechargable = proxy.is_rechargable;
-        capacity = proxy.capacity;
+        capacity = proxy.capacity / 100;
         technology = (Technology)proxy.technology;
         warning_level = (WarningLevel)proxy.warning_level;
         battery_level = (BatteryLevel)proxy.battery_level;
@@ -115,7 +295,7 @@ public class Device : Object {
 }
 
 [CCode (type_signature = "u")]
-public enum State {
+public enum AstalBattery.State {
     UNKNOWN,
     CHARGING,
     DISCHARGING,
@@ -126,7 +306,7 @@ public enum State {
 }
 
 [CCode (type_signature = "u")]
-public enum Technology {
+public enum AstalBattery.Technology {
     UNKNOWN,
     LITHIUM_ION,
     LITHIUM_POLYMER,
@@ -137,7 +317,7 @@ public enum Technology {
 }
 
 [CCode (type_signature = "u")]
-public enum WarningLevel {
+public enum AstalBattery.WarningLevel {
     UNKNOWN,
     NONE,
     DISCHARGING,
@@ -147,7 +327,7 @@ public enum WarningLevel {
 }
 
 [CCode (type_signature = "u")]
-public enum BatteryLevel {
+public enum AstalBattery.BatteryLevel {
     UNKNOWN,
     NONE,
     LOW,
@@ -158,7 +338,7 @@ public enum BatteryLevel {
 }
 
 [CCode (type_signature = "u")]
-public enum Type {
+public enum AstalBattery.Type {
     UNKNOWN,
     LINE_POWER,
     BATTERY,
@@ -190,7 +370,7 @@ public enum Type {
     BLUETOOTH_GENERIC;
 
     // TODO: add more icon names
-    public string? get_icon_name () {
+    internal string? get_icon_name () {
         switch (this) {
             case UPS:
                 return "uninterruptible-power-supply";
@@ -213,7 +393,7 @@ public enum Type {
         }
     }
 
-    public unowned string? get_name () {
+    internal unowned string? get_name () {
         switch (this) {
             case LINE_POWER:
                 return "Plugged In";
@@ -276,4 +456,3 @@ public enum Type {
         }
     }
 }
-}
diff --git a/lib/battery/gir.py b/lib/battery/gir.py
new file mode 120000
index 0000000..b5b4f1d
--- /dev/null
+++ b/lib/battery/gir.py
@@ -0,0 +1 @@
+../gir.py
\ No newline at end of file
diff --git a/lib/battery/ifaces.vala b/lib/battery/ifaces.vala
index e6eb849..e2d21fe 100644
--- a/lib/battery/ifaces.vala
+++ b/lib/battery/ifaces.vala
@@ -1,12 +1,11 @@
-namespace AstalBattery {
 [DBus (name = "org.freedesktop.UPower")]
-interface IUPower : DBusProxy {
-    public abstract string[] enumerate_devices() throws Error;
-    public abstract string get_display_device() throws Error;
+private interface AstalBattery.IUPower : DBusProxy {
+    public abstract ObjectPath[] enumerate_devices() throws Error;
+    public abstract ObjectPath get_display_device() throws Error;
     public abstract string get_critical_action() throws Error;
 
-    public signal void device_added(string object_path);
-    public signal void device_removed(string object_path);
+    public signal void device_added(ObjectPath object_path);
+    public signal void device_removed(ObjectPath object_path);
 
     public abstract string daemon_version { owned get; }
     public abstract bool on_battery { get; }
@@ -15,10 +14,10 @@ interface IUPower : DBusProxy {
 }
 
 [DBus (name = "org.freedesktop.UPower.Device")]
-public interface IUPowerDevice : DBusProxy {
-    public abstract HistoryDataPoint[] get_history (string type, uint32 timespan, uint32 resolution) throws GLib.Error;
-    public abstract StatisticsDataPoint[] get_statistics (string type) throws GLib.Error;
-    public abstract void refresh () throws GLib.Error;
+private interface AstalBattery.IUPowerDevice : DBusProxy {
+    // public abstract HistoryDataPoint[] get_history (string type, uint32 timespan, uint32 resolution) throws GLib.Error;
+    // public abstract StatisticsDataPoint[] get_statistics (string type) throws GLib.Error;
+    // public abstract void refresh () throws GLib.Error;
 
     public abstract uint Type { get; }
     public abstract string native_path { owned get; }
@@ -52,14 +51,13 @@ public interface IUPowerDevice : DBusProxy {
     public abstract string icon_name { owned get; }
 }
 
-public struct HistoryDataPoint {
-    uint32 time;
-    double value;
-    uint32 state;
-}
-
-public struct StatisticsDataPoint {
-    double value;
-    double accuracy;
-}
-}
+// private struct AstalBattery.HistoryDataPoint {
+//     uint32 time;
+//     double value;
+//     uint32 state;
+// }
+// 
+// private struct AstalBattery.StatisticsDataPoint {
+//     double value;
+//     double accuracy;
+// }
diff --git a/lib/battery/meson.build b/lib/battery/meson.build
index 584f66d..054e9db 100644
--- a/lib/battery/meson.build
+++ b/lib/battery/meson.build
@@ -41,34 +41,40 @@ pkgconfig_deps = [
 
 deps = pkgconfig_deps + meson.get_compiler('c').find_library('m')
 
-sources = [
-  config,
-  'ifaces.vala',
+sources = [config] + files(
   'device.vala',
+  'ifaces.vala',
   'upower.vala',
-]
+)
 
 if get_option('lib')
   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: pkgconfig_deps,
-    install_dir: get_option('libdir') / 'pkgconfig',
+  pkgs = []
+  foreach dep : pkgconfig_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(
@@ -81,10 +87,20 @@ if get_option('lib')
     ],
     input: lib,
     output: typelib,
-    depends: lib,
+    depends: [lib, gir_tgt],
     install: true,
     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: pkgconfig_deps,
+    install_dir: get_option('libdir') / 'pkgconfig',
+  )
 endif
 
 if get_option('cli')
diff --git a/lib/battery/upower.vala b/lib/battery/upower.vala
index 9c18ffd..223633e 100644
--- a/lib/battery/upower.vala
+++ b/lib/battery/upower.vala
@@ -1,23 +1,40 @@
-namespace AstalBattery {
-public class UPower : Object {
+/**
+ * Client for the UPower [[https://upower.freedesktop.org/docs/UPower.html|dbus interface]].
+ */
+public class AstalBattery.UPower : Object {
     private IUPower proxy;
     private HashTable<string, Device> _devices =
         new HashTable<string, Device>(str_hash, str_equal);
 
+    /** List of UPower devices. */
     public List<weak Device> devices {
         owned get { return _devices.get_values(); }
     }
 
+    /** Emitted when a new device is connected. */
     public signal void device_added(Device device);
+
+    /** Emitted a new device is disconnected. */
     public signal void device_removed(Device device);
 
+    /** A composite device that represents the battery status. */
     public Device display_device { owned get { return Device.get_default(); }}
 
     public string daemon_version { owned get { return proxy.daemon_version; } }
+
+    /** Indicates whether the system is running on battery power. */
     public bool on_battery { get { return proxy.on_battery; } }
+
+    /** Indicates if the laptop lid is closed where the display cannot be seen. */
     public bool lid_is_closed { get { return proxy.lid_is_closed; } }
+
+    /** Indicates if the system has a lid device. */
     public bool lis_is_present { get { return proxy.lid_is_closed; } }
 
+    /**
+     * When the system's power supply is critical (critically low batteries or UPS),
+     * the system will take this action.
+     */
     public string critical_action {
         owned get {
             try {
@@ -41,8 +58,14 @@ public class UPower : Object {
                 _devices.set(path, new Device(path));
 
             proxy.device_added.connect((path) => {
-                _devices.set(path, new Device(path));
-                notify_property("devices");
+                try {
+                    var d = new Device(path);
+                    _devices.set(path, d);
+                    device_added(d);
+                    notify_property("devices");
+                } catch (Error err) {
+                    critical(err.message);
+                }
             });
 
             proxy.device_removed.connect((path) => {
@@ -55,4 +78,3 @@ public class UPower : Object {
         }
     }
 }
-}
diff --git a/lib/gir.py b/lib/gir.py
index 9ef680f..a0a81dc 100644
--- a/lib/gir.py
+++ b/lib/gir.py
@@ -8,6 +8,15 @@ import xml.etree.ElementTree as ET
 import html
 import sys
 import subprocess
+import re
+
+
+# valac fails on gi-docgen compliant markdown
+# gi-docgen removes valac compliant ulink
+# so we use vala notation and turn it into markdown
+def ulink_to_markdown(text: str):
+    pattern = r'<ulink url="(.*?)">(.*?)</ulink>'
+    return re.sub(pattern, r"[\2](\1)", text)
 
 
 def fix_gir(name: str, gir: str, out: str):
@@ -24,7 +33,7 @@ def fix_gir(name: str, gir: str, out: str):
 
     for doc in root.findall(".//doc", namespaces):
         if doc.text:
-            doc.text = (
+            doc.text = ulink_to_markdown(
                 html.unescape(doc.text).replace("<para>", "").replace("</para>", "")
             )