libmm-glib,location-gps-nmea: improve documentation

3 files changed, 55 insertions, 8 deletions

diff --git a/docs/reference/libmm-glib/libmm-glib-sections.txt b/docs/reference/libmm-glib/libmm-glib-sections.txt
index 43863a92..8dbebcb7 100644
--- a/docs/reference/libmm-glib/libmm-glib-sections.txt
+++ b/docs/reference/libmm-glib/libmm-glib-sections.txt
@@ -366,14 +366,16 @@ mm_location_3gpp_get_type
 <FILE>mm-location-gps-nmea</FILE>
 <TITLE>MMLocationGpsNmea</TITLE>
 MMLocationGpsNmea
-MMLocationGpsNmeaClass
-mm_location_gps_nmea_add_trace
-mm_location_gps_nmea_build_full
-mm_location_gps_nmea_get_string_variant
+<SUBSECTION Getters>
 mm_location_gps_nmea_get_trace
+mm_location_gps_nmea_build_full
+<SUBSECTION Private>
 mm_location_gps_nmea_new
 mm_location_gps_nmea_new_from_string_variant
+mm_location_gps_nmea_add_trace
+mm_location_gps_nmea_get_string_variant
 <SUBSECTION Standard>
+MMLocationGpsNmeaClass
 MMLocationGpsNmeaPrivate
 MM_IS_LOCATION_GPS_NMEA
 MM_IS_LOCATION_GPS_NMEA_CLASS
diff --git a/libmm-glib/mm-location-gps-nmea.c b/libmm-glib/mm-location-gps-nmea.c
index de6478dc..2070eebc 100644
--- a/libmm-glib/mm-location-gps-nmea.c
+++ b/libmm-glib/mm-location-gps-nmea.c
@@ -21,6 +21,19 @@
 #include "mm-errors-types.h"
 #include "mm-location-gps-nmea.h"
 
+/**
+ * SECTION: mm-location-gps-nmea
+ * @title: MMLocationGpsNmea
+ * @short_description: Helper object to handle NMEA-based GPS location information.
+ *
+ * The #MMLocationGpsNmea is an object handling the location information of the
+ * modem when this is reported by GPS.
+ *
+ * This object is retrieved with either mm_modem_location_get_gps_nmea(),
+ * mm_modem_location_get_gps_nmea_sync(), mm_modem_location_get_full() or
+ * mm_modem_location_get_full_sync().
+ */
+
 G_DEFINE_TYPE (MMLocationGpsNmea, mm_location_gps_nmea, G_TYPE_OBJECT);
 
 struct _MMLocationGpsNmeaPrivate {
@@ -110,6 +123,15 @@ mm_location_gps_nmea_add_trace (MMLocationGpsNmea *self,
 
 /*****************************************************************************/
 
+/**
+ * mm_location_gps_nmea_get_trace:
+ * @self: a #MMLocationGpsNmea.
+ * @trace_type: specific NMEA trace type to gather.
+ *
+ * Gets the last cached value of the specific @trace_type given.
+ *
+ * Returns: the NMEA trace, or %NULL if not available. Do not free the returned value, it is owned by @self.
+ */
 const gchar *
 mm_location_gps_nmea_get_trace (MMLocationGpsNmea *self,
                                 const gchar *trace_type)
@@ -130,6 +152,14 @@ build_full_foreach (const gchar *trace_type,
         g_string_append_printf (*built, "\r\n%s", trace);
 }
 
+/**
+ * mm_location_gps_nmea_build_full:
+ * @self: a #MMLocationGpsNmea.
+ *
+ * Gets a compilation of all cached traces.
+ *
+ * Returns: (transfer full) a string containing all traces, or #NULL if none available. The returned value should be freed with g_free().
+ */
 gchar *
 mm_location_gps_nmea_build_full (MMLocationGpsNmea *self)
 {
diff --git a/libmm-glib/mm-location-gps-nmea.h b/libmm-glib/mm-location-gps-nmea.h
index 84f1dfdd..e0269da6 100644
--- a/libmm-glib/mm-location-gps-nmea.h
+++ b/libmm-glib/mm-location-gps-nmea.h
@@ -36,17 +36,36 @@ typedef struct _MMLocationGpsNmea MMLocationGpsNmea;
 typedef struct _MMLocationGpsNmeaClass MMLocationGpsNmeaClass;
 typedef struct _MMLocationGpsNmeaPrivate MMLocationGpsNmeaPrivate;
 
+/**
+ * MMLocationGpsNmea:
+ *
+ * The #MMLocationGpsNmea structure contains private data and should
+ * only be accessed using the provided API.
+ */
 struct _MMLocationGpsNmea {
+    /*< private >*/
     GObject parent;
     MMLocationGpsNmeaPrivate *priv;
 };
 
 struct _MMLocationGpsNmeaClass {
+    /*< private >*/
     GObjectClass parent;
 };
 
 GType mm_location_gps_nmea_get_type (void);
 
+const gchar *mm_location_gps_nmea_get_trace (MMLocationGpsNmea *self,
+                                             const gchar *trace_type);
+gchar *mm_location_gps_nmea_build_full (MMLocationGpsNmea *self);
+
+/*****************************************************************************/
+/* ModemManager/libmm-glib/mmcli specific methods */
+
+#if defined (_LIBMM_INSIDE_MM) ||    \
+    defined (_LIBMM_INSIDE_MMCLI) || \
+    defined (LIBMM_GLIB_COMPILATION)
+
 MMLocationGpsNmea *mm_location_gps_nmea_new (void);
 MMLocationGpsNmea *mm_location_gps_nmea_new_from_string_variant (GVariant *string,
                                                                  GError **error);
@@ -54,10 +73,6 @@ MMLocationGpsNmea *mm_location_gps_nmea_new_from_string_variant (GVariant *strin
 gboolean mm_location_gps_nmea_add_trace (MMLocationGpsNmea *self,
                                          const gchar *trace);
 
-const gchar *mm_location_gps_nmea_get_trace (MMLocationGpsNmea *self,
-                                             const gchar *trace_type);
-gchar *mm_location_gps_nmea_build_full (MMLocationGpsNmea *self);
-
 GVariant *mm_location_gps_nmea_get_string_variant (MMLocationGpsNmea *self);
 
 G_END_DECLS