docs: update Wireless setting documentation

libnm-util/nm-setting-wireless.c

@@ -37,6 +37,22 @@
 #include "nm-dbus-glib-types.h"
 #include "nm-utils-private.h"
 
+/**
+ * SECTION:nm-setting-wireless
+ * @short_description: Describes connection properties for 802.11 WiFi networks
+ * @include: nm-setting-wireless.h
+ *
+ * The #NMSettingWireless object is a #NMSetting subclass that describes properties
+ * necessary for connection to 802.11 WiFi networks.
+ **/
+
+/**
+ * nm_setting_wireless_error_quark:
+ *
+ * Registers an error quark for #NMSettingWireless if necessary.
+ *
+ * Returns: the error quark used for #NMSettingWireless errors.
+ **/
 GQuark
 nm_setting_wireless_error_quark (void)
 {
@@ -130,6 +146,27 @@ match_cipher (const char *cipher,
 	return TRUE;
 }
 
+/**
+ * nm_setting_wireless_ap_security_compatible:
+ * @s_wireless: a #NMSettingWireless
+ * @s_wireless_sec: a #NMSettingWirelessSecurity or %NULL
+ * @ap_flags: the %NM80211ApFlags of the given access point
+ * @ap_wpa: the %NM80211ApSecurityFlags of the given access point's WPA
+ * capabilities
+ * @ap_rsn: the %NM80211ApSecurityFlags of the given access point's WPA2/RSN
+ * capabilities
+ * @ap_mode: the 802.11 mode of the AP, either Ad-Hoc or Infrastructure
+ *
+ * Given a #NMSettingWireless and an optional #NMSettingWirelessSecurity,
+ * determine if the configuration given by the settings is compatible with
+ * the security of an access point using that access point's capability flags
+ * and mode.  Useful for clients that wish to filter a set of connections
+ * against a set of access points and determine which connections are
+ * compatible with which access points.
+ *
+ * Returns: %TRUE if the given settings are compatible with the access point's
+ * security flags and mode, %FALSE if they are not.
+ */ 
 gboolean
 nm_setting_wireless_ap_security_compatible (NMSettingWireless *s_wireless,
                                             NMSettingWirelessSecurity *s_wireless_sec,
@@ -291,12 +328,25 @@ nm_setting_wireless_ap_security_compatible (NMSettingWireless *s_wireless,
 	return FALSE;
 }
 
+/**
+ * nm_setting_wireless_new:
+ *
+ * Creates a new #NMSettingWireless object with default values.
+ *
+ * Returns: the new empty #NMSettingWireless object
+ **/
 NMSetting *
 nm_setting_wireless_new (void)
 {
 	return (NMSetting *) g_object_new (NM_TYPE_SETTING_WIRELESS, NULL);
 }
 
+/**
+ * nm_setting_wireless_get_ssid:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:ssid property of the setting
+ **/
 const GByteArray *
 nm_setting_wireless_get_ssid (NMSettingWireless *setting)
 {
@@ -305,6 +355,12 @@ nm_setting_wireless_get_ssid (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->ssid;
 }
 
+/**
+ * nm_setting_wireless_get_mode:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:mode property of the setting
+ **/
 const char *
 nm_setting_wireless_get_mode (NMSettingWireless *setting)
 {
@@ -313,6 +369,12 @@ nm_setting_wireless_get_mode (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->mode;
 }
 
+/**
+ * nm_setting_wireless_get_band:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:band property of the setting
+ **/
 const char *
 nm_setting_wireless_get_band (NMSettingWireless *setting)
 {
@@ -321,6 +383,12 @@ nm_setting_wireless_get_band (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->band;
 }
 
+/**
+ * nm_setting_wireless_get_channel:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:channel property of the setting
+ **/
 guint32
 nm_setting_wireless_get_channel (NMSettingWireless *setting)
 {
@@ -329,6 +397,12 @@ nm_setting_wireless_get_channel (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->channel;
 }
 
+/**
+ * nm_setting_wireless_get_bssid:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:bssid property of the setting
+ **/
 const GByteArray *
 nm_setting_wireless_get_bssid (NMSettingWireless *setting)
 {
@@ -337,6 +411,12 @@ nm_setting_wireless_get_bssid (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->bssid;
 }
 
+/**
+ * nm_setting_wireless_get_rate:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:rate property of the setting
+ **/
 guint32
 nm_setting_wireless_get_rate (NMSettingWireless *setting)
 {
@@ -345,6 +425,12 @@ nm_setting_wireless_get_rate (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->rate;
 }
 
+/**
+ * nm_setting_wireless_get_tx_power:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:tx-power property of the setting
+ **/
 guint32
 nm_setting_wireless_get_tx_power (NMSettingWireless *setting)
 {
@@ -353,6 +439,12 @@ nm_setting_wireless_get_tx_power (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->tx_power;
 }
 
+/**
+ * nm_setting_wireless_get_mac_address:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:mac-address property of the setting
+ **/
 const GByteArray *
 nm_setting_wireless_get_mac_address (NMSettingWireless *setting)
 {
@@ -361,6 +453,12 @@ nm_setting_wireless_get_mac_address (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->device_mac_address;
 }
 
+/**
+ * nm_setting_wireless_get_cloned_mac_address:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:cloned-mac-address property of the setting
+ **/
 const GByteArray *
 nm_setting_wireless_get_cloned_mac_address (NMSettingWireless *setting)
 {
@@ -369,6 +467,13 @@ nm_setting_wireless_get_cloned_mac_address (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->cloned_mac_address;
 }
 
+/**
+ * nm_setting_wireless_get_mac_address_blacklist:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: (element-type GLib.ByteArray): the
+ * #NMSettingWireless:mac-address-blacklist property of the setting
+ **/
 const GSList *
 nm_setting_wireless_get_mac_address_blacklist (NMSettingWireless *setting)
 {
@@ -377,6 +482,12 @@ nm_setting_wireless_get_mac_address_blacklist (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->mac_address_blacklist;
 }
 
+/**
+ * nm_setting_wireless_get_mtu:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:mtu property of the setting
+ **/
 guint32
 nm_setting_wireless_get_mtu (NMSettingWireless *setting)
 {
@@ -385,6 +496,12 @@ nm_setting_wireless_get_mtu (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->mtu;
 }
 
+/**
+ * nm_setting_wireless_get_security:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the #NMSettingWireless:security property of the setting
+ **/
 const char *
 nm_setting_wireless_get_security (NMSettingWireless *setting)
 {
@@ -393,6 +510,17 @@ nm_setting_wireless_get_security (NMSettingWireless *setting)
 	return NM_SETTING_WIRELESS_GET_PRIVATE (setting)->security;
 }
 
+/**
+ * nm_setting_wireless_add_seen_bssid:
+ * @setting: the #NMSettingWireless
+ * @bssid: the new BSSID to add to the list
+ *
+ * Adds a new WiFi AP's BSSID to the previously seen BSSID list of the setting.
+ * NetworkManager tracks previously seen BSSIDs internally so this function
+ * no longer has much use.
+ *
+ * Returns: %TRUE if @bssid was already known, %FALSE if not
+ **/
 gboolean
 nm_setting_wireless_add_seen_bssid (NMSettingWireless *setting,
 									const char *bssid)
@@ -426,6 +554,12 @@ nm_setting_wireless_add_seen_bssid (NMSettingWireless *setting,
 	return !found;
 }
 
+/**
+ * nm_setting_wireless_get_num_seen_bssids:
+ * @setting: the #NMSettingWireless
+ *
+ * Returns: the number of BSSIDs in the previously seen BSSID list
+ **/
 guint32
 nm_setting_wireless_get_num_seen_bssids (NMSettingWireless *setting)
 {
@@ -434,6 +568,13 @@ nm_setting_wireless_get_num_seen_bssids (NMSettingWireless *setting)
 	return g_slist_length (NM_SETTING_WIRELESS_GET_PRIVATE (setting)->seen_bssids);
 }
 
+/**
+ * nm_setting_wireless_get_seen_bssid:
+ * @setting: the #NMSettingWireless
+ * @i: index of a BSSID in the previously seen BSSID list
+ *
+ * Returns: the BSSID at index @i
+ **/
 const char *
 nm_setting_wireless_get_seen_bssid (NMSettingWireless *setting,
 									guint32 i)
@@ -921,27 +1062,18 @@ nm_setting_wireless_class_init (NMSettingWirelessClass *setting_class)
 	 *
 	 * A list of BSSIDs (each BSSID formatted as a MAC address like
 	 * '00:11:22:33:44:55') that have been detected as part of the WiFI network.
-	 * The settings service will usually populate this property by periodically
+	 * NetworkManager internally tracks previously seen BSSIDs so this property
-	 * asking NetworkManager what the device's current AP is while connected
+	 * is no longer of much use.
-	 * to the network (or monitoring the device's 'active-ap' property) and
-	 * adding the current AP'sBSSID to this list.  This list helps NetworkManager
-	 * find hidden APs by matching up scan results with the BSSIDs in this list.
 	 **/
 	g_object_class_install_property
 		(object_class, PROP_SEEN_BSSIDS,
 		 _nm_param_spec_specialized (NM_SETTING_WIRELESS_SEEN_BSSIDS,
 							   "Seen BSSIDS",
 							   "A list of BSSIDs (each BSSID formatted as a MAC "
-							   "address like '00:11:22:33:44:55') that have been "
+							   "address like 00:11:22:33:44:55') that have been "
-							   "detected as part of the WiFI network.  The "
+							   "detected as part of the WiFI network. "
-							   "settings service will usually populate this "
+							   "NetworkManager internally tracks previously seen "
-							   "property by periodically asking NetworkManager "
+							   "BSSIDs so this property is no longer of much use.",
-							   "what the device's current AP is while connected "
-							   "to the network (or monitoring the device's "
-							   "'active-ap' property) and adding the current AP's "
-							   "BSSID to this list.  This list helps NetworkManager "
-							   "find hidden APs by matching up scan results with "
-							   "the BSSIDs in this list.",
 							   DBUS_TYPE_G_LIST_OF_STRING,
 							   G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE));
 

libnm-util/nm-setting-wireless.h

@@ -41,8 +41,18 @@ G_BEGIN_DECLS
 
 #define NM_SETTING_WIRELESS_SETTING_NAME "802-11-wireless"
 
-typedef enum
+/**
-{
+ * NMSettingWirelessError:
+ * @NM_SETTING_WIRELESS_ERROR_UNKNOWN: unknown or unclassified error
+ * @NM_SETTING_WIRELESS_ERROR_INVALID_PROPERTY: the property was invalid
+ * @NM_SETTING_WIRELESS_ERROR_MISSING_PROPERTY: the property was missing and is
+ * required
+ * @NM_SETTING_WIRELESS_ERROR_MISSING_SECURITY_SETTING: property values require
+ * the presence of an #NMSettingWirelessSecurity object in the connection
+ * @NM_SETTING_WIRELESS_ERROR_CHANNEL_REQUIRES_BAND: the property channel was
+ * set to a value that requires the #NMSettingWireless:band property to be set
+ */
+typedef enum {
 	NM_SETTING_WIRELESS_ERROR_UNKNOWN = 0,
 	NM_SETTING_WIRELESS_ERROR_INVALID_PROPERTY,
 	NM_SETTING_WIRELESS_ERROR_MISSING_PROPERTY,
@@ -70,7 +80,19 @@ GQuark nm_setting_wireless_error_quark (void);
 #define NM_SETTING_WIRELESS_SEEN_BSSIDS "seen-bssids"
 #define NM_SETTING_WIRELESS_SEC         "security"
 
+/**
+ * NM_SETTING_WIRELESS_MODE_ADHOC:
+ *
+ * Indicates Ad-Hoc mode where no access point is expected to be present.
+ */
 #define NM_SETTING_WIRELESS_MODE_ADHOC  "adhoc"
+
+/**
+ * NM_SETTING_WIRELESS_MODE_INFRA
+ *
+ * Indicates infrastructure mode where an access point is expected to be present
+ * for this connection.
+ */
 #define NM_SETTING_WIRELESS_MODE_INFRA  "infrastructure"
 
 typedef struct {