2008-08-12 Tambet Ingo <tambet@gmail.com>

	* libnm-glib/*.c. Document some more.


git-svn-id: http://svn-archive.gnome.org/svn/NetworkManager/trunk@3934 4912f4e0-d625-0410-9fb7-b9a5a253dbdc

ChangeLog

+2008-08-12  Tambet Ingo  <tambet@gmail.com>
+
+	* libnm-glib/*.c. Document some more.
+
 2008-08-12  Tambet Ingo  <tambet@gmail.com>
 
 	Start documenting libnm-glib public API using gtk-doc.

docs/libnm-glib/libnm-glib-docs.sgml

+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>libnm-glib Reference Manual</title>
+    <releaseinfo>
+      for libnm-glib [VERSION]
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="http://[SERVER]/libnm-glib/index.html">http://[SERVER]/libnm-glib/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>[Insert title here]</title>
+    <xi:include href="xml/nm-access-point.xml"/>
+    <xi:include href="xml/nm-cdma-device.xml"/>
+    <xi:include href="xml/nm-client.xml"/>
+    <xi:include href="xml/nm-gsm-device.xml"/>
+    <xi:include href="xml/nm-device.xml"/>
+    <xi:include href="xml/nm-ip4-config.xml"/>
+    <xi:include href="xml/nm-object.xml"/>
+    <xi:include href="xml/nm-settings.xml"/>
+    <xi:include href="xml/nm-vpn-connection.xml"/>
+    <xi:include href="xml/nm-vpn-plugin.xml"/>
+    <xi:include href="xml/nm-dbus-settings-system.xml"/>
+    <xi:include href="xml/nm-active-connection.xml"/>
+    <xi:include href="xml/nm-device-ethernet.xml"/>
+    <xi:include href="xml/nm-device-wifi.xml"/>
+    <xi:include href="xml/nm-dbus-connection.xml"/>
+    <xi:include href="xml/nm-serial-device.xml"/>
+    <xi:include href="xml/nm-dbus-settings.xml"/>
+    <xi:include href="xml/nm-dhcp4-config.xml"/>
+    <xi:include href="xml/nm-vpn-plugin-ui-interface.xml"/>
+    <xi:include href="xml/libnm_glib.xml"/>
+    <xi:include href="xml/nm-types.xml"/>
+  </chapter>
+</book>

docs/libnm-glib/libnm-glib.types

@@ -4,6 +4,10 @@
 #include <nm-cdma-device.h>
 #include <nm-gsm-device.h>
 #include <nm-serial-device.h>
+#include <nm-access-point.h>
+#include <nm-ip4-config.h>
+#include <nm-active-connection.h>
+#include <nm-dhcp4-config.h>
 
 nm_object_get_type
 nm_client_get_type
@@ -13,3 +17,7 @@ nm_device_wifi_get_type
 nm_gsm_device_get_type
 nm_cdma_device_get_type
 nm_serial_device_get_type
+nm_access_point_get_type
+nm_ip4_config_get_type
+nm_active_connection_get_type
+nm_dhcp4_config_get_type

libnm-glib/nm-access-point.c

@@ -53,6 +53,15 @@ enum {
 #define DBUS_PROP_MAX_BITRATE "MaxBitrate"
 #define DBUS_PROP_STRENGTH "Strength"
 
+/**
+ * nm_access_point_new:
+ * @connection: the #DBusGConnection
+ * @path: the DBusobject path of the access point
+ *
+ * Creates a new #NMAccessPoint.
+ *
+ * Returns: a new access point
+ **/
 GObject *
 nm_access_point_new (DBusGConnection *connection, const char *path)
 {
@@ -65,6 +74,14 @@ nm_access_point_new (DBusGConnection *connection, const char *path)
 								    NULL);
 }
 
+/**
+ * nm_access_point_get_flags:
+ * @ap: a #NMAccessPoint
+ *
+ * Gets the flags of the access point
+ *
+ * Returns: the flags
+ **/
 guint32
 nm_access_point_get_flags (NMAccessPoint *ap)
 {
@@ -82,6 +99,14 @@ nm_access_point_get_flags (NMAccessPoint *ap)
 	return priv->flags;
 }
 
+/**
+ * nm_access_point_get_wpa_flags:
+ * @ap: a #NMAccessPoint
+ *
+ * Gets the WPA flags of the access point.
+ *
+ * Returns: the WPA flags
+ **/
 guint32
 nm_access_point_get_wpa_flags (NMAccessPoint *ap)
 {
@@ -99,6 +124,14 @@ nm_access_point_get_wpa_flags (NMAccessPoint *ap)
 	return priv->wpa_flags;
 }
 
