libmm-glib: Fix and add introspection annotations

Bug #705641.

13 files changed, 78 insertions, 27 deletions

diff --git a/libmm-glib/mm-bearer-ip-config.c b/libmm-glib/mm-bearer-ip-config.c
index 14f99f34..e436c392 100644
--- a/libmm-glib/mm-bearer-ip-config.c
+++ b/libmm-glib/mm-bearer-ip-config.c
@@ -139,7 +139,7 @@ mm_bearer_ip_config_set_prefix (MMBearerIpConfig *self,
  *
  * Gets the list of IP addresses of DNS servers to be used with this bearer.
  *
- * Returns: a NULL-terminated array of strings. Do not free the returned value, it is owned by @self.
+ * Returns: (transfer none) (array zero-terminated=1): a NULL-terminated array of strings. Do not free the returned value, it is owned by @self.
  */
 const gchar **
 mm_bearer_ip_config_get_dns (MMBearerIpConfig *self)
@@ -331,6 +331,14 @@ mm_bearer_ip_config_new_from_dictionary (GVariant *dictionary,
 
 /*****************************************************************************/
 
+/**
+ * mm_bearer_ip_config_dup:
+ * @orig: a #MMBearerIpConfig
+ *
+ * Creates a copy of @orig.
+ *
+ * Returns: (transfer full): a newly created #MMBearerIpConfig
+ */
 MMBearerIpConfig *
 mm_bearer_ip_config_dup (MMBearerIpConfig *orig)
 {
diff --git a/libmm-glib/mm-bearer-properties.c b/libmm-glib/mm-bearer-properties.c
index c4f4ba2f..c864f8e8 100644
--- a/libmm-glib/mm-bearer-properties.c
+++ b/libmm-glib/mm-bearer-properties.c
@@ -408,6 +408,16 @@ mm_bearer_properties_get_dictionary (MMBearerProperties *self)
 
 /*****************************************************************************/
 
+
+/**
+ * mm_bearer_properties_consume_string:
+ * @self: a #MMBearerProperties
+ * @key:
+ * @value:
+ * @error: (allow-none): Return location for error or %NULL.
+ *
+ * Returns: %TRUE if the operation succeded, %FALSE if @error is set.
+ */
 gboolean
 mm_bearer_properties_consume_string (MMBearerProperties *self,
                                      const gchar *key,
@@ -517,6 +527,15 @@ mm_bearer_properties_new_from_string (const gchar *str,
 
 /*****************************************************************************/
 
+/**
+ * mm_bearer_properties_consume_variant:
+ * @properties: a #MMBearerProperties
+ * @key:
+ * @value: a #GVariant
+ * @error: (allow-none): Return location for error or %NULL.
+ *
+ * Returns: %TRUE if the operation succeded, %FALSE if @error is set.
+ */
 gboolean
 mm_bearer_properties_consume_variant (MMBearerProperties *properties,
                                       const gchar *key,
@@ -613,6 +632,14 @@ mm_bearer_properties_new_from_dictionary (GVariant *dictionary,
 
 /*****************************************************************************/
 
+/**
+ * mm_bearer_properties_dup:
+ * @orig: a #MMBearerProperties
+ *
+ * Creates a copy of @orig.
+ *
+ * Returns: (transfer full): a newly created #MMBearerProperties
+ */
 MMBearerProperties *
 mm_bearer_properties_dup (MMBearerProperties *orig)
 {
diff --git a/libmm-glib/mm-bearer-properties.h b/libmm-glib/mm-bearer-properties.h
index 852d16e6..361c8678 100644
--- a/libmm-glib/mm-bearer-properties.h
+++ b/libmm-glib/mm-bearer-properties.h
@@ -102,7 +102,7 @@ gboolean mm_bearer_properties_consume_string (MMBearerProperties *self,
                                               const gchar *value,
                                               GError **error);
 
-gboolean mm_bearer_properties_consume_variant (MMBearerProperties *self,
+gboolean mm_bearer_properties_consume_variant (MMBearerProperties *properties,
                                                const gchar *key,
                                                GVariant *value,
                                                GError **error);
diff --git a/libmm-glib/mm-modem-3gpp.c b/libmm-glib/mm-modem-3gpp.c
index 40c7e862..c0a98bb1 100644
--- a/libmm-glib/mm-modem-3gpp.c
+++ b/libmm-glib/mm-modem-3gpp.c
@@ -499,7 +499,7 @@ create_networks_list (GVariant *variant)
  *
  * Finishes an operation started with mm_modem_3gpp_scan().
  *
- * Returns: a list of #MMModem3gppNetwork structs, or #NULL if @error is set. The returned value should be freed with g_list_free_full() using mm_modem_3gpp_network_free() as #GDestroyNotify function.
+ * Returns: (transfer full) (element-type ModemManager.Modem3gppNetwork): a list of #MMModem3gppNetwork structs, or #NULL if @error is set. The returned value should be freed with g_list_free_full() using mm_modem_3gpp_network_free() as #GDestroyNotify function.
  */
 GList *
 mm_modem_3gpp_scan_finish (MMModem3gpp *self,
@@ -552,7 +552,7 @@ mm_modem_3gpp_scan (MMModem3gpp *self,
  * The calling thread is blocked until a reply is received. See mm_modem_3gpp_scan()
  * for the asynchronous version of this method.
  *
- * Returns: a list of #MMModem3gppNetwork structs, or #NULL if @error is set. The returned value should be freed with g_list_free_full() using mm_modem_3gpp_network_free() as #GDestroyNotify function.
+ * Returns:  (transfer full) (element-type ModemManager.Modem3gppNetwork):  a list of #MMModem3gppNetwork structs, or #NULL if @error is set. The returned value should be freed with g_list_free_full() using mm_modem_3gpp_network_free() as #GDestroyNotify function.
  */
 GList *
 mm_modem_3gpp_scan_sync (MMModem3gpp *self,
diff --git a/libmm-glib/mm-modem-firmware.c b/libmm-glib/mm-modem-firmware.c
index c52f3160..0bc6c6bd 100644
--- a/libmm-glib/mm-modem-firmware.c
+++ b/libmm-glib/mm-modem-firmware.c
@@ -245,7 +245,7 @@ build_results (const gchar *str_selected,
  * mm_modem_firmware_list_finish:
  * @self: A #MMModemFirmware.
  * @selected: (out) (allow-none) (transfer full): The selected firmware slot, or NULL if no slot is selected (such as if all slots are empty, or no slots exist). The returned value should be freed with g_object_unref().
- * @installed: (out) (allow-none) (transfer full): A list of #MMFirmwareProperties objects specifying the installed images. The returned value should be freed with g_list_free_full() using g_object_unref() as #GDestroyNotify.
+ * @installed: (out) (allow-none) (transfer full) (element-type ModemManager.FirmwareProperties): A list of #MMFirmwareProperties objects specifying the installed images. The returned value should be freed with g_list_free_full() using g_object_unref() as #GDestroyNotify.
  * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to mm_modem_firmware_list().
  * @error: Return location for error or %NULL.
  *
@@ -321,7 +321,7 @@ mm_modem_firmware_list (MMModemFirmware *self,
  * mm_modem_firmware_list_sync:
  * @self: A #MMModemFirmware.
  * @selected: (out) (allow-none) (transfer full): The selected firmware slot, or NULL if no slot is selected (such as if all slots are empty, or no slots exist). The returned value should be freed with g_object_unref().
- * @installed: (out) (allow-none) (transfer full): A list of #MMFirmwareProperties objects specifying the installed images. The returned value should be freed with g_list_free_full() using g_object_unref() as #GDestroyNotify.
+ * @installed: (out) (allow-none) (transfer full) (element-type ModemManager.FirmwareProperties): A list of #MMFirmwareProperties objects specifying the installed images. The returned value should be freed with g_list_free_full() using g_object_unref() as #GDestroyNotify.
  * @cancellable: (allow-none): A #GCancellable or %NULL.
  * @error: Return firmware for error or %NULL.
  *
diff --git a/libmm-glib/mm-modem-location.c b/libmm-glib/mm-modem-location.c
index 1e5541a7..6df83c21 100644
--- a/libmm-glib/mm-modem-location.c
+++ b/libmm-glib/mm-modem-location.c
@@ -101,7 +101,7 @@ mm_modem_location_get_capabilities (MMModemLocation *self)
 /*****************************************************************************/
 
 /**
- * mm_modem_location_get_capabilities:
+ * mm_modem_location_get_enabled:
  * @self: A #MMModemLocation.
  *
  * Gets a bitmask of the location capabilities which are enabled in this #MMModemLocation.
diff --git a/libmm-glib/mm-modem-messaging.c b/libmm-glib/mm-modem-messaging.c
index 50c525c8..e81c6bdb 100644
--- a/libmm-glib/mm-modem-messaging.c
+++ b/libmm-glib/mm-modem-messaging.c
@@ -255,7 +255,7 @@ list_sms_context_complete_and_free (ListSmsContext *ctx)
  *
  * Finishes an operation started with mm_modem_messaging_list().
  *
- * Returns: (element-type MM.Sms) (transfer full): A list of #MMSms objects, or #NULL if either not found or @error is set. The returned value should be freed with g_list_free_full() using g_object_unref() as #GDestroyNotify function.
+ * Returns: (element-type ModemManager.Sms) (transfer full): A list of #MMSms objects, or #NULL if either not found or @error is set. The returned value should be freed with g_list_free_full() using g_object_unref() as #GDestroyNotify function.
  */
 GList *
 mm_modem_messaging_list_finish (MMModemMessaging *self,
@@ -407,7 +407,7 @@ mm_modem_messaging_list (MMModemMessaging *self,
  * The calling thread is blocked until a reply is received. See mm_modem_messaging_list()
  * for the asynchronous version of this method.
  *
- * Returns: (element-type MM.Sms) (transfer full): A list of #MMSms objects, or #NULL if either not found or @error is set. The returned value should be freed with g_list_free_full() using g_object_unref() as #GDestroyNotify function.
+ * Returns: (element-type MMSms) (transfer full): A list of #MMSms objects, or #NULL if either not found or @error is set. The returned value should be freed with g_list_free_full() using g_object_unref() as #GDestroyNotify function.
  */
 GList *
 mm_modem_messaging_list_sync (MMModemMessaging *self,
@@ -598,7 +598,7 @@ mm_modem_messaging_create (MMModemMessaging *self,
 }
 
 /**
- * mm_modem_create_sms_sync:
+ * mm_modem_messaging_create_sync:
  * @self: A #MMModemMessaging.
  * @properties: A ##MMSmsProperties object with the properties to use.
  * @cancellable: (allow-none): A #GCancellable or %NULL.
diff --git a/libmm-glib/mm-modem-time.c b/libmm-glib/mm-modem-time.c
index c2d16d44..a8331ecd 100644
--- a/libmm-glib/mm-modem-time.c
+++ b/libmm-glib/mm-modem-time.c
@@ -97,7 +97,7 @@ mm_modem_time_dup_path (MMModemTime *self)
  *
  * Finishes an operation started with mm_modem_time_get_network_time().
  *
- * Returns: A string containing the network time, or %NULL if @error is set. The returned value should be freed with g_free().
+ * Returns: (transfer full): A string containing the network time, or %NULL if @error is set. The returned value should be freed with g_free().
  */
 gchar *
 mm_modem_time_get_network_time_finish (MMModemTime *self,
@@ -153,7 +153,7 @@ mm_modem_time_get_network_time (MMModemTime *self,
  * The calling thread is blocked until a reply is received. See mm_modem_time_get_network_time()
  * for the asynchronous version of this method.
  *
- * Returns: A string containing the network time, or %NULL if @error is set. The returned value should be freed with g_free().
+ * Returns: (transfer full): A string containing the network time, or %NULL if @error is set. The returned value should be freed with g_free().
  */
 gchar *
 mm_modem_time_get_network_time_sync (MMModemTime *self,
@@ -221,8 +221,8 @@ ensure_internal_timezone (MMModemTime *self,
 }
 
 /**
- * mm_modem_get_network_timezone:
- * @self: A #MMModem.
+ * mm_modem_time_get_network_timezone:
+ * @self: A #MMModemTime.
  *
  * Gets the network timezone information.
  *
@@ -231,7 +231,7 @@ ensure_internal_timezone (MMModemTime *self,
  * mm_modem_get_network_timezone() again to get a new #MMNetworkTimezone with the
  * new values.</warning>
  *
- * Returns: (transfer full) A #MMNetworkTimezone that must be freed with g_object_unref() or %NULL if unknown.
+ * Returns: (transfer full): A #MMNetworkTimezone that must be freed with g_object_unref() or %NULL if unknown.
  */
 MMNetworkTimezone *
 mm_modem_time_get_network_timezone (MMModemTime *self)
@@ -245,8 +245,8 @@ mm_modem_time_get_network_timezone (MMModemTime *self)
 }
 
 /**
- * mm_modem_peek_network_timezone:
- * @self: A #MMModem.
+ * mm_modem_time_peek_network_timezone:
+ * @self: A #MMModemTime.
  *
  * Gets the network timezone information.
  *
@@ -255,7 +255,7 @@ mm_modem_time_get_network_timezone (MMModemTime *self)
  * @self was constructed. Use mm_modem_get_network_timezone() if on another
  * thread.</warning>
  *
- * Returns: (transfer none) A #MMNetworkTimezone. Do not free the returned value, it belongs to @self.
+ * Returns: (transfer none): A #MMNetworkTimezone. Do not free the returned value, it belongs to @self.
  */
 MMNetworkTimezone *
 mm_modem_time_peek_network_timezone (MMModemTime *self)
diff --git a/libmm-glib/mm-modem.c b/libmm-glib/mm-modem.c
index 410b5593..fdd68335 100644
--- a/libmm-glib/mm-modem.c
+++ b/libmm-glib/mm-modem.c
@@ -758,7 +758,7 @@ ensure_internal_ports (MMModem *self,
 /**
  * mm_modem_peek_current_ports:
  * @self: A #MMModem.
- * @ports: (out) (array length=n_ports): Return location for the array of #MMModemPortInfo values. Do not free the returned value, it is owned by @self.
+ * @ports: (out) (array length=n_ports) (transfer none): Return location for the array of #MMModemPortInfo values. Do not free the returned value, it is owned by @self.
  * @n_ports: (out): Return location for the number of values in @ports.
  *
  * Gets the list of ports in the modem.
@@ -1510,7 +1510,7 @@ mm_modem_get_current_bands (MMModem *self,
 /**
  * mm_modem_peek_current_bands:
  * @self: A #MMModem.
- * @bands: (out) (array length=n_storages): Return location for the array of #MMModemBand values. Do not free the returned value, it is owned by @self.
+ * @bands: (out) (array length=n_bands): Return location for the array of #MMModemBand values. Do not free the returned value, it is owned by @self.
  * @n_bands: (out): Return location for the number of values in @bands.
  *
  * Gets the list of radio frequency and technology bands the #MMModem is currently
@@ -1740,7 +1740,7 @@ list_bearers_context_complete_and_free (ListBearersContext *ctx)
  *
  * Finishes an operation started with mm_modem_list_bearers().
  *
- * Returns: (transfer full): The list of #MMBearer objects, or %NULL if either none found or if @error is set.
+ * Returns: (transfer full) (element-type ModemManager.Modem): The list of #MMBearer objects, or %NULL if either none found or if @error is set.
  */
 GList *
 mm_modem_list_bearers_finish (MMModem *self,
@@ -1892,7 +1892,7 @@ mm_modem_list_bearers (MMModem *self,
  * The calling thread is blocked until a reply is received. See mm_modem_list_bearers()
  * for the asynchronous version of this method.
  *
- * Returns: (transfer full): The list of #MMBearer objects, or %NULL if either none found or if @error is set.
+ * Returns: (transfer full) (element-type ModemManager.Modem): The list of #MMBearer objects, or %NULL if either none found or if @error is set.
  */
 GList *
 mm_modem_list_bearers_sync (MMModem *self,
@@ -2802,7 +2802,7 @@ mm_modem_set_current_bands_sync (MMModem *self,
  *
  * Finishes an operation started with mm_modem_get_sim().
  *
- * Returns: a #MMSim or #NULL if none available. The returned value should be freed with g_object_unref().
+ * Returns: (transfer full): a #MMSim or #NULL if none available. The returned value should be freed with g_object_unref().
  */
 MMSim *
 mm_modem_get_sim_finish (MMModem *self,
@@ -2906,7 +2906,7 @@ mm_modem_get_sim (MMModem *self,
  * The calling thread is blocked until a reply is received. See mm_modem_get_sim()
  * for the asynchronous version of this method.
  *
- * Returns: a #MMSim or #NULL if none available. The returned value should be freed with g_object_unref().
+ * Returns: (transfer full): a #MMSim or #NULL if none available. The returned value should be freed with g_object_unref().
  */
 MMSim *
 mm_modem_get_sim_sync (MMModem *self,
diff --git a/libmm-glib/mm-simple-connect-properties.c b/libmm-glib/mm-simple-connect-properties.c
index f57cc4f0..200b7c38 100644
--- a/libmm-glib/mm-simple-connect-properties.c
+++ b/libmm-glib/mm-simple-connect-properties.c
@@ -363,6 +363,14 @@ mm_simple_connect_properties_get_number (MMSimpleConnectProperties *self)
 
 /*****************************************************************************/
 
+/**
+ * mm_simple_connect_properties_get_bearer_properties:
+ * @self: a #MMSimpleConnectProperties:
+ *
+ * Returns the bearer properties of @self.
+ *
+ * Returns: (transfer full): a #MMBearerProperties
+ */
 MMBearerProperties *
 mm_simple_connect_properties_get_bearer_properties (MMSimpleConnectProperties *self)
 {
diff --git a/libmm-glib/mm-simple-connect-properties.h b/libmm-glib/mm-simple-connect-properties.h
index e9c09ae3..3167db0a 100644
--- a/libmm-glib/mm-simple-connect-properties.h
+++ b/libmm-glib/mm-simple-connect-properties.h
@@ -100,7 +100,7 @@ MMSimpleConnectProperties *mm_simple_connect_properties_new_from_string (const g
 MMSimpleConnectProperties *mm_simple_connect_properties_new_from_dictionary (GVariant *dictionary,
                                                                              GError **error);
 
-MMBearerProperties *mm_simple_connect_properties_get_bearer_properties (MMSimpleConnectProperties *properties);
+MMBearerProperties *mm_simple_connect_properties_get_bearer_properties (MMSimpleConnectProperties *self);
 
 GVariant *mm_simple_connect_properties_get_dictionary (MMSimpleConnectProperties *self);
 #endif
diff --git a/libmm-glib/mm-sms-properties.c b/libmm-glib/mm-sms-properties.c
index bac363aa..5294112d 100644
--- a/libmm-glib/mm-sms-properties.c
+++ b/libmm-glib/mm-sms-properties.c
@@ -708,6 +708,14 @@ mm_sms_properties_new_from_dictionary (GVariant *dictionary,
 
 /*****************************************************************************/
 
+/**
+ * mm_sms_properties_dup:
+ * @orig: a #MMSmsProperties
+ *
+ * Returns a copy of @orig.
+ *
+ * Returns: (transfer full): a #MMSmsProperties
+ */
 MMSmsProperties *
 mm_sms_properties_dup (MMSmsProperties *orig)
 {
diff --git a/libmm-glib/mm-unlock-retries.c b/libmm-glib/mm-unlock-retries.c
index 4ce6c324..0901fb65 100644
--- a/libmm-glib/mm-unlock-retries.c
+++ b/libmm-glib/mm-unlock-retries.c
@@ -112,8 +112,8 @@ 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.
+ * @callback: (scope call): callback to call for each available lock.
+ * @user_data: (closure) data to pass to @callback.
  *
  * Executes @callback for each lock information found in @self.
  */