libmm-glib,bearer-properties: improve documentation

2 files changed, 221 insertions, 68 deletions

diff --git a/libmm-glib/mm-bearer-properties.c b/libmm-glib/mm-bearer-properties.c
index ab7d4408..2ebe81cc 100644
--- a/libmm-glib/mm-bearer-properties.c
+++ b/libmm-glib/mm-bearer-properties.c
@@ -19,6 +19,18 @@
 #include "mm-common-helpers.h"
 #include "mm-bearer-properties.h"
 
+/**
+ * SECTION: mm-bearer-properties
+ * @title: MMBearerProperties
+ * @short_description: Helper object to handle bearer properties.
+ *
+ * The #MMBearerProperties is an object handling the properties requested
+ * to ModemManager when creating a new bearer.
+ *
+ * This object is created by the user and passed to ModemManager with either
+ * mm_modem_create_bearer() or mm_modem_create_bearer_sync().
+ */
+
 G_DEFINE_TYPE (MMBearerProperties, mm_bearer_properties, G_TYPE_OBJECT);
 
 #define PROPERTY_APN             "apn"
@@ -49,6 +61,13 @@ struct _MMBearerPropertiesPrivate {
 
 /*****************************************************************************/
 
+/**
+ * mm_bearer_properties_set_apn:
+ * @self: a #MMBearerProperties.
+ * @apn: Name of the access point.
+ *
+ * Sets the name of the access point to use when connecting.
+ */
 void
 mm_bearer_properties_set_apn (MMBearerProperties *self,
                               const gchar *apn)
@@ -59,6 +78,31 @@ mm_bearer_properties_set_apn (MMBearerProperties *self,
     self->priv->apn = g_strdup (apn);
 }
 
+/**
+ * mm_bearer_properties_get_apn:
+ * @self: a #MMBearerProperties.
+ *
+ * Gets the name of the access point to use when connecting.
+ *
+ * Returns: (transfer none): the access point, or #NULL if not set. Do not free the returned value, it is owned by @self.
+ */
+const gchar *
+mm_bearer_properties_get_apn (MMBearerProperties *self)
+{
+    g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), NULL);
+
+    return self->priv->apn;
+}
+
+/*****************************************************************************/
+
+/**
+ * mm_bearer_properties_set_user:
+ * @self: a #MMBearerProperties.
+ * @user: the username
+ *
+ * Sets the username used to authenticate with the access point.
+ */
 void
 mm_bearer_properties_set_user (MMBearerProperties *self,
                                const gchar *user)
@@ -69,6 +113,31 @@ mm_bearer_properties_set_user (MMBearerProperties *self,
     self->priv->user = g_strdup (user);
 }
 
+/**
+ * mm_bearer_properties_get_user:
+ * @self: a #MMBearerProperties.
+ *
+ * Gets the username used to authenticate with the access point.
+ *
+ * Returns: (transfer none): the username, or #NULL if not set. Do not free the returned value, it is owned by @self.
+ */
+const gchar *
+mm_bearer_properties_get_user (MMBearerProperties *self)
+{
+    g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), NULL);
+
+    return self->priv->user;
+}
+
+/*****************************************************************************/
+
+/**
+ * mm_bearer_properties_set_password:
+ * @self: a #MMBearerProperties.
+ * @password: the password
+ *
+ * Sets the password used to authenticate with the access point.
+ */
 void
 mm_bearer_properties_set_password (MMBearerProperties *self,
                                    const gchar *password)
@@ -79,6 +148,31 @@ mm_bearer_properties_set_password (MMBearerProperties *self,
     self->priv->password = g_strdup (password);
 }
 
