libmm-glib,unlock-retries: improve documentation

docs/reference/libmm-glib/libmm-glib-sections.txt

@@ -165,19 +165,21 @@ mm_modem_get_type
 <FILE>mm-unlock-retries</FILE>
 <TITLE>MMUnlockRetries</TITLE>
 MMUnlockRetries
-MMUnlockRetriesClass
-MMUnlockRetriesForeachCb
 MM_UNLOCK_RETRIES_UNKNOWN
+<SUBSECTION Getters>
+mm_unlock_retries_get
+MMUnlockRetriesForeachCb
+mm_unlock_retries_foreach
+<SUBSECTION Private>
 mm_unlock_retries_build_string
 mm_unlock_retries_cmp
-mm_unlock_retries_foreach
-mm_unlock_retries_get
-mm_unlock_retries_get_dictionary
 mm_unlock_retries_new
 mm_unlock_retries_new_from_dictionary
+mm_unlock_retries_get_dictionary
 mm_unlock_retries_set
 mm_unlock_retries_unset
 <SUBSECTION Standard>
+MMUnlockRetriesClass
 MMUnlockRetriesPrivate
 MM_IS_UNLOCK_RETRIES
 MM_IS_UNLOCK_RETRIES_CLASS

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,

libmm-glib/mm-unlock-retries.h

@@ -32,23 +32,62 @@ 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);
 
+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);
+
+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);
 
@@ -59,17 +98,6 @@ void  mm_unlock_retries_set (MMUnlockRetries *self,
 void  mm_unlock_retries_unset (MMUnlockRetries *self,
                                MMModemLock lock);
 
-guint mm_unlock_retries_get (MMUnlockRetries *self,
-                             MMModemLock lock);
-
-typedef void (* MMUnlockRetriesForeachCb) (MMModemLock lock,
-                                           guint count,
-                                           gpointer user_data);
-
-void mm_unlock_retries_foreach (MMUnlockRetries *self,
-                                MMUnlockRetriesForeachCb callback,
-                                gpointer user_data);
-
 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 */