libmm-glib,unlock-retries: improve documentation

2 files changed, 71 insertions, 10 deletions

diff --git a/libmm-glib/mm-unlock-retries.c b/libmm-glib/mm-unlock-retries.c
index a329c411..4ce6c324 100644
--- a/libmm-glib/mm-unlock-retries.c
+++ b/libmm-glib/mm-unlock-retries.c
@@ -20,6 +20,18 @@
 #include "mm-enums-types.h"
 #include "mm-unlock-retries.h"
 
+/**
+ * SECTION: mm-unlock-retries
+ * @title: MMUnlockRetries
+ * @short_description: Helper object to report unlock retries.
+ *
+ * The #MMUnlockRetries is an object exposing the unlock retry counts for
+ * different #MMModemLock values.
+ *
+ * This object is retrieved from the #MMModem object with either
+ * mm_modem_get_unlock_retries() or mm_modem_peek_unlock_retries().
+ */
+
 G_DEFINE_TYPE (MMUnlockRetries, mm_unlock_retries, G_TYPE_OBJECT);
 
 struct _MMUnlockRetriesPrivate {
@@ -46,6 +58,17 @@ mm_unlock_retries_unset (MMUnlockRetries *self,
                          GUINT_TO_POINTER (lock));
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_unlock_retries_get:
+ * @self: a #MMUnlockRetries.
+ * @lock: a #MMModemLock.
+ *
+ * Gets the unlock retries for the given @lock.
+ *
+ * Returns: the unlock retries or %MM_UNLOCK_RETRIES_UNKNOWN if unknown.
+ */
 guint
 mm_unlock_retries_get (MMUnlockRetries *self,
                        MMModemLock lock)
@@ -86,6 +109,14 @@ mm_unlock_retries_cmp (MMUnlockRetries *a,
 
 /*****************************************************************************/
 
+/**
+ * mm_unlock_retries_foreach:
+ * @self: a @MMUnlockRetries.
+ * @callback: callback to call for each available lock.
+ * @user_data: data to pass to @callback.
+ *
+ * Executes @callback for each lock information found in @self.
+ */
 void
 mm_unlock_retries_foreach (MMUnlockRetries *self,
                            MMUnlockRetriesForeachCb callback,
diff --git a/libmm-glib/mm-unlock-retries.h b/libmm-glib/mm-unlock-retries.h
index ea43cb6a..babdcbb3 100644
--- a/libmm-glib/mm-unlock-retries.h
+++ b/libmm-glib/mm-unlock-retries.h
@@ -32,36 +32,47 @@ G_BEGIN_DECLS
 #define MM_IS_UNLOCK_RETRIES_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),  MM_TYPE_UNLOCK_RETRIES))
 #define MM_UNLOCK_RETRIES_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),  MM_TYPE_UNLOCK_RETRIES, MMUnlockRetriesClass))
 
+/**
+ * MM_UNLOCK_RETRIES_UNKNOWN:
+ *
+ * Identifier for reporting unknown unlock retries.
+ */
 #define MM_UNLOCK_RETRIES_UNKNOWN 999
 
 typedef struct _MMUnlockRetries MMUnlockRetries;
 typedef struct _MMUnlockRetriesClass MMUnlockRetriesClass;
 typedef struct _MMUnlockRetriesPrivate MMUnlockRetriesPrivate;
 
+/**
+ * MMUnlockRetries:
+ *
+ * The #MMUnlockRetries structure contains private data and should only be accessed
+ * using the provided API.
+ */
 struct _MMUnlockRetries {
+    /*< private >*/
     GObject parent;
     MMUnlockRetriesPrivate *priv;
 };
 
 struct _MMUnlockRetriesClass {
+    /*< private >*/
     GObjectClass parent;
 };
 
 GType mm_unlock_retries_get_type (void);
 
-MMUnlockRetries *mm_unlock_retries_new (void);
-MMUnlockRetries *mm_unlock_retries_new_from_dictionary (GVariant *dictionary);
-
-void  mm_unlock_retries_set (MMUnlockRetries *self,
-                             MMModemLock lock,
-                             guint retries);
-
-void  mm_unlock_retries_unset (MMUnlockRetries *self,
-                               MMModemLock lock);
-
 guint mm_unlock_retries_get (MMUnlockRetries *self,
                              MMModemLock lock);
 
+/**
+ * MMUnlockRetriesForeachCb:
+ * @lock: a #MMModemLock.
+ * @count: the number of retries left for @lock.
+ * @user_data: data passed to the function.
+ *
+ * Specifies the type of function passed to mm_unlock_retries_foreach().
+ */
 typedef void (* MMUnlockRetriesForeachCb) (MMModemLock lock,
                                            guint count,
                                            gpointer user_data);
@@ -70,6 +81,23 @@ void mm_unlock_retries_foreach (MMUnlockRetries *self,
                                 MMUnlockRetriesForeachCb callback,
                                 gpointer user_data);
 
+/*****************************************************************************/
+/* ModemManager/libmm-glib/mmcli specific methods */
+
+#if defined (_LIBMM_INSIDE_MM) ||    \
+    defined (_LIBMM_INSIDE_MMCLI) || \
+    defined (LIBMM_GLIB_COMPILATION)
+
+MMUnlockRetries *mm_unlock_retries_new (void);
+MMUnlockRetries *mm_unlock_retries_new_from_dictionary (GVariant *dictionary);
+
+void  mm_unlock_retries_set (MMUnlockRetries *self,
+                             MMModemLock lock,
+                             guint retries);
+
+void  mm_unlock_retries_unset (MMUnlockRetries *self,
+                               MMModemLock lock);
+
 gboolean mm_unlock_retries_cmp (MMUnlockRetries *a,
                                 MMUnlockRetries *b);
 
@@ -77,6 +105,8 @@ GVariant *mm_unlock_retries_get_dictionary (MMUnlockRetries *self);
 
 gchar *mm_unlock_retries_build_string (MMUnlockRetries *self);
 
+#endif
+
 G_END_DECLS
 
 #endif /* MM_UNLOCK_RETRIES_H */