+/**
+ * nm_access_point_get_rsn_flags:
+ * @ap: a #NMAccessPoint
+ *
+ * Gets the RSN flags of the access point.
+ *
+ * Returns: the RSN flags
+ **/
 guint32
 nm_access_point_get_rsn_flags (NMAccessPoint *ap)
 {
@@ -116,6 +149,15 @@ nm_access_point_get_rsn_flags (NMAccessPoint *ap)
 	return priv->rsn_flags;
 }
 
+/**
+ * nm_access_point_get_ssid:
+ * @ap: a #NMAccessPoint
+ *
+ * Gets the SSID of the access point.
+ *
+ * Returns: the #GByteArray containing the SSID. This is the internal copy used by the
+ * access point, and must not be modified.
+ **/
 const GByteArray *
 nm_access_point_get_ssid (NMAccessPoint *ap)
 {
@@ -133,6 +175,14 @@ nm_access_point_get_ssid (NMAccessPoint *ap)
 	return priv->ssid;
 }
 
+/**
+ * nm_access_point_get_frequency:
+ * @ap: a #NMAccessPoint
+ *
+ * Gets the frequency of the access point.
+ *
+ * Returns: the frequency
+ **/
 guint32
 nm_access_point_get_frequency (NMAccessPoint *ap)
 {
@@ -150,6 +200,15 @@ nm_access_point_get_frequency (NMAccessPoint *ap)
 	return priv->frequency;
 }
 
+/**
+ * nm_access_point_get_hw_address:
+ * @ap: a #NMAccessPoint
+ *
+ * Gets the hardware (MAC) address of the access point.
+ *
+ * Returns: the hardware address of the access point. This is the internal string used by the
+ * access point and must not be modified.
+ **/
 const char *
 nm_access_point_get_hw_address (NMAccessPoint *ap)
 {
@@ -167,6 +226,14 @@ nm_access_point_get_hw_address (NMAccessPoint *ap)
 	return priv->hw_address;
 }
 
+/**
+ * nm_access_point_get_mode:
+ * @ap: a #NMAccessPoint
+ *
+ * Gets the mode of the access point.
+ *
+ * Returns: the mode
+ **/
 NM80211Mode
 nm_access_point_get_mode (NMAccessPoint *ap)
 {
@@ -184,6 +251,14 @@ nm_access_point_get_mode (NMAccessPoint *ap)
 	return priv->mode;
 }
 
+/**
+ * nm_access_point_get_max_bitrate:
+ * @ap: a #NMAccessPoint
+ *
+ * Gets the maximum bit rate of the access point.
+ *
+ * Returns: the maximum bit rate
+ **/
 guint32
 nm_access_point_get_max_bitrate (NMAccessPoint *ap)
 {
@@ -201,6 +276,14 @@ nm_access_point_get_max_bitrate (NMAccessPoint *ap)
 	return priv->max_bitrate;
 }
 
