From 8a0be71e6c57d9e8f236d3e5325b2e1ee6316d4a Mon Sep 17 00:00:00 2001
From: Bastien Nocera <hadess@hadess.net>
Date: Fri, 4 Sep 2020 15:40:14 +0200
Subject: [PATCH] main: Add PpdDriver API docs

---
 src/ppd-driver.c | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 src/ppd-driver.h |  9 +++++++++
 2 files changed, 55 insertions(+)

diff --git a/src/ppd-driver.c b/src/ppd-driver.c
index 30aadfd..0bfc2bf 100644
--- a/src/ppd-driver.c
+++ b/src/ppd-driver.c
@@ -10,6 +10,34 @@
 #include "ppd-driver.h"
 #include "ppd-enums.h"
 
+/**
+ * SECTION:ppd-driver
+ * @Short_description: Profile Drivers
+ * @Title: Profile Drivers
+ *
+ * Profile drivers are the implementation of the different profiles for
+ * the whole system. A driver will implement support for one or more
+ * profiles, usually one or both of the `performance` and `power-saver`
+ * profiles, for a particular system. Only one driver will be selected and
+ * running per profile.
+ *
+ * If no system-specific driver is available, some placeholder `balanced`
+ * and `power-saver` drivers will be put in place, and the `performance`
+ * profile will be unavailable.
+ *
+ * Common implementation of drivers might be:
+ * - a driver handling all three profiles, relying on a firmware feature
+ *   exposed in the kernel,
+ * - a driver that only implements the `performance` profile on a particular
+ *   system it has intimate knowledge of, leaving the `balanced` and
+ *   `power-saver` profiles using placeholder
+ *
+ * When a driver implements the `performance` profile, it might set the
+ * #PpdDriver:performance-inhibited property if the profile isn't available for any
+ * reason, such as thermal limits being reached, or because a part of the
+ * user's body is too close for safety, for example.
+ */
+
 typedef struct
 {
   char          *driver_name;
@@ -100,12 +128,23 @@ ppd_driver_class_init (PpdDriverClass *klass)
   object_class->get_property = ppd_driver_get_property;
   object_class->set_property = ppd_driver_set_property;
 
+  /**
+   * PpdDriver::driver-name:
+   *
+   * A unique driver name, only used for debugging.
+   */
   g_object_class_install_property (object_class, PROP_DRIVER_NAME,
                                    g_param_spec_string("driver-name",
                                                        "Driver name",
                                                        "Profile driver name",
                                                        NULL,
                                                        G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+
+  /**
+   * PpdDriver::profiles:
+   *
+   * The bitmask of #PpdProfile<!-- -->s implemented by this driver.
+   */
   g_object_class_install_property (object_class, PROP_PROFILES,
                                    g_param_spec_flags("profiles",
                                                       "Profiles",
@@ -113,6 +152,13 @@ ppd_driver_class_init (PpdDriverClass *klass)
                                                       PPD_TYPE_PROFILE,
                                                       0,
                                                       G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+
+  /**
+   * PpdDriver:performance-inhibited:
+   *
+   * If set to a non-%NULL value, the reason why the performance profile is unavailable.
+   * The value must be one of the options listed in the D-Bus API reference.
+   */
   g_object_class_install_property (object_class, PROP_PERFORMANCE_INHIBITED,
                                    g_param_spec_string("performance-inhibited",
                                                        "Performance Inhibited",
diff --git a/src/ppd-driver.h b/src/ppd-driver.h
index fe19fda..b405fe4 100644
--- a/src/ppd-driver.h
+++ b/src/ppd-driver.h
@@ -15,6 +15,15 @@
 #define PPD_TYPE_DRIVER (ppd_driver_get_type())
 G_DECLARE_DERIVABLE_TYPE(PpdDriver, ppd_driver, PPD, DRIVER, GObject)
 
+/**
+ * PpdDriverClass:
+ * @parent_class: The parent class.
+ * @probe: Called by the daemon on startup.
+ * @activate_profile: Called by the daemon for every profile change.
+ *
+ * New profile drivers should derive from #PpdDriver and implement
+ * at least one of probe() and @activate_profile.
+ */
 struct _PpdDriverClass
 {
   GObjectClass   parent_class;