+/**
+ * mm_bearer_properties_get_password:
+ * @self: a #MMBearerProperties.
+ *
+ * Gets the password used to authenticate with the access point.
+ *
+ * Returns: (transfer none): the password, or #NULL if not set. Do not free the returned value, it is owned by @self.
+ */
+const gchar *
+mm_bearer_properties_get_password (MMBearerProperties *self)
+{
+    g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), NULL);
+
+    return self->priv->password;
+}
+
+/*****************************************************************************/
+
+/**
+ * mm_bearer_properties_set_ip_type:
+ * @self: a #MMBearerProperties.
+ * @ip_type: a #MMBearerIpFamily.
+ *
+ * Sets the IP type to use.
+ */
 void
 mm_bearer_properties_set_ip_type (MMBearerProperties *self,
                                   MMBearerIpFamily ip_type)
@@ -88,85 +182,119 @@ mm_bearer_properties_set_ip_type (MMBearerProperties *self,
     self->priv->ip_type = ip_type;
 }
 
-void
-mm_bearer_properties_set_allow_roaming (MMBearerProperties *self,
-                                        gboolean allow_roaming)
+/**
+ * mm_bearer_properties_get_ip_type:
+ * @self: a #MMBearerProperties.
+ *
+ * Sets the IP type to use.
+ *
+ * Returns: a #MMBearerIpFamily.
+ */
+MMBearerIpFamily
+mm_bearer_properties_get_ip_type (MMBearerProperties *self)
 {
-    g_return_if_fail (MM_IS_BEARER_PROPERTIES (self));
+    g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), MM_BEARER_IP_FAMILY_UNKNOWN);
 
-    self->priv->allow_roaming = allow_roaming;
-    self->priv->allow_roaming_set = TRUE;
+    return self->priv->ip_type;
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_bearer_properties_set_allow_roaming:
+ * @self: a #MMBearerProperties.
+ * @allow_roaming: boolean value.
+ *
+ * Sets the flag to indicate whether roaming is allowed or not in the
+ * connection.
+ */
 void
-mm_bearer_properties_set_number (MMBearerProperties *self,
-                                 const gchar *number)
+mm_bearer_properties_set_allow_roaming (MMBearerProperties *self,
+                                        gboolean allow_roaming)
 {
     g_return_if_fail (MM_IS_BEARER_PROPERTIES (self));
 
-    g_free (self->priv->number);
-    self->priv->number = g_strdup (number);
+    self->priv->allow_roaming = allow_roaming;
+    self->priv->allow_roaming_set = TRUE;
 }
 
-void
-mm_bearer_properties_set_rm_protocol (MMBearerProperties *self,
-                                      MMModemCdmaRmProtocol protocol)
+/**
+ * mm_bearer_properties_get_allow_roaming:
+ * @self: a #MMBearerProperties.
+ *
+ * Checks whether roaming is allowed in the connection.
+ *
+ * Returns: %TRUE if roaming is allowed, %FALSE otherwise..
+ */
+gboolean
+mm_bearer_properties_get_allow_roaming (MMBearerProperties *self)
 {
-    g_return_if_fail (MM_IS_BEARER_PROPERTIES (self));
+    g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), FALSE);
 
-    self->priv->rm_protocol = protocol;
+    return self->priv->allow_roaming;
 }
 
 /*****************************************************************************/
 
-const gchar *
-mm_bearer_properties_get_apn (MMBearerProperties *self)
-{
-    g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), NULL);
-
-    return self->priv->apn;
-}
-
-const gchar *
-mm_bearer_properties_get_user (MMBearerProperties *self)
+/**
+ * mm_bearer_properties_set_number:
+ * @self: a #MMBearerProperties.
+ * @number: the number.
+ *
+ * Sets the number to use when performing the connection.
+ */
+void
+mm_bearer_properties_set_number (MMBearerProperties *self,
+                                 const gchar *number)
 {
-    g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), NULL);
+    g_return_if_fail (MM_IS_BEARER_PROPERTIES (self));
 
-    return self->priv->user;
+    g_free (self->priv->number);
+    self->priv->number = g_strdup (number);
 }
 
