libmm-glib,network-timezone: improve documentation

3 files changed, 95 insertions, 26 deletions

diff --git a/docs/reference/libmm-glib/libmm-glib-sections.txt b/docs/reference/libmm-glib/libmm-glib-sections.txt
index 78b35f12..605b6e1f 100644
--- a/docs/reference/libmm-glib/libmm-glib-sections.txt
+++ b/docs/reference/libmm-glib/libmm-glib-sections.txt
@@ -476,19 +476,21 @@ mm_modem_time_get_type
 <FILE>mm-network-timezone</FILE>
 <TITLE>MMNetworkTimezone</TITLE>
 MMNetworkTimezone
-MMNetworkTimezoneClass
-MM_NETWORK_TIMEZONE_LEAP_SECONDS_UNKNOWN
 MM_NETWORK_TIMEZONE_OFFSET_UNKNOWN
-mm_network_timezone_get_dictionary
+MM_NETWORK_TIMEZONE_LEAP_SECONDS_UNKNOWN
+<SUBSECTION Getters>
+mm_network_timezone_get_offset
 mm_network_timezone_get_dst_offset
 mm_network_timezone_get_leap_seconds
-mm_network_timezone_get_offset
+<SUBSECTION Private>
 mm_network_timezone_new
 mm_network_timezone_new_from_dictionary
 mm_network_timezone_set_dst_offset
 mm_network_timezone_set_leap_seconds
+mm_network_timezone_get_dictionary
 mm_network_timezone_set_offset
 <SUBSECTION Standard>
+MMNetworkTimezoneClass
 MMNetworkTimezonePrivate
 MM_IS_NETWORK_TIMEZONE
 MM_IS_NETWORK_TIMEZONE_CLASS
diff --git a/libmm-glib/mm-network-timezone.c b/libmm-glib/mm-network-timezone.c
index dfb6914e..0a37c0ea 100644
--- a/libmm-glib/mm-network-timezone.c
+++ b/libmm-glib/mm-network-timezone.c
@@ -18,6 +18,18 @@
 #include "mm-errors-types.h"
 #include "mm-network-timezone.h"
 
