docs: document Bluetooth setting more fully

2 files changed, 69 insertions, 4 deletions

diff --git a/libnm-util/nm-setting-bluetooth.c b/libnm-util/nm-setting-bluetooth.c
index e3cebe2ee4..50d8de50d3 100644
--- a/libnm-util/nm-setting-bluetooth.c
+++ b/libnm-util/nm-setting-bluetooth.c
@@ -34,6 +34,24 @@
 #include "nm-setting-cdma.h"
 #include "nm-setting-gsm.h"
 
+/**
+ * SECTION:nm-setting-bluetooth
+ * @short_description: Describes Bluetooth connection properties
+ * @include: nm-setting-bluetooth.h
+ *
+ * The #NMSettingBluetooth object is a #NMSetting subclass that describes
+ * properties necessary for connection to devices that provide network
+ * connections via the Bluetooth Dial-Up Networking (DUN) and Network Access
+ * Point (NAP) profiles.
+ **/
+
+/**
+ * nm_setting_bluetooth_error_quark:
+ *
+ * Registers an error quark for #NMSettingBluetooth if necessary.
+ *
+ * Returns: the error quark used for #NMSettingBluetooth errors.
+ **/
 GQuark
 nm_setting_bluetooth_error_quark (void)
 {
@@ -83,11 +101,27 @@ enum {
 	LAST_PROP
 };
 
+/**
+ * nm_setting_bluetooth_new:
+ *
+ * Creates a new #NMSettingBluetooth object with default values.
+ *
+ * Returns: the new empty #NMSettingBluetooth object
+ **/
 NMSetting *nm_setting_bluetooth_new (void)
 {
 	return (NMSetting *) g_object_new (NM_TYPE_SETTING_BLUETOOTH, NULL);
 }
 
+/**
+ * nm_setting_bluetooth_get_connection_type:
+ * @setting: the #NMSettingBluetooth
+ *
+ * Returns the connection method for communicating with the remote device (i.e.
+ * either DUN to a DUN-capable device or PANU to a NAP-capable device).
+ *
+ * Returns: the type, either %NM_SETTING_BLUETOOTH_PANU or %NM_SETTING_BLUETOOTH_DUN
+ **/
 const char *
 nm_setting_bluetooth_get_connection_type (NMSettingBluetooth *setting)
 {
@@ -96,6 +130,15 @@ nm_setting_bluetooth_get_connection_type (NMSettingBluetooth *setting)
 	return NM_SETTING_BLUETOOTH_GET_PRIVATE (setting)->type;
 }
 
+/**
+ * nm_setting_bluetooth_get_bdaddr:
+ * @setting: the #NMSettingBluetooth
+ *
+ * Gets the Bluetooth address of the remote device which this setting
+ * describes a connection to.
+ *
+ * Returns: the Bluetooth address
+ **/
 const GByteArray *
 nm_setting_bluetooth_get_bdaddr (NMSettingBluetooth *setting)
 {
@@ -266,8 +309,8 @@ nm_setting_bluetooth_class_init (NMSettingBluetoothClass *setting_class)
 	/**
 	 * NMSettingBluetooth:type:
 	 *
-	 * Either 'dun' for Dial-Up Networking connections (not yet supported) or
-	 * 'panu' for Personal Area Networking connections.
+	 * Either 'dun' for Dial-Up Networking connections or 'panu' for Personal
+	 * Area Networking connections to devices supporting the NAP profile.
 	 **/
 	g_object_class_install_property
 		(object_class, PROP_TYPE,
diff --git a/libnm-util/nm-setting-bluetooth.h b/libnm-util/nm-setting-bluetooth.h
index e41183bc26..a17a72bf40 100644
--- a/libnm-util/nm-setting-bluetooth.h
+++ b/libnm-util/nm-setting-bluetooth.h
@@ -40,8 +40,17 @@ G_BEGIN_DECLS
 
 #define NM_SETTING_BLUETOOTH_SETTING_NAME "bluetooth"
 
-typedef enum
-{
+/**
+ * NMSettingBluetoothError:
+ * @NM_SETTING_BLUETOOTH_ERROR_UNKNOWN: unknown or unclassified error
+ * @NM_SETTING_BLUETOOTH_ERROR_INVALID_PROPERTY: the property was invalid
+ * @NM_SETTING_BLUETOOTH_ERROR_MISSING_PROPERTY: the property was missing and is
+ * required
+ * @NM_SETTING_BLUETOOTH_ERROR_TYPE_SETTING_NOT_FOUND: the connection
+ * did not contain a required type setting, ie for DUN connections the connection
+ * must also contain an #NMSettingGsm or #NMSettingCdma as appropriate
+ */
+typedef enum {
 	NM_SETTING_BLUETOOTH_ERROR_UNKNOWN = 0,
 	NM_SETTING_BLUETOOTH_ERROR_INVALID_PROPERTY,
 	NM_SETTING_BLUETOOTH_ERROR_MISSING_PROPERTY,
@@ -57,7 +66,20 @@ GQuark nm_setting_bluetooth_error_quark (void);
 #define NM_SETTING_BLUETOOTH_BDADDR    "bdaddr"
 #define NM_SETTING_BLUETOOTH_TYPE      "type"
 
+/**
+ * NM_SETTING_BLUETOOTH_TYPE_DUN:
+ *
+ * Connection type describing a connection to devices that support the Bluetooth
+ * DUN profile.
+ */
 #define NM_SETTING_BLUETOOTH_TYPE_DUN  "dun"
+
+/**
+ * NM_SETTING_BLUETOOTH_TYPE_PANU:
+ *
+ * Connection type describing a connection to devices that support the Bluetooth
+ * NAP (Network Access Point) protocol, which accepts connections via PANU.
+ */
 #define NM_SETTING_BLUETOOTH_TYPE_PANU "panu"
 
 typedef struct {