+/**
+ * mm_bearer_properties_get_number:
+ * @self: a #MMBearerProperties.
+ *
+ * Gets the number to use when performing the connection.
+ *
+ * Returns: (transfer none): the number, or #NULL if not set. Do not free the returned value, it is owned by @self.
+ */
 const gchar *
-mm_bearer_properties_get_password (MMBearerProperties *self)
+mm_bearer_properties_get_number (MMBearerProperties *self)
 {
     g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), NULL);
 
-    return self->priv->password;
-}
-
-MMBearerIpFamily
-mm_bearer_properties_get_ip_type (MMBearerProperties *self)
-{
-    g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), MM_BEARER_IP_FAMILY_UNKNOWN);
-
-    return self->priv->ip_type;
+    return self->priv->number;
 }
 
-gboolean
-mm_bearer_properties_get_allow_roaming (MMBearerProperties *self)
-{
-    g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), FALSE);
-
-    return self->priv->allow_roaming;
-}
+/*****************************************************************************/
 
-const gchar *
-mm_bearer_properties_get_number (MMBearerProperties *self)
+/**
+ * mm_simple_connect_properties_set_rm_protocol:
+ * @self: a #MMBearerProperties.
+ * @protocol: a #MMModemCdmaRmProtocol.
+ *
+ * Sets the RM protocol to use in the CDMA connection.
+ */
+void
+mm_bearer_properties_set_rm_protocol (MMBearerProperties *self,
+                                      MMModemCdmaRmProtocol protocol)
 {
-    g_return_val_if_fail (MM_IS_BEARER_PROPERTIES (self), NULL);
+    g_return_if_fail (MM_IS_BEARER_PROPERTIES (self));
 
-    return self->priv->number;
+    self->priv->rm_protocol = protocol;
 }
 
