docs: document the VPN setting

libnm-util/nm-setting-vpn.c

@@ -32,6 +32,27 @@
 #include "nm-dbus-glib-types.h"
 #include "nm-setting-private.h"
 
+/**
+ * SECTION:nm-setting-vpn
+ * @short_description: Describes connection properties for Virtual Private Networks
+ * @include: nm-setting-vpn.h
+ *
+ * The #NMSettingVPN object is a #NMSetting subclass that describes properties
+ * necessary for connection to Virtual Private Networks.  NetworkManager uses
+ * a plugin architecture to allow easier use of new VPN types, and this
+ * setting abstracts the configuration for those plugins.  Since the configuration
+ * options are only known to the VPN plugins themselves, the VPN configuration
+ * options are stored as key/value pairs of strings rather than GObject
+ * properties.
+ **/
+
+/**
+ * nm_setting_vpn_error_quark:
+ *
+ * Registers an error quark for #NMSettingVPN if necessary.
+ *
+ * Returns: the error quark used for #NMSettingVPN errors.
+ **/
 GQuark
 nm_setting_vpn_error_quark (void)
 {
@@ -108,12 +129,27 @@ enum {
 	LAST_PROP
 };
 
+/**
+ * nm_setting_vpn_new:
+ *
+ * Creates a new #NMSettingVPN object with default values.
+ *
+ * Returns: (transfer full): the new empty #NMSettingVPN object
+ **/
 NMSetting *
 nm_setting_vpn_new (void)
 {
 	return (NMSetting *) g_object_new (NM_TYPE_SETTING_VPN, NULL);
 }
 
+/**
+ * nm_setting_vpn_get_service_type:
+ *
+ * Returns the service name of the VPN, which identifies the specific VPN
+ * plugin that should be used to connect to this VPN.
+ *
+ * Returns: the VPN plugin's service name
+ **/
 const char *
 nm_setting_vpn_get_service_type (NMSettingVPN *setting)
 {
@@ -122,6 +158,12 @@ nm_setting_vpn_get_service_type (NMSettingVPN *setting)
 	return NM_SETTING_VPN_GET_PRIVATE (setting)->service_type;
 }
 
+/**
+ * nm_setting_vpn_get_user_name:
+ * @setting: the #NMSettingVPN
+ *
+ * Returns: the #NMSettingVPN:user-name property of the setting
+ **/
 const char *
 nm_setting_vpn_get_user_name (NMSettingVPN *setting)
 {
@@ -130,6 +172,16 @@ nm_setting_vpn_get_user_name (NMSettingVPN *setting)
 	return NM_SETTING_VPN_GET_PRIVATE (setting)->user_name;
 }
 
+/**
+ * nm_setting_vpn_add_data_item:
+ * @setting: the #NMSettingVPN
+ * @key: a name that uniquely identifies the given value @item
+ * @item: the value to be referenced by @key
+ *
+ * Establishes a relationship between @key and @item internally in the
+ * setting which may be retrieved later.  Should not be used to store passwords
+ * or other secrets, which is what nm_setting_vpn_add_secret() is for.
+ **/
 void
 nm_setting_vpn_add_data_item (NMSettingVPN *setting,
                               const char *key,
@@ -145,6 +197,16 @@ nm_setting_vpn_add_data_item (NMSettingVPN *setting,
 	                     g_strdup (key), g_strdup (item));
 }
 
+/**
+ * nm_setting_vpn_get_data_item:
+ * @setting: the #NMSettingVPN
+ * @key: the name of the data item to retrieve
+ *
+ * Retrieves the data item of a key/value relationship previously established
+ * by nm_setting_vpn_add_data_item().
+ *
+ * Returns: the data item, if any
+ **/
 const char *
 nm_setting_vpn_get_data_item (NMSettingVPN *setting, const char *key)
 {
@@ -153,6 +215,14 @@ nm_setting_vpn_get_data_item (NMSettingVPN *setting, const char *key)
 	return (const char *) g_hash_table_lookup (NM_SETTING_VPN_GET_PRIVATE (setting)->data, key);
 }
 
+/**
+ * nm_setting_vpn_remove_data_item:
+ * @setting: the #NMSettingVPN
+ * @key: the name of the data item to remove
+ *
+ * Deletes a key/value relationship previously established by
+ * nm_setting_vpn_add_data_item().
+ **/
 void
 nm_setting_vpn_remove_data_item (NMSettingVPN *setting, const char *key)
 {
@@ -212,6 +282,15 @@ nm_setting_vpn_foreach_data_item (NMSettingVPN *setting,
 	foreach_item_helper (NM_SETTING_VPN_GET_PRIVATE (setting)->data, func, user_data);
 }
 
+/**
+ * nm_setting_vpn_add_secret:
+ * @setting: the #NMSettingVPN
+ * @key: a name that uniquely identifies the given secret @secret
+ * @secret: the secret to be referenced by @key
+ *
+ * Establishes a relationship between @key and @secret internally in the
+ * setting which may be retrieved later.
+ **/
 void
 nm_setting_vpn_add_secret (NMSettingVPN *setting,
                            const char *key,
@@ -227,6 +306,16 @@ nm_setting_vpn_add_secret (NMSettingVPN *setting,
 	                     g_strdup (key), g_strdup (secret));
 }
 
+/**
+ * nm_setting_vpn_get_secret:
+ * @setting: the #NMSettingVPN
+ * @key: the name of the secret to retrieve
+ *
+ * Retrieves the secret of a key/value relationship previously established
+ * by nm_setting_vpn_add_secret().
+ *
+ * Returns: the secret, if any
+ **/
 const char *
 nm_setting_vpn_get_secret (NMSettingVPN *setting, const char *key)
 {
@@ -235,6 +324,14 @@ nm_setting_vpn_get_secret (NMSettingVPN *setting, const char *key)
 	return (const char *) g_hash_table_lookup (NM_SETTING_VPN_GET_PRIVATE (setting)->secrets, key);
 }
 
+/**
+ * nm_setting_vpn_remove_secret:
+ * @setting: the #NMSettingVPN
+ * @key: the name of the secret to remove
+ *
+ * Deletes a key/value relationship previously established by
+ * nm_setting_vpn_add_secret().
+ **/
 void
 nm_setting_vpn_remove_secret (NMSettingVPN *setting, const char *key)
 {

libnm-util/nm-setting-vpn.h

@@ -39,8 +39,14 @@ G_BEGIN_DECLS
 
 #define NM_SETTING_VPN_SETTING_NAME "vpn"
 
-typedef enum
-{
+/**
+ * NMSettingVPNError:
+ * @NM_SETTING_VPN_ERROR_UNKNOWN: unknown or unclassified error
+ * @NM_SETTING_VPN_ERROR_INVALID_PROPERTY: the property was invalid
+ * @NM_SETTING_VPN_ERROR_MISSING_PROPERTY: the property was missing and is
+ * required
+ */
+typedef enum {
 	NM_SETTING_VPN_ERROR_UNKNOWN = 0,
 	NM_SETTING_VPN_ERROR_INVALID_PROPERTY,
 	NM_SETTING_VPN_ERROR_MISSING_PROPERTY,
@@ -71,6 +77,13 @@ typedef struct {
 	void (*_reserved4) (void);
 } NMSettingVPNClass;
 
+/**
+ * NMVPNIterFunc:
+ * @key: the name of the data or secret item
+ * @value: the value of the data or secret item
+ * @user_data: User data passed to nm_setting_vpn_foreach_data_item() or
+ * nm_setting_vpn_foreach_secret()
+ **/
 typedef void (*NMVPNIterFunc) (const char *key, const char *value, gpointer user_data);
 
 GType nm_setting_vpn_get_type (void);