+/**
+ * SECTION: mm-network-timezone
+ * @title: MMNetworkTimezone
+ * @short_description: Helper object to handle network timezone information.
+ *
+ * The #MMNetworkTimezone is an object handling the timezone information
+ * reported by the network.
+ *
+ * This object is retrieved with either mm_modem_time_peek_network_timezone()
+ * or mm_modem_time_get_network_timezone().
+ */
+
 G_DEFINE_TYPE (MMNetworkTimezone, mm_network_timezone, G_TYPE_OBJECT);
 
 struct _MMNetworkTimezonePrivate {
@@ -28,6 +40,14 @@ struct _MMNetworkTimezonePrivate {
 
 /*****************************************************************************/
 
+/**
+ * mm_network_timezone_get_offset:
+ * @self: a #MMNetworkTimezone.
+ *
+ * Gets the timezone offset (in minutes) reported by the network.
+ *
+ * Returns: the offset, or %MM_NETWORK_TIMEZONE_OFFSET_UNKNOWN if unknown.
+ */
 gint
 mm_network_timezone_get_offset (MMNetworkTimezone *self)
 {
@@ -37,42 +57,61 @@ mm_network_timezone_get_offset (MMNetworkTimezone *self)
     return self->priv->offset;
 }
 
-gint
-mm_network_timezone_get_dst_offset (MMNetworkTimezone *self)
+void
+mm_network_timezone_set_offset (MMNetworkTimezone *self,
+                                gint offset)
 {
-    g_return_val_if_fail (MM_IS_NETWORK_TIMEZONE (self),
-                          MM_NETWORK_TIMEZONE_OFFSET_UNKNOWN);
+    g_return_if_fail (MM_IS_NETWORK_TIMEZONE (self));
 
-    return self->priv->dst_offset;
+    self->priv->offset = offset;
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_network_timezone_get_dst_offset:
+ * @self: a #MMNetworkTimezone.
+ *
+ * Gets the timezone offset due to daylight saving time (in minutes) reported by
+ * the network.
+ *
+ * Returns: the offset, or %MM_NETWORK_TIMEZONE_OFFSET_UNKNOWN if unknown.
+ */
 gint
-mm_network_timezone_get_leap_seconds (MMNetworkTimezone *self)
+mm_network_timezone_get_dst_offset (MMNetworkTimezone *self)
 {
     g_return_val_if_fail (MM_IS_NETWORK_TIMEZONE (self),
-                          MM_NETWORK_TIMEZONE_LEAP_SECONDS_UNKNOWN);
+                          MM_NETWORK_TIMEZONE_OFFSET_UNKNOWN);
 
-    return self->priv->leap_seconds;
+    return self->priv->dst_offset;
 }
 
-/*****************************************************************************/
-
 void
-mm_network_timezone_set_offset (MMNetworkTimezone *self,
-                                gint offset)
+mm_network_timezone_set_dst_offset (MMNetworkTimezone *self,
+                                    gint dst_offset)
 {
     g_return_if_fail (MM_IS_NETWORK_TIMEZONE (self));
 
-    self->priv->offset = offset;
+    self->priv->dst_offset = dst_offset;
 }
 
-void
-mm_network_timezone_set_dst_offset (MMNetworkTimezone *self,
-                                    gint dst_offset)
+/*****************************************************************************/
+
+/**
+ * mm_network_timezone_get_leap_seconds:
+ * @self: a #MMNetworkTimezone.
+ *
+ * Gets the number of leap seconds (TAI-UTC), as reported by the network.
+ *
+ * Returns: the number of leap seconds, or %MM_NETWORK_TIMEZONE_LEAP_SECONDS_UNKNOWN if unknown.
+ */
+gint
+mm_network_timezone_get_leap_seconds (MMNetworkTimezone *self)
 {
-    g_return_if_fail (MM_IS_NETWORK_TIMEZONE (self));
+    g_return_val_if_fail (MM_IS_NETWORK_TIMEZONE (self),
+                          MM_NETWORK_TIMEZONE_LEAP_SECONDS_UNKNOWN);
 
-    self->priv->dst_offset = dst_offset;
+    return self->priv->leap_seconds;
 }
 
 void
diff --git a/libmm-glib/mm-network-timezone.h b/libmm-glib/mm-network-timezone.h
index 42a1bc69..2bbb3058 100644
--- a/libmm-glib/mm-network-timezone.h
+++ b/libmm-glib/mm-network-timezone.h
@@ -32,32 +32,58 @@ G_BEGIN_DECLS
 #define MM_IS_NETWORK_TIMEZONE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),  MM_TYPE_NETWORK_TIMEZONE))
 #define MM_NETWORK_TIMEZONE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),  MM_TYPE_NETWORK_TIMEZONE, MMNetworkTimezoneClass))
 
+/**
+ * MM_NETWORK_TIMEZONE_OFFSET_UNKNOWN:
+ *
+ * Identifier for an unknown timezone offset.
+ */
 #define MM_NETWORK_TIMEZONE_OFFSET_UNKNOWN       G_MAXINT32
+
+/**
+ * MM_NETWORK_TIMEZONE_LEAP_SECONDS_UNKNOWN:
+ *
+ * Identifier for an unknown leap seconds value.
+ */
 #define MM_NETWORK_TIMEZONE_LEAP_SECONDS_UNKNOWN G_MAXINT32
 
 typedef struct _MMNetworkTimezone MMNetworkTimezone;
 typedef struct _MMNetworkTimezoneClass MMNetworkTimezoneClass;
 typedef struct _MMNetworkTimezonePrivate MMNetworkTimezonePrivate;
 
+/**
+ * MMNetworkTimezone:
+ *
+ * The #MMNetworkTimezone structure contains private data and should
+ * only be accessed using the provided API.
+ */
 struct _MMNetworkTimezone {
+    /*< private >*/
     GObject parent;
     MMNetworkTimezonePrivate *priv;
 };
 
 struct _MMNetworkTimezoneClass {
+    /*< private >*/
     GObjectClass parent;
 };
 
 GType mm_network_timezone_get_type (void);
 
-MMNetworkTimezone *mm_network_timezone_new (void);
-MMNetworkTimezone *mm_network_timezone_new_from_dictionary (GVariant *dictionary,
-                                                            GError **error);
-
 gint32 mm_network_timezone_get_offset       (MMNetworkTimezone *self);
 gint32 mm_network_timezone_get_dst_offset   (MMNetworkTimezone *self);
 gint32 mm_network_timezone_get_leap_seconds (MMNetworkTimezone *self);
 
+/*****************************************************************************/
+/* ModemManager/libmm-glib/mmcli specific methods */
+
+#if defined (_LIBMM_INSIDE_MM) ||    \
+    defined (_LIBMM_INSIDE_MMCLI) || \
+    defined (LIBMM_GLIB_COMPILATION)
+
+MMNetworkTimezone *mm_network_timezone_new (void);
+MMNetworkTimezone *mm_network_timezone_new_from_dictionary (GVariant *dictionary,
+                                                            GError **error);
+
 void mm_network_timezone_set_offset       (MMNetworkTimezone *self,
                                            gint offset);
 void mm_network_timezone_set_dst_offset   (MMNetworkTimezone *self,
@@ -67,6 +93,8 @@ void mm_network_timezone_set_leap_seconds (MMNetworkTimezone *self,
 
 GVariant *mm_network_timezone_get_dictionary (MMNetworkTimezone *self);
 
+#endif
+
 G_END_DECLS
 
 #endif /* MM_NETWORK_TIMEZONE_H */