docs: powerprofile doc comments

3 files changed, 138 insertions, 64 deletions

diff --git a/lib/powerprofiles/cli.vala b/lib/powerprofiles/cli.vala
index 7be01d2..1e5cc70 100644
--- a/lib/powerprofiles/cli.vala
+++ b/lib/powerprofiles/cli.vala
@@ -56,16 +56,16 @@ int main(string[] argv) {
     if (daemonize) {
         var loop = new MainLoop();
 
-        stdout.printf("%s\n", profiles.to_json_string());
+        stdout.printf("%s\n", to_json_string(profiles));
         stdout.flush();
 
         profiles.notify.connect(() => {
-            stdout.printf("%s\n", profiles.to_json_string());
+            stdout.printf("%s\n", to_json_string(profiles));
             stdout.flush();
         });
 
         profiles.profile_released.connect(() => {
-            stdout.printf("%s\n", profiles.to_json_string());
+            stdout.printf("%s\n", to_json_string(profiles));
             stdout.flush();
         });
 
@@ -73,8 +73,49 @@ int main(string[] argv) {
     }
 
     if (set == null && !daemonize) {
-        stdout.printf("%s\n", profiles.to_json_string());
+        stdout.printf("%s\n", to_json_string(profiles));
     }
 
     return 0;
 }
+
+string to_json_string(AstalPowerProfiles.PowerProfiles profiles) {
+    var acts = new Json.Builder().begin_array();
+    foreach (var action in profiles.actions) {
+        acts.add_string_value(action);
+    }
+
+    var active_holds = new Json.Builder().begin_array();
+    foreach (var action in profiles.active_profile_holds) {
+        active_holds.add_value(new Json.Builder()
+            .begin_object()
+            .set_member_name("application_id").add_string_value(action.application_id)
+            .set_member_name("profile").add_string_value(action.profile)
+            .set_member_name("reason").add_string_value(action.reason)
+            .end_object()
+            .get_root());
+    }
+
+    var profs = new Json.Builder().begin_array();
+    foreach (var prof in profiles.profiles) {
+        profs.add_value(new Json.Builder()
+            .begin_object()
+            .set_member_name("profie").add_string_value(prof.profile)
+            .set_member_name("driver").add_string_value(prof.driver)
+            .set_member_name("cpu_driver").add_string_value(prof.cpu_driver)
+            .set_member_name("platform_driver").add_string_value(prof.platform_driver)
+            .end_object()
+            .get_root());
+    }
+
+    return Json.to_string(new Json.Builder()
+        .begin_object()
+        .set_member_name("active_profile").add_string_value(profiles.active_profile)
+        .set_member_name("icon_name").add_string_value(profiles.icon_name)
+        .set_member_name("performance_degraded").add_string_value(profiles.performance_degraded)
+        .set_member_name("actions").add_value(acts.end_array().get_root())
+        .set_member_name("active_profile_holds").add_value(active_holds.end_array().get_root())
+        .set_member_name("profiles").add_value(profs.end_array().get_root())
+        .end_object()
+        .get_root(), false);
+}
diff --git a/lib/powerprofiles/meson.build b/lib/powerprofiles/meson.build
index d0fe78f..cd8cc2b 100644
--- a/lib/powerprofiles/meson.build
+++ b/lib/powerprofiles/meson.build
@@ -39,32 +39,38 @@ deps = [
   dependency('json-glib-1.0'),
 ]
 
-sources = [
-  config,
+sources = [config] + files(
   'power-profiles.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: deps,
-    install_dir: get_option('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(
@@ -77,10 +83,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: deps,
+    install_dir: get_option('libdir') / 'pkgconfig',
+  )
 endif
 
 if get_option('cli')
diff --git a/lib/powerprofiles/power-profiles.vala b/lib/powerprofiles/power-profiles.vala
index ab98505..a104d2e 100644
--- a/lib/powerprofiles/power-profiles.vala
+++ b/lib/powerprofiles/power-profiles.vala
@@ -16,11 +16,17 @@ private interface IPowerProfiles : DBusProxy {
 }
 
 public PowerProfiles get_default() {
+    /** Gets the default singleton PowerProfiles instance. */
     return PowerProfiles.get_default();
 }
 
+/**
+ * Client for  [[https://freedesktop-team.pages.debian.net/power-profiles-daemon/gdbus-org.freedesktop.UPower.PowerProfiles.html|PowerProfiles]].
+ */
 public class PowerProfiles : Object {
     private static PowerProfiles instance;
+
+    /** Gets the default singleton PowerProfiles instance. */
     public static PowerProfiles get_default() {
         if (instance == null)
             instance = new PowerProfiles();
@@ -52,19 +58,34 @@ public class PowerProfiles : Object {
         }
     }
 
+    /**
+     * The type of the currently active profile.
+     * It might change automatically if a profile is held,
+     * using the [[email protected]_profile] method.
+     */
     public string active_profile {
         owned get { return proxy.active_profile; }
         set { proxy.active_profile = value; }
     }
 
+    /**
+     * Return a named icon based [[email protected]:active_profile].
+     */
     public string icon_name {
         owned get { return @"power-profile-$active_profile-symbolic"; }
     }
 
+    /**
+     * List of the "actions" implemented in the running daemon.
+     * This can used to figure out whether particular functionality is available in the daemon.
+     */
     public string[] actions {
         owned get { return proxy.actions.copy(); }
     }
 
+    /**
+     * List of dictionaries representing the current profile holds.
+     */
     public Hold[] active_profile_holds {
         owned get {
             Hold[] holds = new Hold[proxy.active_profile_holds.length];
@@ -80,14 +101,21 @@ public class PowerProfiles : Object {
         }
     }
 
+    /**
+     * This will be set if the performance power profile is running in degraded mode,
+     * with the value being used to identify the reason for that degradation.
+     * Possible values are:
+     * - "lap-detected" (the computer is sitting on the user's lap)
+     * - "high-operating-temperature" (the computer is close to overheating)
+     * - "" (the empty string, if not performance is not degraded)
+     */
     public string performance_degraded {
         owned get { return proxy.performance_degraded; }
     }
 
-    public string performance_inhibited {
-        owned get { return proxy.performance_degraded; }
-    }
-
+    /**
+     * List of each profile.
+     */
     public Profile[] profiles {
         owned get {
             Profile[] profs = new Profile[proxy.profiles.length];
@@ -104,12 +132,31 @@ public class PowerProfiles : Object {
         }
     }
 
+    /**
+     * The version of the power-profiles-daemon software.
+     */
     public string version {
         owned get { return proxy.version; }
     }
 
+    /**
+     * Emitted when the profile is released because
+     * [[email protected]:active_profile] was manually changed.
+     * This will only be emitted to the process that originally called
+     * [[email protected]_profile].
+     */
     public signal void profile_released (uint cookie);
 
+    /**
+     * This forces the passed profile (either 'power-saver' or 'performance')
+     * to be activated until either the caller quits,
+     * [[email protected]_profile] is called,
+     * or the [[email protected]:active_profile] is changed by the user.
+     * When conflicting profiles are requested to be held,
+     * the 'power-saver' profile will be activated in preference to the 'performance' profile.
+     * Those holds will be automatically cancelled if the user manually switches to another profile,
+     * and the [[email protected]::profile_released] signal will be emitted.
+     */
     public int hold_profile(string profile, string reason, string application_id) {
         try {
             return (int)proxy.hold_profile(profile, reason, application_id);
@@ -119,6 +166,9 @@ public class PowerProfiles : Object {
         }
     }
 
+    /**
+     * This removes the hold that was set on a profile.
+     */
     public void release_profile(uint cookie) {
         try {
             proxy.release_profile(cookie);
@@ -126,54 +176,21 @@ public class PowerProfiles : Object {
             critical(error.message);
         }
     }
-
-    public string to_json_string() {
-        var acts = new Json.Builder().begin_array();
-        foreach (var action in actions) {
-            acts.add_string_value(action);
-        }
-
-        var active_holds = new Json.Builder().begin_array();
-        foreach (var action in active_profile_holds) {
-            active_holds.add_value(new Json.Builder()
-                .begin_object()
-                .set_member_name("application_id").add_string_value(action.application_id)
-                .set_member_name("profile").add_string_value(action.profile)
-                .set_member_name("reason").add_string_value(action.reason)
-                .end_object()
-                .get_root());
-        }
-
-        var profs = new Json.Builder().begin_array();
-        foreach (var prof in profiles) {
-            profs.add_value(new Json.Builder()
-                .begin_object()
-                .set_member_name("profie").add_string_value(prof.profile)
-                .set_member_name("driver").add_string_value(prof.driver)
-                .set_member_name("cpu_driver").add_string_value(prof.cpu_driver)
-                .set_member_name("platform_driver").add_string_value(prof.platform_driver)
-                .end_object()
-                .get_root());
-        }
-
-        return Json.to_string(new Json.Builder()
-            .begin_object()
-            .set_member_name("active_profile").add_string_value(active_profile)
-            .set_member_name("icon_name").add_string_value(icon_name)
-            .set_member_name("performance_degraded").add_string_value(performance_degraded)
-            .set_member_name("performance_inhibited").add_string_value(performance_inhibited)
-            .set_member_name("actions").add_value(acts.end_array().get_root())
-            .set_member_name("active_profile_holds").add_value(active_holds.end_array().get_root())
-            .set_member_name("profiles").add_value(profs.end_array().get_root())
-            .end_object()
-            .get_root(), false);
-    }
 }
 
 public struct Profile {
+    /**
+     * Will be one of:
+     * - "power-saver" (battery saving profile)
+     * - "balanced" (the default profile)
+     * - "performance" (a profile that does not care about noise or battery consumption)
+     */
     public string profile;
     public string cpu_driver;
     public string platform_driver;
+    /**
+     * Identifies the power-profiles-daemon backend code used to implement the profile.
+     */
     public string driver;
 }