+/**
+ * nm_access_point_get_strength:
+ * @ap: 
+ *
+ * Gets the current signal strength of the access point.
+ *
+ * Returns: the signal strength
+ **/
 guint8
 nm_access_point_get_strength (NMAccessPoint *ap)
 {
@@ -371,6 +454,12 @@ nm_access_point_class_init (NMAccessPointClass *ap_class)
 	object_class->finalize = finalize;
 
 	/* properties */
+
+	/**
+	 * NMAccessPoint:flags:
+	 *
+	 * The flags of the access point.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_FLAGS,
 		 g_param_spec_uint (NM_ACCESS_POINT_FLAGS,
@@ -381,6 +470,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class)
 		                    NM_802_11_AP_FLAGS_NONE,
 		                    G_PARAM_READABLE));
 
+	/**
+	 * NMAccessPoint:wpa-flags:
+	 *
+	 * The WPA flags of the access point.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_WPA_FLAGS,
 		 g_param_spec_uint (NM_ACCESS_POINT_WPA_FLAGS,
@@ -389,6 +483,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class)
 		                    0, G_MAXUINT32, 0,
 		                    G_PARAM_READABLE));
 
+	/**
+	 * NMAccessPoint:rsn-flags:
+	 *
+	 * The RSN flags of the access point.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_RSN_FLAGS,
 		 g_param_spec_uint (NM_ACCESS_POINT_RSN_FLAGS,
@@ -397,6 +496,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class)
 		                    0, G_MAXUINT32, 0,
 		                    G_PARAM_READABLE));
 
+	/**
+	 * NMAccessPoint:ssid:
+	 *
+	 * The SSID of the access point.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_SSID,
 		 g_param_spec_boxed (NM_ACCESS_POINT_SSID,
@@ -405,6 +509,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class)
 						 NM_TYPE_SSID,
 						 G_PARAM_READABLE));
 
+	/**
+	 * NMAccessPoint:frequency:
+	 *
+	 * The frequency of the access point.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_FREQUENCY,
 		 g_param_spec_uint (NM_ACCESS_POINT_FREQUENCY,
@@ -413,6 +522,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class)
 						0, 10000, 0,
 						G_PARAM_READABLE));
 
+	/**
+	 * NMAccessPoint:hw-address:
+	 *
+	 * The hardware address of the access point.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_HW_ADDRESS,
 		 g_param_spec_string (NM_ACCESS_POINT_HW_ADDRESS,
@@ -421,6 +535,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class)
 						  NULL,
 						  G_PARAM_READABLE));
 	
+	/**
+	 * NMAccessPoint:mode:
+	 *
+	 * The mode of the access point.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_MODE,
 		 g_param_spec_uint (NM_ACCESS_POINT_MODE,
@@ -429,6 +548,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class)
 					    NM_802_11_MODE_ADHOC, NM_802_11_MODE_INFRA, NM_802_11_MODE_INFRA,
 					    G_PARAM_READABLE));
 
+	/**
+	 * NMAccessPoint:max-bitrate:
+	 *
+	 * The maximum bit rate of the access point.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_MAX_BITRATE,
 		 g_param_spec_uint (NM_ACCESS_POINT_MAX_BITRATE,
@@ -437,6 +561,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class)
 						0, G_MAXUINT32, 0,
 						G_PARAM_READABLE));
 
+	/**
+	 * NMAccessPoint:strength:
+	 *
+	 * The current signal strength of the access point.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_STRENGTH,
 		 g_param_spec_uchar (NM_ACCESS_POINT_STRENGTH,

libnm-glib/nm-active-connection.c

@@ -50,6 +50,15 @@ enum {
 #define DBUS_PROP_STATE "State"
 #define DBUS_PROP_DEFAULT "Default"
 
+/**
+ * nm_active_connection_new:
+ * @connection: the #DBusGConnection
+ * @path: the DBus object path of the device
+ *
+ * Creates a new #NMActiveConnection.
+ *
+ * Returns: a new active connection
+ **/
 GObject *
 nm_active_connection_new (DBusGConnection *connection, const char *path)
 {
@@ -73,6 +82,15 @@ get_scope_for_service_name (const char *service_name)
 	return NM_CONNECTION_SCOPE_UNKNOWN;
 }
 
+/**
+ * nm_active_connection_get_service_name:
+ * @connection: a #NMActiveConnection
+ *
+ * Gets the service name of the active connection.
+ *
+ * Returns: the service name. This is the internal string used by the
+ * connection, and must not be modified.
+ **/
 const char *
 nm_active_connection_get_service_name (NMActiveConnection *connection)
 {
@@ -91,6 +109,14 @@ nm_active_connection_get_service_name (NMActiveConnection *connection)
 	return priv->service_name;
 }
 
+/**
+ * nm_active_connection_get_scope:
+ * @connection: a #NMActiveConnection
+ *
+ * Gets the scope of the active connection.
+ *
+ * Returns: the connection's scope
+ **/
 NMConnectionScope
 nm_active_connection_get_scope (NMActiveConnection *connection)
 {
@@ -101,6 +127,15 @@ nm_active_connection_get_scope (NMActiveConnection *connection)
 	return NM_ACTIVE_CONNECTION_GET_PRIVATE (connection)->scope;
 }
 
+/**
+ * nm_active_connection_get_connection:
+ * @connection: a #NMActiveConnection
+ *
+ * Gets the #NMConnection<!-- -->'s DBus object path.
+ *
+ * Returns: the object path of the #NMConnection inside of #NMActiveConnection.
+ * This is the internal string used by the connection, and must not be modified.
+ **/
 const char *
 nm_active_connection_get_connection (NMActiveConnection *connection)
 {
@@ -118,6 +153,15 @@ nm_active_connection_get_connection (NMActiveConnection *connection)
 	return priv->connection;
 }
 
+/**
+ * nm_active_connection_get_specific_object:
+ * @connection: a #NMActiveConnection
+ *
+ * Gets the "specific object" used at the activation.
+ *
+ * Returns: the specific object's DBus path. This is the internal string used by the
+ * connection, and must not be modified.
+ **/
 const char *
 nm_active_connection_get_specific_object (NMActiveConnection *connection)
 {
@@ -135,6 +179,15 @@ nm_active_connection_get_specific_object (NMActiveConnection *connection)
 	return priv->specific_object;
 }
 
+/**
+ * nm_active_connection_get_devices:
+ * @connection: a #NMActiveConnection
+ *
+ * Gets the #NMDevice<!-- -->s used for the active connections.
+ *
+ * Returns: the #GPtrArray containing #NMDevice<!-- -->s.
+ * This is the internal copy used by the connection, and must not be modified.
+ **/
 const GPtrArray *
 nm_active_connection_get_devices (NMActiveConnection *connection)
 {
@@ -160,6 +213,14 @@ nm_active_connection_get_devices (NMActiveConnection *connection)
 	return handle_ptr_array_return (priv->devices);
 }
 
+/**
+ * nm_active_connection_get_state:
+ * @connection: a #NMActiveConnection
+ *
+ * Gets the active connection's state.
+ *
+ * Returns: the state
+ **/
 NMActiveConnectionState
 nm_active_connection_get_state (NMActiveConnection *connection)
 {
@@ -177,6 +238,15 @@ nm_active_connection_get_state (NMActiveConnection *connection)
 	return priv->state;
 }
 
+/**
+ * nm_active_connection_get_default:
+ * @connection: a #NMActiveConnection
+ *
+ * Whether the active connection is the default one (that is, is used for the default route
+ * and DNS information).
+ *
+ * Returns: %TRUE if the active connection is the default one
+ **/
 gboolean
 nm_active_connection_get_default (NMActiveConnection *connection)
 {
@@ -350,6 +420,12 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class)
 	object_class->finalize = finalize;
 
 	/* properties */
+
+	/**
+	 * NMActiveConnection:service-name:
+	 *
+	 * The service name of the active connection.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_SERVICE_NAME,
 		 g_param_spec_string (NM_ACTIVE_CONNECTION_SERVICE_NAME,
@@ -358,6 +434,11 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class)
 						  NULL,
 						  G_PARAM_READABLE));
 
+	/**
+	 * NMActiveConnection:connection:
+	 *
+	 * The connection's path of the active connection.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_CONNECTION,
 		 g_param_spec_string (NM_ACTIVE_CONNECTION_CONNECTION,
@@ -366,6 +447,11 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class)
 						      NULL,
 						      G_PARAM_READABLE));
 
+	/**
+	 * NMActiveConnection:specific-object:
+	 *
+	 * The specific object's path of the active connection.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_SPECIFIC_OBJECT,
 		 g_param_spec_string (NM_ACTIVE_CONNECTION_SPECIFIC_OBJECT,
@@ -374,6 +460,11 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class)
 						      NULL,
 						      G_PARAM_READABLE));
 
+	/**
+	 * NMActiveConnection:device:
+	 *
+	 * The devices (#NMDevice) of the active connection.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_DEVICES,
 		 g_param_spec_boxed (NM_ACTIVE_CONNECTION_DEVICES,
@@ -382,6 +473,11 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class)
 						       NM_TYPE_OBJECT_ARRAY,
 						       G_PARAM_READABLE));
 
+	/**
+	 * NMActiveConnection:state:
+	 *
+	 * The state of the active connection.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_STATE,
 		 g_param_spec_uint (NM_ACTIVE_CONNECTION_STATE,
@@ -392,6 +488,11 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class)
 							  NM_ACTIVE_CONNECTION_STATE_UNKNOWN,
 							  G_PARAM_READABLE));
 
+	/**
+	 * NMActiveConnection:default:
+	 *
+	 * Whether the active connection is the default one.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_DEFAULT,
 		 g_param_spec_boolean (NM_ACTIVE_CONNECTION_DEFAULT,

libnm-glib/nm-dhcp4-config.c

@@ -139,6 +139,12 @@ nm_dhcp4_config_class_init (NMDHCP4ConfigClass *config_class)
 	object_class->finalize = finalize;
 
 	/* properties */
+
+	/**
+	 * NMDHCP4Config:options:
+	 *
+	 * The #GHashTable containing options of the configuration.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_OPTIONS,
 		 g_param_spec_boxed (NM_DHCP4_CONFIG_OPTIONS,
@@ -148,6 +154,15 @@ nm_dhcp4_config_class_init (NMDHCP4ConfigClass *config_class)
 						       G_PARAM_READABLE));
 }
 
+/**
+ * nm_dhcp4_config_new:
+ * @connection: the #DBusGConnection
+ * @object_path: the DBus object path of the device
+ *
+ * Creates a new #NMDHCP4Config.
+ *
+ * Returns: a new configuration
+ **/
 GObject *
 nm_dhcp4_config_new (DBusGConnection *connection, const char *object_path)
 {
@@ -157,6 +172,15 @@ nm_dhcp4_config_new (DBusGConnection *connection, const char *object_path)
 									 NULL);
 }
 