+/**
+ * mm_bearer_properties_get_rm_protocol:
+ * @self: a #MMBearerProperties.
+ *
+ * Gets the RM protocol requested to use in the CDMA connection.
+ *
+ * Returns: a #MMModemCdmaRmProtocol.
+ */
 MMModemCdmaRmProtocol
 mm_bearer_properties_get_rm_protocol (MMBearerProperties *self)
 {
@@ -463,6 +591,13 @@ mm_bearer_properties_cmp (MMBearerProperties *a,
 
 /*****************************************************************************/
 
+/**
+ * mm_bearer_properties_new:
+ *
+ * Creates a new empty #MMBearerProperties.
+ *
+ * Returns: (transfer full): a #MMBearerProperties. The returned value should be freed with g_object_unref().
+ */
 MMBearerProperties *
 mm_bearer_properties_new (void)
 {
diff --git a/libmm-glib/mm-bearer-properties.h b/libmm-glib/mm-bearer-properties.h
index 74536d8d..633ee4b3 100644
--- a/libmm-glib/mm-bearer-properties.h
+++ b/libmm-glib/mm-bearer-properties.h
@@ -36,47 +36,63 @@ typedef struct _MMBearerProperties MMBearerProperties;
 typedef struct _MMBearerPropertiesClass MMBearerPropertiesClass;
 typedef struct _MMBearerPropertiesPrivate MMBearerPropertiesPrivate;
 
+/**
+ * MMBearerProperties:
+ *
+ * The #MMBearerProperties structure contains private data and should
+ * only be accessed using the provided API.
+ */
 struct _MMBearerProperties {
+    /*< private >*/
     GObject parent;
     MMBearerPropertiesPrivate *priv;
 };
 
 struct _MMBearerPropertiesClass {
+    /*< private >*/
     GObjectClass parent;
 };
 
 GType mm_bearer_properties_get_type (void);
 
 MMBearerProperties *mm_bearer_properties_new (void);
-MMBearerProperties *mm_bearer_properties_new_from_string (const gchar *str,
-                                                          GError **error);
-MMBearerProperties *mm_bearer_properties_new_from_dictionary (GVariant *dictionary,
-                                                              GError **error);
-
-MMBearerProperties *mm_bearer_properties_dup (MMBearerProperties *orig);
 
-void mm_bearer_properties_set_apn           (MMBearerProperties *properties,
+void mm_bearer_properties_set_apn           (MMBearerProperties *self,
                                              const gchar *apn);
-void mm_bearer_properties_set_user          (MMBearerProperties *properties,
+void mm_bearer_properties_set_user          (MMBearerProperties *self,
                                              const gchar *user);
-void mm_bearer_properties_set_password      (MMBearerProperties *properties,
+void mm_bearer_properties_set_password      (MMBearerProperties *self,
                                              const gchar *password);
-void mm_bearer_properties_set_ip_type       (MMBearerProperties *properties,
+void mm_bearer_properties_set_ip_type       (MMBearerProperties *self,
                                              MMBearerIpFamily ip_type);
-void mm_bearer_properties_set_allow_roaming (MMBearerProperties *properties,
+void mm_bearer_properties_set_allow_roaming (MMBearerProperties *self,
                                              gboolean allow_roaming);
-void mm_bearer_properties_set_number        (MMBearerProperties *properties,
+void mm_bearer_properties_set_number        (MMBearerProperties *self,
                                              const gchar *number);
-void mm_bearer_properties_set_rm_protocol   (MMBearerProperties *properties,
+void mm_bearer_properties_set_rm_protocol   (MMBearerProperties *self,
                                              MMModemCdmaRmProtocol protocol);
 
-const gchar           *mm_bearer_properties_get_apn           (MMBearerProperties *properties);
-const gchar           *mm_bearer_properties_get_user          (MMBearerProperties *properties);
-const gchar           *mm_bearer_properties_get_password      (MMBearerProperties *properties);
-MMBearerIpFamily       mm_bearer_properties_get_ip_type       (MMBearerProperties *properties);
-gboolean               mm_bearer_properties_get_allow_roaming (MMBearerProperties *properties);
-const gchar           *mm_bearer_properties_get_number        (MMBearerProperties *properties);
-MMModemCdmaRmProtocol  mm_bearer_properties_get_rm_protocol   (MMBearerProperties *properties);
+const gchar           *mm_bearer_properties_get_apn           (MMBearerProperties *self);
+const gchar           *mm_bearer_properties_get_user          (MMBearerProperties *self);
+const gchar           *mm_bearer_properties_get_password      (MMBearerProperties *self);
+MMBearerIpFamily       mm_bearer_properties_get_ip_type       (MMBearerProperties *self);
+gboolean               mm_bearer_properties_get_allow_roaming (MMBearerProperties *self);
+const gchar           *mm_bearer_properties_get_number        (MMBearerProperties *self);
+MMModemCdmaRmProtocol  mm_bearer_properties_get_rm_protocol   (MMBearerProperties *self);
+
+/*****************************************************************************/
+/* ModemManager/libmm-glib/mmcli specific methods */
+
+#if defined (_LIBMM_INSIDE_MM) ||    \
+    defined (_LIBMM_INSIDE_MMCLI) || \
+    defined (LIBMM_GLIB_COMPILATION)
+
+MMBearerProperties *mm_bearer_properties_new_from_string (const gchar *str,
+                                                          GError **error);
+MMBearerProperties *mm_bearer_properties_new_from_dictionary (GVariant *dictionary,
+                                                              GError **error);
+
+MMBearerProperties *mm_bearer_properties_dup (MMBearerProperties *orig);
 
 gboolean mm_bearer_properties_consume_string (MMBearerProperties *self,
                                               const gchar *key,
@@ -93,6 +109,8 @@ GVariant *mm_bearer_properties_get_dictionary (MMBearerProperties *self);
 gboolean mm_bearer_properties_cmp (MMBearerProperties *a,
                                    MMBearerProperties *b);
 
+#endif
+
 G_END_DECLS
 
 #endif /* MM_BEARER_PROPERTIES_H */