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

3 files changed, 94 insertions, 7 deletions

diff --git a/libmm-glib/mm-location-gps-nmea.h b/libmm-glib/mm-location-gps-nmea.h
index e0269da6..3317074b 100644
--- a/libmm-glib/mm-location-gps-nmea.h
+++ b/libmm-glib/mm-location-gps-nmea.h
@@ -75,6 +75,8 @@ gboolean mm_location_gps_nmea_add_trace (MMLocationGpsNmea *self,
 
 GVariant *mm_location_gps_nmea_get_string_variant (MMLocationGpsNmea *self);
 
+#endif
+
 G_END_DECLS
 
 #endif /* MM_LOCATION_GPS_NMEA_H */
diff --git a/libmm-glib/mm-location-gps-raw.c b/libmm-glib/mm-location-gps-raw.c
index 47eae14b..d6b93997 100644
--- a/libmm-glib/mm-location-gps-raw.c
+++ b/libmm-glib/mm-location-gps-raw.c
@@ -21,6 +21,19 @@
 #include "mm-errors-types.h"
 #include "mm-location-gps-raw.h"
 
+/**
+ * SECTION: mm-location-gps-raw
+ * @title: MMLocationGpsRaw
+ * @short_description: Helper object to handle generic GPS location information.
+ *
+ * The #MMLocationGpsRaw 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_raw(),
+ * mm_modem_location_get_gps_raw_sync(), mm_modem_location_get_full() or
+ * mm_modem_location_get_full_sync().
+ */
+
 G_DEFINE_TYPE (MMLocationGpsRaw, mm_location_gps_raw, G_TYPE_OBJECT);
 
 #define PROPERTY_UTC_TIME  "utc-time"
@@ -39,6 +52,14 @@ struct _MMLocationGpsRawPrivate {
 
 /*****************************************************************************/
 
+/**
+ * mm_location_gps_raw_get_utc_time:
+ * @self: a #MMLocationGpsRaw.
+ *
+ * Gets the UTC time of the location being reported.
+ *
+ * Returns: a string with the UTC time, or #NULL if unknown. Do not free the returned value, it is owned by @self.
+ */
 const gchar *
 mm_location_gps_raw_get_utc_time (MMLocationGpsRaw *self)
 {
@@ -47,6 +68,16 @@ mm_location_gps_raw_get_utc_time (MMLocationGpsRaw *self)
     return self->priv->utc_time;
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_location_gps_raw_get_longitude:
+ * @self: a #MMLocationGpsRaw.
+ *
+ * Gets the longitude, in the [-180,180] range.
+ *
+ * Returns: the longitude, or %MM_LOCATION_GPS_RAW_LONGITUDE_UNKNOWN if unknown.
+ */
 gdouble
 mm_location_gps_raw_get_longitude (MMLocationGpsRaw *self)
 {
@@ -56,6 +87,16 @@ mm_location_gps_raw_get_longitude (MMLocationGpsRaw *self)
     return self->priv->longitude;
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_location_gps_raw_get_latitude:
+ * @self: a #MMLocationGpsRaw.
+ *
+ * Gets the latitude, in the [-90,90] range.
+ *
+ * Returns: the latitude, or %MM_LOCATION_GPS_RAW_LATITUDE_UNKNOWN if unknown.
+ */
 gdouble
 mm_location_gps_raw_get_latitude (MMLocationGpsRaw *self)
 {
@@ -65,6 +106,16 @@ mm_location_gps_raw_get_latitude (MMLocationGpsRaw *self)
     return self->priv->latitude;
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_location_gps_raw_get_altitude:
+ * @self: a #MMLocationGpsRaw.
+ *
+ * Gets the altitude, in the [-90,90] range.
+ *
+ * Returns: the altitude, or %MM_LOCATION_GPS_RAW_ALTITUDE_UNKNOWN if unknown.
+ */
 gdouble
 mm_location_gps_raw_get_altitude (MMLocationGpsRaw *self)
 {
diff --git a/libmm-glib/mm-location-gps-raw.h b/libmm-glib/mm-location-gps-raw.h
index f566f483..3ec0b29d 100644
--- a/libmm-glib/mm-location-gps-raw.h
+++ b/libmm-glib/mm-location-gps-raw.h
@@ -32,43 +32,77 @@ G_BEGIN_DECLS
 #define MM_IS_LOCATION_GPS_RAW_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass),  MM_TYPE_LOCATION_GPS_RAW))
 #define MM_LOCATION_GPS_RAW_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj),  MM_TYPE_LOCATION_GPS_RAW, MMLocationGpsRawClass))
 
-
-/* Proper longitude values will fall in the [-180,180] range
- * Proper latitude values will fall in the [-90,90] range
+/**
+ * MM_LOCATION_GPS_RAW_LONGITUDE_UNKNOWN:
+ *
+ * Identifier for an unknown longitude value.
+ *
+ * Proper longitude values fall in the [-180,180] range.
  */
 #define MM_LOCATION_GPS_RAW_LONGITUDE_UNKNOWN G_MINDOUBLE
+
+/**
+ * MM_LOCATION_GPS_RAW_LATITUDE_UNKNOWN:
+ *
+ * Identifier for an unknown latitude value.
+ *
+ * Proper latitude values fall in the [-90,90] range.
+ */
 #define MM_LOCATION_GPS_RAW_LATITUDE_UNKNOWN  G_MINDOUBLE
+
+/**
+ * MM_LOCATION_GPS_RAW_ALTITUDE_UNKNOWN:
+ *
+ * Identifier for an unknown altitude value.
+ */
 #define MM_LOCATION_GPS_RAW_ALTITUDE_UNKNOWN  G_MINDOUBLE
 
 typedef struct _MMLocationGpsRaw MMLocationGpsRaw;
 typedef struct _MMLocationGpsRawClass MMLocationGpsRawClass;
 typedef struct _MMLocationGpsRawPrivate MMLocationGpsRawPrivate;
 
+/**
+ * MMLocationGpsRaw:
+ *
+ * The #MMLocationGpsRaw structure contains private data and should
+ * only be accessed using the provided API.
+ */
 struct _MMLocationGpsRaw {
+    /*< private >*/
     GObject parent;
     MMLocationGpsRawPrivate *priv;
 };
 
 struct _MMLocationGpsRawClass {
+    /*< private >*/
     GObjectClass parent;
 };
 
 GType mm_location_gps_raw_get_type (void);
 
-MMLocationGpsRaw *mm_location_gps_raw_new (void);
-MMLocationGpsRaw *mm_location_gps_raw_new_from_dictionary (GVariant *string,
-                                                           GError **error);
-
 const gchar *mm_location_gps_raw_get_utc_time  (MMLocationGpsRaw *self);
 gdouble      mm_location_gps_raw_get_longitude (MMLocationGpsRaw *self);
 gdouble      mm_location_gps_raw_get_latitude  (MMLocationGpsRaw *self);
 gdouble      mm_location_gps_raw_get_altitude  (MMLocationGpsRaw *self);
 
+/*****************************************************************************/
+/* ModemManager/libmm-glib/mmcli specific methods */
+
+#if defined (_LIBMM_INSIDE_MM) ||    \
+    defined (_LIBMM_INSIDE_MMCLI) || \
+    defined (LIBMM_GLIB_COMPILATION)
+
+MMLocationGpsRaw *mm_location_gps_raw_new (void);
+MMLocationGpsRaw *mm_location_gps_raw_new_from_dictionary (GVariant *string,
+                                                           GError **error);
+
 gboolean mm_location_gps_raw_add_trace (MMLocationGpsRaw *self,
                                         const gchar *trace);
 
 GVariant *mm_location_gps_raw_get_dictionary (MMLocationGpsRaw *self);
 
+#endif
+
 G_END_DECLS
 
 #endif /* MM_LOCATION_GPS_RAW_H */