libmm-glib,location-3gpp: improve documentation

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

@@ -337,11 +337,12 @@ mm_modem_location_get_type
 <FILE>mm-location-3gpp</FILE>
 <TITLE>MMLocation3gpp</TITLE>
 MMLocation3gpp
-MMLocation3gppClass
+<SUBSECTION Getters>
-mm_location_3gpp_get_cell_id
-mm_location_3gpp_get_location_area_code
 mm_location_3gpp_get_mobile_country_code
 mm_location_3gpp_get_mobile_network_code
+mm_location_3gpp_get_location_area_code
+mm_location_3gpp_get_cell_id
+<SUBSECTION Private>
 mm_location_3gpp_get_string_variant
 mm_location_3gpp_new
 mm_location_3gpp_new_from_string_variant
@@ -350,6 +351,7 @@ mm_location_3gpp_set_location_area_code
 mm_location_3gpp_set_mobile_country_code
 mm_location_3gpp_set_mobile_network_code
 <SUBSECTION Standard>
+MMLocation3gppClass
 MMLocation3gppPrivate
 MM_IS_LOCATION_3GPP
 MM_IS_LOCATION_3GPP_CLASS

libmm-glib/mm-location-3gpp.c

@@ -21,6 +21,19 @@
 #include "mm-common-helpers.h"
 #include "mm-location-3gpp.h"
 
