libmm-glib,bearer-ip-config: improve documentation

3 files changed, 129 insertions, 51 deletions

diff --git a/docs/reference/libmm-glib/libmm-glib-sections.txt b/docs/reference/libmm-glib/libmm-glib-sections.txt
index 5d2983f1..dba3b267 100644
--- a/docs/reference/libmm-glib/libmm-glib-sections.txt
+++ b/docs/reference/libmm-glib/libmm-glib-sections.txt
@@ -706,14 +706,14 @@ mm_bearer_get_type
 <FILE>mm-bearer-ip-config</FILE>
 <TITLE>MMBearerIpConfig</TITLE>
 MMBearerIpConfig
-MMBearerIpConfigClass
-mm_bearer_ip_config_dup
+<SUBSECTION Getters>
+mm_bearer_ip_config_get_method
 mm_bearer_ip_config_get_address
-mm_bearer_ip_config_get_dictionary
+mm_bearer_ip_config_get_prefix
 mm_bearer_ip_config_get_dns
 mm_bearer_ip_config_get_gateway
-mm_bearer_ip_config_get_method
-mm_bearer_ip_config_get_prefix
+<SUBSECTION Private>
+mm_bearer_ip_config_get_dictionary
 mm_bearer_ip_config_new
 mm_bearer_ip_config_new_from_dictionary
 mm_bearer_ip_config_set_address
@@ -721,7 +721,9 @@ mm_bearer_ip_config_set_dns
 mm_bearer_ip_config_set_gateway
 mm_bearer_ip_config_set_method
 mm_bearer_ip_config_set_prefix
+mm_bearer_ip_config_dup
 <SUBSECTION Standard>
+MMBearerIpConfigClass
 MMBearerIpConfigPrivate
 MM_BEARER_IP_CONFIG
 MM_BEARER_IP_CONFIG_CLASS
diff --git a/libmm-glib/mm-bearer-ip-config.c b/libmm-glib/mm-bearer-ip-config.c
index 06e7830e..14f99f34 100644
--- a/libmm-glib/mm-bearer-ip-config.c
+++ b/libmm-glib/mm-bearer-ip-config.c
@@ -18,6 +18,19 @@
 #include "mm-errors-types.h"
 #include "mm-bearer-ip-config.h"
 
+/**
+ * SECTION: mm-bearer-ip-config
+ * @title: MMBearerIpConfig
+ * @short_description: Helper object to handle IP configuration.
+ *
+ * The #MMBearerIpConfig is an object handling the IP configuration required by
+ * the bearer to finish the connection.
+ *
+ * This object is retrieved with either mm_bearer_get_ipv4_config(),
+ * mm_bearer_peek_ipv4_config(), mm_bearer_get_ipv6_config() or
+ * mm_bearer_peek_ipv6_config().
+ */
+
 G_DEFINE_TYPE (MMBearerIpConfig, mm_bearer_ip_config, G_TYPE_OBJECT);
 
 #define PROPERTY_METHOD  "method"
