Documentation updates

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

libnm-util/nm-connection.c

@@ -76,7 +76,7 @@
  *
  * Registers an error quark for #NMConnection if necessary.
  *
- * Returns: the error quark used for NMConnection errors.
+ * Returns: the error quark used for #NMConnection errors.
  **/
 GQuark
 nm_connection_error_quark (void)
@@ -98,9 +98,7 @@ nm_connection_error_get_type (void)
 
 	if (etype == 0) {
 		static const GEnumValue values[] = {
-			/* Unknown error. */
 			ENUM_ENTRY (NM_CONNECTION_ERROR_UNKNOWN, "UnknownError"),
-			/* The required 'connection' setting was not found. */
 			ENUM_ENTRY (NM_CONNECTION_ERROR_CONNECTION_SETTING_NOT_FOUND, "ConnectionSettingNotFound"),
 			{ 0, 0, 0 }
 		};
@@ -985,7 +983,7 @@ nm_connection_get_path (NMConnection *connection)
  *
  * Creates a new #NMConnection object with no #NMSetting objects.
  *
- * Returns: the new blank #NMConnection object
+ * Returns: the new empty #NMConnection object
  **/
 NMConnection *
 nm_connection_new (void)

libnm-util/nm-connection.h

@@ -39,18 +39,34 @@ G_BEGIN_DECLS
 #define NM_IS_CONNECTION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((obj), NM_TYPE_CONNECTION))
 #define NM_CONNECTION_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_CONNECTION, NMConnectionClass))
 
-/* connection scope, used only by the caller for tracking connections
+/**
- * provided by multiple settings services.
+ * NMConnectionScope:
- */
+ * @NM_CONNECTION_SCOPE_UNKNOWN: scope not known or not yet set
+ * @NM_CONNECTION_SCOPE_SYSTEM: connection is provided by the system settings
+ *   service
+ * @NM_CONNECTION_SCOPE_USER: connection is provided by a user settings service
+ *
+ * Connection scope indicated what settings service, if any, provides the
+ * connection.
+ *
+ **/
 typedef enum {
-	/* The connection's scope is unknown, or not yet set */
 	NM_CONNECTION_SCOPE_UNKNOWN = 0,
-	/* The connection is provided by the system settings service */
 	NM_CONNECTION_SCOPE_SYSTEM,
-	/* The connection is provided by a user settings service */
 	NM_CONNECTION_SCOPE_USER
 } NMConnectionScope;
 
+
+/**
+ * NMConnectionError:
+ * @NM_CONNECTION_ERROR_UNKNOWN: unknown or unclassified error
+ * @NM_CONNECTION_ERROR_CONNECTION_SETTING_NOT_FOUND: the #NMConnection object
+ *   did not contain the required #NMSettingConnection object, which must be
+ *   present for all connections
+ *
+ * Describes errors that may result from operations involving a #NMConnection.
+ *
+ **/
 typedef enum
 {
 	NM_CONNECTION_ERROR_UNKNOWN = 0,
@@ -66,6 +82,12 @@ GQuark nm_connection_error_quark (void);
 #define NM_CONNECTION_SCOPE "scope"
 #define NM_CONNECTION_PATH "path"
 
+/**
+ * NMConnection:
+ *
+ * The NMConnection struct contains only private data.
+ * It should only be accessed through the functions described below.
+ */
 typedef struct {
 	GObject parent;
 } NMConnection;
@@ -101,7 +123,6 @@ gboolean      nm_connection_replace_settings (NMConnection *connection,
                                               GHashTable *new_settings,
                                               GError **error);
 
-/* Returns TRUE if the connections are the same */
 gboolean      nm_connection_compare       (NMConnection *a,
                                            NMConnection *b,
                                            NMSettingCompareFlags flags);

libnm-util/nm-setting-connection.c

@@ -26,6 +26,24 @@
 #include <string.h>
 #include "nm-setting-connection.h"
 
+/**
+ * SECTION:nm-setting-connection
+ * @short_description: Describes general connection properties
+ * @include: nm-setting-connection.h
+ *
+ * The #NMSettingConnection object is a #NMSetting subclass that describes
+ * properties that apply to all #NMConnection objects, regardless of what type
+ * of network connection they describe.  Each #NMConnection object must contain
+ * a #NMSettingConnection setting.
+ */
+
+/**
+ * nm_setting_connection_error_quark:
+ *
+ * Registers an error quark for #NMSettingConnection if necessary.
+ *
+ * Returns: the error quark used for #NMSettingConnection errors.
+ **/
 GQuark
 nm_setting_connection_error_quark (void)
 {
@@ -46,13 +64,9 @@ nm_setting_connection_error_get_type (void)
 
 	if (etype == 0) {
 		static const GEnumValue values[] = {
-			/* Unknown error. */
 			ENUM_ENTRY (NM_SETTING_CONNECTION_ERROR_UNKNOWN, "UnknownError"),
-			/* The specified property was invalid. */
 			ENUM_ENTRY (NM_SETTING_CONNECTION_ERROR_INVALID_PROPERTY, "InvalidProperty"),
-			/* The specified property was missing and is required. */
 			ENUM_ENTRY (NM_SETTING_CONNECTION_ERROR_MISSING_PROPERTY, "MissingProperty"),
-			/* The setting specified by the 'type' field was not found. */
 			ENUM_ENTRY (NM_SETTING_CONNECTION_ERROR_TYPE_SETTING_NOT_FOUND, "TypeSettingNotFound"),
 			{ 0, 0, 0 }
 		};
@@ -87,11 +101,26 @@ enum {
 	LAST_PROP
 };
 
+/**
+ * nm_setting_connection_new:
+ *
+ * Creates a new #NMSettingConnection object with default values.
+ *
+ * Returns: the new empty #NMSettingConnection object
+ **/
 NMSetting *nm_setting_connection_new (void)
 {
 	return (NMSetting *) g_object_new (NM_TYPE_SETTING_CONNECTION, NULL);
 }
 
+/**
+ * nm_setting_connection_get_id:
+ * @setting: the #NMSettingConnection
+ *
+ * Returns the #NMSettingConnection:id property of the connection.
+ *
+ * Returns: the connection ID
+ **/
 const char *
 nm_setting_connection_get_id (NMSettingConnection *setting)
 {
@@ -100,6 +129,14 @@ nm_setting_connection_get_id (NMSettingConnection *setting)
 	return NM_SETTING_CONNECTION_GET_PRIVATE (setting)->id;
 }
 
+/**
+ * nm_setting_connection_get_uuid:
+ * @setting: the #NMSettingConnection
+ *
+ * Returns the #NMSettingConnection:uuid property of the connection.
+ *
+ * Returns: the connection UUID
+ **/
 const char *
 nm_setting_connection_get_uuid (NMSettingConnection *setting)
 {
@@ -108,6 +145,14 @@ nm_setting_connection_get_uuid (NMSettingConnection *setting)
 	return NM_SETTING_CONNECTION_GET_PRIVATE (setting)->uuid;
 }
 
+/**
+ * nm_setting_connection_get_type:
+ * @setting: the #NMSettingConnection
+ *
+ * Returns the #NMSettingConnection:type property of the connection.
+ *
+ * Returns: the connection type
+ **/
 const char *
 nm_setting_connection_get_connection_type (NMSettingConnection *setting)
 {
@@ -116,6 +161,14 @@ nm_setting_connection_get_connection_type (NMSettingConnection *setting)
 	return NM_SETTING_CONNECTION_GET_PRIVATE (setting)->type;
 }
 
+/**
+ * nm_setting_connection_get_autoconnect:
+ * @setting: the #NMSettingConnection
+ *
+ * Returns the #NMSettingConnection:autoconnect property of the connection.
+ *
+ * Returns: the connection's autoconnect behavior
+ **/
 gboolean
 nm_setting_connection_get_autoconnect (NMSettingConnection *setting)
 {
@@ -124,6 +177,14 @@ nm_setting_connection_get_autoconnect (NMSettingConnection *setting)
 	return NM_SETTING_CONNECTION_GET_PRIVATE (setting)->autoconnect;
 }
 
+/**
+ * nm_setting_connection_get_timestamp:
+ * @setting: the #NMSettingConnection
+ *
+ * Returns the #NMSettingConnection:timestamp property of the connection.
+ *
+ * Returns: the connection's timestamp
+ **/
 guint64
 nm_setting_connection_get_timestamp (NMSettingConnection *setting)
 {
@@ -132,6 +193,14 @@ nm_setting_connection_get_timestamp (NMSettingConnection *setting)
 	return NM_SETTING_CONNECTION_GET_PRIVATE (setting)->timestamp;
 }
 
+/**
+ * nm_setting_connection_get_read_only:
+ * @setting: the #NMSettingConnection
+ *
+ * Returns the #NMSettingConnection:read-only property of the connection.
+ *
+ * Returns: %TRUE if the connection is read-only, %FALSE if it is not
+ **/
 gboolean
 nm_setting_connection_get_read_only (NMSettingConnection *setting)
 {
@@ -306,6 +375,13 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
 	parent_class->verify       = verify;
 
 	/* Properties */
+
+	/**
+	 * NMSettingConnection:id:
+	 *
+	 * A human readable unique idenfier for the connection, like "Work WiFi" or
+	 * "T-Mobile 3G".
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_ID,
 		 g_param_spec_string (NM_SETTING_CONNECTION_ID,
@@ -314,6 +390,17 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
 						  NULL,
 						  G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE));
 
+	/**
+	 * NMSettingConnection:uuid:
+	 *
+	 * A universally unique idenfier for the connection, for example generated
+	 * with libuuid.  Should be assigned when the connection is created, and
+	 * never changed as long as the connection still applies to the same
+	 * network.  For example, should not be changed when the
+	 * #NMSettingConnection:id or #NMSettingIP4Config changes, but might need
+	 * to be re-created when the WiFi SSID, mobile broadband network provider,
+	 * or #NMSettingConnection:type changes.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_UUID,
 		 g_param_spec_string (NM_SETTING_CONNECTION_UUID,
@@ -322,6 +409,14 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
 						  NULL,
 						  G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE));
 
+	/**
+	 * NMSettingConnection:type:
+	 *
+	 * The general hardware type of the device used for the network connection,
+	 * contains the name of the #NMSetting object that describes that hardware
+	 * type's parameters.  For example, for WiFi devices, the name of the
+	 * #NMSettingWireless setting.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_TYPE,
 		 g_param_spec_string (NM_SETTING_CONNECTION_TYPE,
@@ -330,6 +425,14 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
 						  NULL,
 						  G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE));
 
+	/**
+	 * NMSettingConnection:autoconnect:
+	 *
+	 * Whether or not the connection should be automatically connected by
+	 * NetworkManager when the resources for the connection are available.
+	 * %TRUE to automatically activate the connection, %FALSE to require manual
+	 * intervention to activate the connection.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_AUTOCONNECT,
 		 g_param_spec_boolean (NM_SETTING_CONNECTION_AUTOCONNECT,
@@ -338,6 +441,12 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
 						   FALSE,
 						   G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE));
 
+	/**
+	 * NMSettingConnection:timestamp:
+	 *
+	 * The time, in seconds since the Unix Epoch, that the connection was last
+	 * _successfully_ fully activated.
+	 **/
 	g_object_class_install_property
 		(object_class, PROP_TIMESTAMP,
 		 g_param_spec_uint64 (NM_SETTING_CONNECTION_TIMESTAMP,
@@ -346,6 +455,13 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
 						  0, G_MAXUINT64, 0,
 						  G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE));
 
+	/**
+	 * NMSettingConnection:read-only:
+	 *
+	 * %TRUE if the connection can be modified using the providing settings
+	 * service's D-Bus interface with the right privileges, or %FALSE
+	 * if the connection is read-only and cannot be modified.
+	 **/
 	g_object_class_install_property
 	    (object_class, PROP_READ_ONLY,
 	     g_param_spec_boolean (NM_SETTING_CONNECTION_READ_ONLY,

libnm-util/nm-setting-connection.h

@@ -39,6 +39,21 @@ G_BEGIN_DECLS
 
 #define NM_SETTING_CONNECTION_SETTING_NAME "connection"
 
+/**
+ * NMSettingConnectionError:
+ * @NM_SETTING_CONNECTION_ERROR_UNKNOWN: unknown or unclassified error
+ * @NM_SETTING_CONNECTION_ERROR_INVALID_PROPERTY: the property's value is
+ *   invalid
+ * @NM_SETTING_CONNECTION_ERROR_MISSING_PROPERTY: a required property is not
+ *   present
+ * @NM_SETTING_CONNECTION_ERROR_TYPE_SETTING_NOT_FOUND: the #NMSetting object
+ *   referenced by the setting name contained in the
+ *   #NMSettingConnection:type property was not present in the #NMConnection
+ *
+ * Describes errors that may result from operations involving a
+ * #NMSettingConnection.
+ *
+ **/
 typedef enum
 {
 	NM_SETTING_CONNECTION_ERROR_UNKNOWN = 0,
@@ -60,6 +75,12 @@ GQuark nm_setting_connection_error_quark (void);
 #define NM_SETTING_CONNECTION_TIMESTAMP   "timestamp"
 #define NM_SETTING_CONNECTION_READ_ONLY   "read-only"
 
+/**
+ * NMSettingConnection:
+ *
+ * The NMSettingConnection struct contains only private data.
+ * It should only be accessed through the functions described below.
+ */
 typedef struct {
 	NMSetting parent;
 } NMSettingConnection;

libnm-util/nm-setting.c

@@ -29,6 +29,19 @@
 #include "nm-setting-connection.h"
 #include "nm-utils.h"
 
+/**
+ * SECTION:nm-setting
+ * @short_description: Describes related configuration information
+ * @include: nm-setting.h
+ *
+ * Each #NMSetting contains properties that describe configuration that applies
+ * to a specific network layer (like IPv4 or IPv6 configuration) or device type
+ * (like Ethernet, or WiFi).  A collection of individual settings together
+ * make up an #NMConnection. Each property is strongly typed and usually has
+ * a number of allowed values.  See each #NMSetting subclass for a description
+ * of properties and allowed values.
+ */
+
 /**
  * nm_setting_error_quark:
  *
@@ -56,13 +69,9 @@ nm_setting_error_get_type (void)
 
 	if (etype == 0) {
 		static const GEnumValue values[] = {
-			/* Unknown error. */
 			ENUM_ENTRY (NM_SETTING_ERROR_UNKNOWN, "UnknownError"),
-			/* The property was not found. */
 			ENUM_ENTRY (NM_SETTING_ERROR_PROPERTY_NOT_FOUND, "PropertyNotFound"),
-			/* The property was not a secret. */
 			ENUM_ENTRY (NM_SETTING_ERROR_PROPERTY_NOT_SECRET, "PropertyNotSecret"),
-			/* The property type didn't match the required property type. */
 			ENUM_ENTRY (NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH, "PropertyTypeMismatch"),
 			{ 0, 0, 0 }
 		};

libnm-util/nm-setting.h

@@ -38,6 +38,20 @@ G_BEGIN_DECLS
 #define NM_IS_SETTING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((obj), NM_TYPE_SETTING))
 #define NM_SETTING_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_SETTING, NMSettingClass))
 
+/**
+ * NMSettingError:
+ * @NM_SETTING_ERROR_UNKNOWN: unknown or unclassified error
+ * @NM_SETTING_ERROR_PROPERTY_NOT_FOUND: a property required by the operation
+ *   was not found; for example, an attempt to update an invalid secret
+ * @NM_SETTING_ERROR_PROPERTY_NOT_SECRET: an operation which requires a secret
+ *   was attempted on a non-secret property
+ * @NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH: the operation requires a property
+ *   of a specific type, or the value couldn't be transformed to the same type
+ *   as the property being acted upon
+ *
+ * Describes errors that may result from operations involving a #NMSetting.
+ *
+ **/
 typedef enum
 {
 	NM_SETTING_ERROR_UNKNOWN = 0,
@@ -52,13 +66,29 @@ GType nm_setting_error_get_type (void);
 #define NM_SETTING_ERROR nm_setting_error_quark ()
 GQuark nm_setting_error_quark (void);
 
+
+/* The property of the #NMSetting should be serialized */
 #define NM_SETTING_PARAM_SERIALIZE    (1 << (0 + G_PARAM_USER_SHIFT))
+
+/* The property of the #NMSetting is required for the setting to be valid */
 #define NM_SETTING_PARAM_REQUIRED     (1 << (1 + G_PARAM_USER_SHIFT))
+
+/* The property of the #NMSetting is a secret */
 #define NM_SETTING_PARAM_SECRET       (1 << (2 + G_PARAM_USER_SHIFT))
+
+/* The property of the #NMSetting should be ignored during comparisons that
+ * use the %NM_SETTING_COMPARE_FLAG_FUZZY flag.
+ */
 #define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + G_PARAM_USER_SHIFT))
 
 #define NM_SETTING_NAME "name"
 
+/**
+ * NMSetting:
+ *
+ * The NMSetting struct contains only private data.
+ * It should only be accessed through the functions described below.
+ */
 typedef struct {
 	GObject parent;
 } NMSetting;
@@ -100,24 +130,26 @@ gboolean    nm_setting_verify        (NMSetting *setting,
                                       GSList    *all_settings,
                                       GError    **error);
 
-
+/**
+ * NMSettingCompareFlags:
+ * @NM_SETTING_COMPARE_FLAG_EXACT: match all properties exactly
+ * @NM_SETTING_COMPARE_FLAG_FUZZY: match only important attributes, like SSID,
+ *   type, security settings, etc.  Does not match, for example, connection ID
+ *   or UUID.
+ * @NM_SETTING_COMPARE_FLAG_IGNORE_ID: ignore the connection's ID
+ * @NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS: ignore secrets
+ *
+ * These flags modify the comparison behavior when comparing two settings or
+ * two connections.
+ *
+ **/
 typedef enum {
-	/* Match all attributes exactly */
 	NM_SETTING_COMPARE_FLAG_EXACT = 0x00000000,
-
-	/* Match only important attributes, like SSID, type, security settings, etc;
-	 * For example, does not match connection ID or UUID.
-	 */
 	NM_SETTING_COMPARE_FLAG_FUZZY = 0x00000001,
-
-	/* Ignore the connection ID */
 	NM_SETTING_COMPARE_FLAG_IGNORE_ID = 0x00000002,
-
-	/* Ignore connection secrets */
 	NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS = 0x00000004
 } NMSettingCompareFlags;
 
-/* Returns TRUE if the connections are the same */
 gboolean    nm_setting_compare       (NMSetting *a,
                                       NMSetting *b,
                                       NMSettingCompareFlags flags);