+/**
+ * nm_dhcp4_config_get_options:
+ * @self: a #NMDHCP4Config
+ *
+ * Gets all the options contained in the configuration.
+ *
+ * Returns: the #GHashTable containing strings for keys and values.
+ * This is the internal copy used by the configuration, and must not be modified.
+ **/
 GHashTable *
 nm_dhcp4_config_get_options (NMDHCP4Config *self)
 {
@@ -179,6 +203,16 @@ out:
 	return priv->options;
 }
 
+/**
+ * nm_dhcp4_config_get_one_option:
+ * @self: a #NMDHCP4Config
+ * @option: the option to retrieve
+ *
+ * Gets one option by option name.
+ *
+ * Returns: the configuration option's value. This is the internal string used by the
+ * configuration, and must not be modified.
+ **/
 const char *
 nm_dhcp4_config_get_one_option (NMDHCP4Config *self, const char *option)
 {

libnm-glib/nm-ip4-config.c

@@ -200,6 +200,12 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class)
 	object_class->finalize = finalize;
 
 	/* properties */
+
+	/**
+	 * NMIP4Config:addresses:
+	 *
+	 * The #GPtrArray containing #NMSettingIP4Address<!-- -->es of the configuration.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_ADDRESSES,
 		 g_param_spec_pointer (NM_IP4_CONFIG_ADDRESSES,
@@ -207,6 +213,11 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class)
 						       "Addresses",
 						       G_PARAM_READABLE));
 
+	/**
+	 * NMIP4Config:hostname:
+	 *
+	 * The host name string of the configuration.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_HOSTNAME,
 		 g_param_spec_string (NM_IP4_CONFIG_HOSTNAME,
@@ -215,6 +226,11 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class)
 						    NULL,
 						    G_PARAM_READABLE));
 
+	/**
+	 * NMIP4Config:nameservers:
+	 *
+	 * The #GArray containing name servers (%guint32<!-- -->es) of the configuration.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_NAMESERVERS,
 		 g_param_spec_boxed (NM_IP4_CONFIG_NAMESERVERS,
@@ -223,6 +239,11 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class)
 						    NM_TYPE_UINT_ARRAY,
 						    G_PARAM_READABLE));
 
+	/**
+	 * NMIP4Config:domains:
+	 *
+	 * The #GPtrArray containing domain strings of the configuration.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_DOMAINS,
 		 g_param_spec_boxed (NM_IP4_CONFIG_DOMAINS,
@@ -231,6 +252,11 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class)
 						    NM_TYPE_STRING_ARRAY,
 						    G_PARAM_READABLE));
 
+	/**
+	 * NMIP4Config:routes:
+	 *
+	 * The #GPtrArray containing #NMSettingIP4Route<!-- -->s of the configuration.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_ROUTES,
 		 g_param_spec_pointer (NM_IP4_CONFIG_ROUTES,
@@ -239,6 +265,15 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class)
 						       G_PARAM_READABLE));
 }
 
+/**
+ * nm_ip4_config_new:
+ * @connection: the #DBusGConnection
+ * @object_path: the DBus object path of the device
+ *
+ * Creates a new #NMIP4Config.
+ *
+ * Returns: a new IP4 configuration
+ **/
 GObject *
 nm_ip4_config_new (DBusGConnection *connection, const char *object_path)
 {
@@ -248,6 +283,15 @@ nm_ip4_config_new (DBusGConnection *connection, const char *object_path)
 									 NULL);
 }