+/**
+ * SECTION: mm-location-3gpp
+ * @title: MMLocation3gpp
+ * @short_description: Helper object to handle 3GPP location information.
+ *
+ * The #MMLocation3gpp is an object handling the location information of the
+ * modem when this is reported by the 3GPP network.
+ *
+ * This object is retrieved with either mm_modem_location_get_3gpp(),
+ * mm_modem_location_get_3gpp_sync(), mm_modem_location_get_full() or
+ * mm_modem_location_get_full_sync().
+ */
+
 G_DEFINE_TYPE (MMLocation3gpp, mm_location_3gpp, G_TYPE_OBJECT);
 
 struct _MMLocation3gppPrivate {
@@ -32,6 +45,14 @@ struct _MMLocation3gppPrivate {
 
 /*****************************************************************************/
 
+/**
+ * mm_location_3gpp_get_mobile_country_code:
+ * @self: a #MMLocation3gpp.
+ *
+ * Gets the Mobile Country Code of the 3GPP network.
+ *
+ * Returns: the MCC, or 0 if unknown.
+ */
 guint
 mm_location_3gpp_get_mobile_country_code (MMLocation3gpp *self)
 {
@@ -40,30 +61,6 @@ mm_location_3gpp_get_mobile_country_code (MMLocation3gpp *self)
     return self->priv->mobile_country_code;
 }
 
-guint
-mm_location_3gpp_get_mobile_network_code (MMLocation3gpp *self)
-{
-    g_return_val_if_fail (MM_IS_LOCATION_3GPP (self), 0);
-
-    return self->priv->mobile_network_code;
-}
-
-gulong
-mm_location_3gpp_get_location_area_code (MMLocation3gpp *self)
-{
-    g_return_val_if_fail (MM_IS_LOCATION_3GPP (self), 0);
-
-    return self->priv->location_area_code;
-}
-
-gulong
-mm_location_3gpp_get_cell_id (MMLocation3gpp *self)
-{
-    g_return_val_if_fail (MM_IS_LOCATION_3GPP (self), 0);
-
-    return self->priv->cell_id;
-}
-
 gboolean
 mm_location_3gpp_set_mobile_country_code (MMLocation3gpp *self,
                                           guint mobile_country_code)
@@ -78,6 +75,24 @@ mm_location_3gpp_set_mobile_country_code (MMLocation3gpp *self,
     return TRUE;
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_location_3gpp_get_mobile_network_code:
+ * @self: a #MMLocation3gpp.
+ *
+ * Gets the Mobile Network Code of the 3GPP network.
+ *
+ * Returns: the MNC, or 0 if unknown.
+ */
+guint
+mm_location_3gpp_get_mobile_network_code (MMLocation3gpp *self)
+{
+    g_return_val_if_fail (MM_IS_LOCATION_3GPP (self), 0);
+
+    return self->priv->mobile_network_code;
+}
+
 gboolean
 mm_location_3gpp_set_mobile_network_code (MMLocation3gpp *self,
                                           guint mobile_network_code)
@@ -92,6 +107,24 @@ mm_location_3gpp_set_mobile_network_code (MMLocation3gpp *self,
     return TRUE;
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_location_3gpp_get_location_area_code:
+ * @self: a #MMLocation3gpp.
+ *
+ * Gets the location area code of the 3GPP network.
+ *
+ * Returns: the location area code, or 0 if unknown.
+ */
+gulong
+mm_location_3gpp_get_location_area_code (MMLocation3gpp *self)
+{
+    g_return_val_if_fail (MM_IS_LOCATION_3GPP (self), 0);
+
+    return self->priv->location_area_code;
+}
+
 gboolean
 mm_location_3gpp_set_location_area_code (MMLocation3gpp *self,
                                          gulong location_area_code)
@@ -106,6 +139,23 @@ mm_location_3gpp_set_location_area_code (MMLocation3gpp *self,
     return TRUE;
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_location_3gpp_get_cell_id:
+ * @self: a #MMLocation3gpp.
+ *
+ * Gets the cell ID of the 3GPP network.
+ *
+ * Returns: the cell ID, or 0 if unknown.
+ */
+gulong
+mm_location_3gpp_get_cell_id (MMLocation3gpp *self)
+{
+    g_return_val_if_fail (MM_IS_LOCATION_3GPP (self), 0);
+
+    return self->priv->cell_id;
+}
 
 gboolean
 mm_location_3gpp_set_cell_id (MMLocation3gpp *self,

libmm-glib/mm-location-3gpp.h

@@ -36,17 +36,39 @@ typedef struct _MMLocation3gpp MMLocation3gpp;
 typedef struct _MMLocation3gppClass MMLocation3gppClass;
 typedef struct _MMLocation3gppPrivate MMLocation3gppPrivate;
 
+/**
+ * MMLocation3gpp:
+ *
+ * The #MMLocation3gpp structure contains private data and should
+ * only be accessed using the provided API.
+ */
 struct _MMLocation3gpp {
+    /*< private >*/
     GObject parent;
     MMLocation3gppPrivate *priv;
 };
 
 struct _MMLocation3gppClass {
+    /*< private >*/
     GObjectClass parent;
 };
 
 GType mm_location_3gpp_get_type (void);
 
+guint  mm_location_3gpp_get_mobile_country_code (MMLocation3gpp *self);
+guint  mm_location_3gpp_get_mobile_network_code (MMLocation3gpp *self);
+gulong mm_location_3gpp_get_location_area_code  (MMLocation3gpp *self);
+gulong mm_location_3gpp_get_cell_id             (MMLocation3gpp *self);
+
+/*****************************************************************************/
+/* ModemManager/libmm-glib/mmcli specific methods */
+
+#if defined (_LIBMM_INSIDE_MM) ||    \
+    defined (_LIBMM_INSIDE_MMCLI) || \
+    defined (LIBMM_GLIB_COMPILATION)
+
+GVariant *mm_location_3gpp_get_string_variant (MMLocation3gpp *self);
+
 MMLocation3gpp *mm_location_3gpp_new (void);
 MMLocation3gpp *mm_location_3gpp_new_from_string_variant (GVariant *string,
                                                           GError **error);
@@ -60,12 +82,7 @@ gboolean mm_location_3gpp_set_location_area_code  (MMLocation3gpp *self,
 gboolean mm_location_3gpp_set_cell_id             (MMLocation3gpp *self,
                                                    gulong cell_id);
 
-guint  mm_location_3gpp_get_mobile_country_code (MMLocation3gpp *self);
+#endif
-guint  mm_location_3gpp_get_mobile_network_code (MMLocation3gpp *self);
-gulong mm_location_3gpp_get_location_area_code  (MMLocation3gpp *self);
-gulong mm_location_3gpp_get_cell_id             (MMLocation3gpp *self);
-
-GVariant *mm_location_3gpp_get_string_variant (MMLocation3gpp *self);
 
 G_END_DECLS