@@ -38,6 +51,22 @@ struct _MMBearerIpConfigPrivate {
 
 /*****************************************************************************/
 
+/**
+ * mm_bearer_ip_config_get_method:
+ * @self: a #MMBearerIpConfig.
+ *
+ * Gets the IP method to be used with this bearer.
+ *
+ * Returns: a #MMBearerIpMethod.
+ */
+MMBearerIpMethod
+mm_bearer_ip_config_get_method (MMBearerIpConfig *self)
+{
+    g_return_val_if_fail (MM_IS_BEARER_IP_CONFIG (self), MM_BEARER_IP_METHOD_UNKNOWN);
+
+    return self->priv->method;
+}
+
 void
 mm_bearer_ip_config_set_method (MMBearerIpConfig *self,
                                 MMBearerIpMethod method)
@@ -47,6 +76,24 @@ mm_bearer_ip_config_set_method (MMBearerIpConfig *self,
     self->priv->method = method;
 }
 
+/*****************************************************************************/
+
+/**
+ * mm_bearer_ip_config_get_address:
+ * @self: a #MMBearerIpConfig.
+ *
+ * Gets the IP address to be used with this bearer.
+ *
+ * Returns: a string with the IP address, or #NULL if unknown. Do not free the returned value, it is owned by @self.
+ */
+const gchar *
+mm_bearer_ip_config_get_address (MMBearerIpConfig *self)
+{
+    g_return_val_if_fail (MM_IS_BEARER_IP_CONFIG (self), NULL);
+
+    return self->priv->address;
+}
+
 void
 mm_bearer_ip_config_set_address (MMBearerIpConfig *self,
                                  const gchar *address)
@@ -57,69 +104,71 @@ mm_bearer_ip_config_set_address (MMBearerIpConfig *self,
     self->priv->address = g_strdup (address);
 }
 
-void
-mm_bearer_ip_config_set_prefix (MMBearerIpConfig *self,
-                                guint prefix)
-{
-    g_return_if_fail (MM_IS_BEARER_IP_CONFIG (self));
-
-    self->priv->prefix = prefix;
-}
+/*****************************************************************************/
 
-void
-mm_bearer_ip_config_set_dns (MMBearerIpConfig *self,
-                             const gchar **dns)
+/**
+ * mm_bearer_ip_config_get_prefix:
+ * @self: a #MMBearerIpConfig.
+ *
+ * Gets the network prefix to be used with this bearer.
+ *
+ * Returns: the network prefix.
+ */
+guint
+mm_bearer_ip_config_get_prefix (MMBearerIpConfig *self)
 {
-    g_return_if_fail (MM_IS_BEARER_IP_CONFIG (self));
+    g_return_val_if_fail (MM_IS_BEARER_IP_CONFIG (self), 0);
 
-    g_strfreev (self->priv->dns);
-    self->priv->dns = g_strdupv ((gchar **)dns);
+    return self->priv->prefix;
 }
 
 void
-mm_bearer_ip_config_set_gateway (MMBearerIpConfig *self,
-                                 const gchar *gateway)
+mm_bearer_ip_config_set_prefix (MMBearerIpConfig *self,
+                                guint prefix)
 {
     g_return_if_fail (MM_IS_BEARER_IP_CONFIG (self));
 
-    g_free (self->priv->gateway);
-    self->priv->gateway = g_strdup (gateway);
+    self->priv->prefix = prefix;
 }
 
 /*****************************************************************************/
 
-MMBearerIpMethod
-mm_bearer_ip_config_get_method (MMBearerIpConfig *self)
-{
-    g_return_val_if_fail (MM_IS_BEARER_IP_CONFIG (self), MM_BEARER_IP_METHOD_UNKNOWN);
-
-    return self->priv->method;
-}
-
-const gchar *
-mm_bearer_ip_config_get_address (MMBearerIpConfig *self)
+/**
+ * mm_bearer_ip_config_get_dns:
+ * @self: a #MMBearerIpConfig.
+ *
+ * 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.
+ */
+const gchar **
+mm_bearer_ip_config_get_dns (MMBearerIpConfig *self)
 {
     g_return_val_if_fail (MM_IS_BEARER_IP_CONFIG (self), NULL);
 
-    return self->priv->address;
+    return (const gchar **)self->priv->dns;
 }
 
-guint
-mm_bearer_ip_config_get_prefix (MMBearerIpConfig *self)
+void
+mm_bearer_ip_config_set_dns (MMBearerIpConfig *self,
+                             const gchar **dns)
 {
-    g_return_val_if_fail (MM_IS_BEARER_IP_CONFIG (self), 0);
+    g_return_if_fail (MM_IS_BEARER_IP_CONFIG (self));
 
-    return self->priv->prefix;
+    g_strfreev (self->priv->dns);
+    self->priv->dns = g_strdupv ((gchar **)dns);
 }
 
-const gchar **
-mm_bearer_ip_config_get_dns (MMBearerIpConfig *self)
-{
-    g_return_val_if_fail (MM_IS_BEARER_IP_CONFIG (self), NULL);
-
-    return (const gchar **)self->priv->dns;
-}
+/*****************************************************************************/
 
+/**
+ * mm_bearer_ip_config_get_gateway:
+ * @self: a #MMBearerIpConfig.
+ *
+ * Gets the IP address of the gateway to be used with this bearer.
+ *
+ * Returns: a string with the IP address, or #NULL if unknown. Do not free the returned value, it is owned by @self.
+ */
 const gchar *
 mm_bearer_ip_config_get_gateway (MMBearerIpConfig *self)
 {
@@ -128,6 +177,16 @@ mm_bearer_ip_config_get_gateway (MMBearerIpConfig *self)
     return self->priv->gateway;
 }
 
+void
+mm_bearer_ip_config_set_gateway (MMBearerIpConfig *self,
+                                 const gchar *gateway)
+{
+    g_return_if_fail (MM_IS_BEARER_IP_CONFIG (self));
+
+    g_free (self->priv->gateway);
+    self->priv->gateway = g_strdup (gateway);
+}
+
 /*****************************************************************************/
 
 GVariant *
diff --git a/libmm-glib/mm-bearer-ip-config.h b/libmm-glib/mm-bearer-ip-config.h
index 04b1da53..bfd2ea73 100644
--- a/libmm-glib/mm-bearer-ip-config.h
+++ b/libmm-glib/mm-bearer-ip-config.h
@@ -36,29 +36,44 @@ typedef struct _MMBearerIpConfig MMBearerIpConfig;
 typedef struct _MMBearerIpConfigClass MMBearerIpConfigClass;
 typedef struct _MMBearerIpConfigPrivate MMBearerIpConfigPrivate;
 
+/**
+ * MMBearerIpConfig:
+ *
+ * The #MMBearerIpConfig structure contains private data and should
+ * only be accessed using the provided API.
+ */
 struct _MMBearerIpConfig {
+    /*< private >*/
     GObject parent;
     MMBearerIpConfigPrivate *priv;
 };
 
 struct _MMBearerIpConfigClass {
+    /*< private >*/
     GObjectClass parent;
 };
 
 GType mm_bearer_ip_config_get_type (void);
 
-MMBearerIpConfig *mm_bearer_ip_config_new (void);
-MMBearerIpConfig *mm_bearer_ip_config_new_from_dictionary (GVariant *dictionary,
-                                                           GError **error);
-
-MMBearerIpConfig *mm_bearer_ip_config_dup (MMBearerIpConfig *orig);
-
 MMBearerIpMethod   mm_bearer_ip_config_get_method  (MMBearerIpConfig *self);
 const gchar       *mm_bearer_ip_config_get_address (MMBearerIpConfig *self);
 guint              mm_bearer_ip_config_get_prefix  (MMBearerIpConfig *self);
 const gchar      **mm_bearer_ip_config_get_dns     (MMBearerIpConfig *self);
 const gchar       *mm_bearer_ip_config_get_gateway (MMBearerIpConfig *self);
 
+/*****************************************************************************/
+/* ModemManager/libmm-glib/mmcli specific methods */
+
+#if defined (_LIBMM_INSIDE_MM) ||    \
+    defined (_LIBMM_INSIDE_MMCLI) || \
+    defined (LIBMM_GLIB_COMPILATION)
+
+MMBearerIpConfig *mm_bearer_ip_config_new (void);
+MMBearerIpConfig *mm_bearer_ip_config_new_from_dictionary (GVariant *dictionary,
+                                                           GError **error);
+
+MMBearerIpConfig *mm_bearer_ip_config_dup (MMBearerIpConfig *orig);
+
 void mm_bearer_ip_config_set_method  (MMBearerIpConfig *self,
                                       MMBearerIpMethod ip_method);
 void mm_bearer_ip_config_set_address (MMBearerIpConfig *self,
@@ -72,6 +87,8 @@ void mm_bearer_ip_config_set_gateway (MMBearerIpConfig *self,
 
 GVariant *mm_bearer_ip_config_get_dictionary (MMBearerIpConfig *self);
 
+#endif
+
 G_END_DECLS
 
 #endif /* MM_BEARER_IP_CONFIG_H */