docs: update GSM setting documentation

libnm-util/nm-setting-gsm.c

@@ -29,6 +29,23 @@
 #include "nm-utils.h"
 #include "nm-setting-private.h"
 
+/**
+ * SECTION:nm-setting-gsm
+ * @short_description: Describes GSM/3GPP-based mobile broadband properties
+ * @include: nm-setting-gsm.h
+ *
+ * The #NMSettingGsm object is a #NMSetting subclass that describes
+ * properties that allow connections to 3GPP-based mobile broadband
+ * networks, including those using GPRS/EDGE and UMTS/HSPA technology.
+ */
+
+/**
+ * nm_setting_gsm_error_quark:
+ *
+ * Registers an error quark for #NMSettingGsm if necessary.
+ *
+ * Returns: the error quark used for #NMSettingGsm errors.
+ **/
 GQuark
 nm_setting_gsm_error_quark (void)
 {
@@ -103,12 +120,25 @@ enum {
 	LAST_PROP
 };
 
+/**
+ * nm_setting_gsm_new:
+ *
+ * Creates a new #NMSettingGsm object with default values.
+ *
+ * Returns: the new empty #NMSettingGsm object
+ **/
 NMSetting *
 nm_setting_gsm_new (void)
 {
 	return (NMSetting *) g_object_new (NM_TYPE_SETTING_GSM, NULL);
 }
 
+/**
+ * nm_setting_gsm_get_number:
+ * @setting: the #NMSettingGsm
+ *
+ * Returns: the #NMSettingGsm:number property of the setting
+ **/
 const char *
 nm_setting_gsm_get_number (NMSettingGsm *setting)
 {
@@ -117,6 +147,12 @@ nm_setting_gsm_get_number (NMSettingGsm *setting)
 	return NM_SETTING_GSM_GET_PRIVATE (setting)->number;
 }
 
+/**
+ * nm_setting_gsm_get_username:
+ * @setting: the #NMSettingGsm
+ *
+ * Returns: the #NMSettingGsm:username property of the setting
+ **/
 const char *
 nm_setting_gsm_get_username (NMSettingGsm *setting)
 {
@@ -125,6 +161,12 @@ nm_setting_gsm_get_username (NMSettingGsm *setting)
 	return NM_SETTING_GSM_GET_PRIVATE (setting)->username;
 }
 
+/**
+ * nm_setting_gsm_get_password:
+ * @setting: the #NMSettingGsm
+ *
+ * Returns: the #NMSettingGsm:password property of the setting
+ **/
 const char *
 nm_setting_gsm_get_password (NMSettingGsm *setting)
 {
@@ -147,6 +189,12 @@ nm_setting_gsm_get_password_flags (NMSettingGsm *setting)
 	return NM_SETTING_GSM_GET_PRIVATE (setting)->password_flags;
 }
 
+/**
+ * nm_setting_gsm_get_apn:
+ * @setting: the #NMSettingGsm
+ *
+ * Returns: the #NMSettingGsm:apn property of the setting
+ **/
 const char *
 nm_setting_gsm_get_apn (NMSettingGsm *setting)
 {
@@ -155,6 +203,12 @@ nm_setting_gsm_get_apn (NMSettingGsm *setting)
 	return NM_SETTING_GSM_GET_PRIVATE (setting)->apn;
 }
 
+/**
+ * nm_setting_gsm_get_network_id:
+ * @setting: the #NMSettingGsm
+ *
+ * Returns: the #NMSettingGsm:network-id property of the setting
+ **/
 const char *
 nm_setting_gsm_get_network_id (NMSettingGsm *setting)
 {
@@ -163,6 +217,12 @@ nm_setting_gsm_get_network_id (NMSettingGsm *setting)
 	return NM_SETTING_GSM_GET_PRIVATE (setting)->network_id;
 }
 
+/**
+ * nm_setting_gsm_get_network_type:
+ * @setting: the #NMSettingGsm
+ *
+ * Returns: the #NMSettingGsm:network-type property of the setting
+ **/
 int
 nm_setting_gsm_get_network_type (NMSettingGsm *setting)
 {
@@ -171,6 +231,12 @@ nm_setting_gsm_get_network_type (NMSettingGsm *setting)
 	return NM_SETTING_GSM_GET_PRIVATE (setting)->network_type;
 }
 
+/**
+ * nm_setting_gsm_get_allowed_bands:
+ * @setting: the #NMSettingGsm
+ *
+ * Returns: the #NMSettingGsm:allowed-bands property of the setting
+ **/
 guint32
 nm_setting_gsm_get_allowed_bands (NMSettingGsm *setting)
 {
@@ -179,6 +245,12 @@ nm_setting_gsm_get_allowed_bands (NMSettingGsm *setting)
 	return NM_SETTING_GSM_GET_PRIVATE (setting)->allowed_bands;
 }
 
+/**
+ * nm_setting_gsm_get_pin:
+ * @setting: the #NMSettingGsm
+ *
+ * Returns: the #NMSettingGsm:pin property of the setting
+ **/
 const char *
 nm_setting_gsm_get_pin (NMSettingGsm *setting)
 {
@@ -201,6 +273,12 @@ nm_setting_gsm_get_pin_flags (NMSettingGsm *setting)
 	return NM_SETTING_GSM_GET_PRIVATE (setting)->pin_flags;
 }
 
+/**
+ * nm_setting_gsm_get_home_only:
+ * @setting: the #NMSettingGsm
+ *
+ * Returns: the #NMSettingGsm:home-only property of the setting
+ **/
 gboolean
 nm_setting_gsm_get_home_only (NMSettingGsm *setting)
 {
@@ -481,19 +559,20 @@ nm_setting_gsm_class_init (NMSettingGsmClass *setting_class)
 	 * NMSettingGsm:number:
 	 *
 	 * Number to dial when establishing a PPP data session with the GSM-based
-	 * mobile broadband network.  In most cases, leave the number blank and a
+	 * mobile broadband network.  Many modems do not require PPP for connections
-	 * number selecting the APN specified in the 'apn' property will be used
+	 * to the mobile network and thus this property should be left blank, which
-	 * automatically when required.
+	 * allows NetworkManager to select the appropriate settings automatically.
 	 **/
 	g_object_class_install_property
 		(object_class, PROP_NUMBER,
 		 g_param_spec_string (NM_SETTING_GSM_NUMBER,
 						  "Number",
-						  "Number to dial when establishing a PPP data session "
+		                  "Number to dial when establishing a PPP data session "
-						  "with the GSM-based mobile broadband network.  In most "
+		                  "with the GSM-based mobile broadband network.  Many "
-						  "cases, leave the number blank and a number selecting "
+		                  "modems do not require PPP for connections to the "
-						  "the APN specified in the 'apn' property will be used "
+		                  "mobile network and thus this property should be left "
-						  "automatically when required.",
+		                  "blank, which allows NetworkManager to select the "
+		                  "appropriate settings automatically.",
 						  NULL,
 						  G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE));
 
@@ -599,9 +678,9 @@ nm_setting_gsm_class_init (NMSettingGsmClass *setting_class)
 	 * NMSettingGsm:network-type:
 	 *
 	 * Network preference to force the device to only use specific network
-	 * technologies.  The permitted values are: -1: any, 0: 3G only,
+	 * technologies.  Permitted values are those specified by
-	 * 1: GPRS/EDGE only, 2: prefer 3G, and 3: prefer 2G.  Note that not all
+	 * #NMSettingGsmNetworkType.  Note that not all devices allow network
-	 * devices allow network preference control.
+	 * preference control.
 	 **/
 	g_object_class_install_property
 		(object_class, PROP_NETWORK_TYPE,
@@ -621,7 +700,8 @@ nm_setting_gsm_class_init (NMSettingGsmClass *setting_class)
 	 * NMSettingGsm:allowed-bands:
 	 *
 	 * Bitfield of allowed frequency bands.  Note that not all devices allow
-	 * frequency band control.
+	 * frequency band control.  Permitted values are those specified by
+	 * #NMSettingGsmNetworkBand.
 	 **/
 	g_object_class_install_property
 		(object_class, PROP_ALLOWED_BANDS,
@@ -668,7 +748,7 @@ nm_setting_gsm_class_init (NMSettingGsmClass *setting_class)
 	/**
 	 * NMSettingGsm:pin-flags:
 	 *
-	 * Flags indicating how to handle #NMSettingGsm:pin:.
+	 * Flags indicating how to handle #NMSettingGsm:pin.
 	 **/
 	g_object_class_install_property (object_class, PROP_PIN_FLAGS,
 		 g_param_spec_uint (NM_SETTING_GSM_PIN_FLAGS,

libnm-util/nm-setting-gsm.h

@@ -39,8 +39,16 @@ G_BEGIN_DECLS
 
 #define NM_SETTING_GSM_SETTING_NAME "gsm"
 
-typedef enum
+/**
-{
+ * NMSettingGsmError:
+ * @NM_SETTING_GSM_ERROR_UNKNOWN: unknown or unclassified error
+ * @NM_SETTING_GSM_ERROR_INVALID_PROPERTY: the property was invalid
+ * @NM_SETTING_GSM_ERROR_MISSING_PROPERTY: the property was missing and is
+ * required
+ * @NM_SETTING_GSM_ERROR_MISSING_SERIAL_SETTING: the required #NMSettingSerial
+ * is missing in the connection
+ */
+typedef enum {
 	NM_SETTING_GSM_ERROR_UNKNOWN = 0,
 	NM_SETTING_GSM_ERROR_INVALID_PROPERTY,
 	NM_SETTING_GSM_ERROR_MISSING_PROPERTY,
@@ -65,6 +73,21 @@ GQuark nm_setting_gsm_error_quark (void);
 #define NM_SETTING_GSM_PIN_FLAGS      "pin-flags"
 #define NM_SETTING_GSM_HOME_ONLY      "home-only"
 
+/**
+ * NMSettingGsmNetworkType:
+ * @NM_SETTING_GSM_NETWORK_TYPE_ANY: any access technology may be used
+ * @NM_SETTING_GSM_NETWORK_TYPE_UMTS_HSPA: only 3G-type (UMTS and HSPA)
+ * technologies may be used
+ * @NM_SETTING_GSM_NETWORK_TYPE_GPRS_EDGE: only 2G-type (GPRS and EDGE)
+ * technologies may be used
+ * @NM_SETTING_GSM_NETWORK_TYPE_PREFER_UMTS_HSPA: 3G-type technologies are
+ * preferred but 2G-type technologies may be used as a fallback
+ * @NM_SETTING_GSM_NETWORK_TYPE_PREFER_GPRS_EDGE: 2G-type technologies are
+ * preferred but 3G-type technologies may be used as a fallback
+ *
+ * #NMSettingGsmNetworkType values indicate the allowed access technologies
+ * the device may use when connecting to this network.
+ */
 typedef enum {
 	NM_SETTING_GSM_NETWORK_TYPE_ANY = -1,
 	NM_SETTING_GSM_NETWORK_TYPE_UMTS_HSPA = 0,
@@ -73,6 +96,27 @@ typedef enum {
 	NM_SETTING_GSM_NETWORK_TYPE_PREFER_GPRS_EDGE = 3
 } NMSettingGsmNetworkType;
 
+/**
+ * NMSettingGsmNetworkBand:
+ * @NM_SETTING_GSM_BAND_UNKNOWN: unknown or no band specified
+ * @NM_SETTING_GSM_BAND_ANY: any band is allowed
+ * @NM_SETTING_GSM_BAND_EGSM: 900 MHz original GSM band
+ * @NM_SETTING_GSM_BAND_DCS: 1800 MHz DCS band
+ * @NM_SETTING_GSM_BAND_PCS: US 1900 MHz PCS band
+ * @NM_SETTING_GSM_BAND_G850: US 850 MHz Cellular band
+ * @NM_SETTING_GSM_BAND_U2100: WCDMA 3GPP UMTS 2100 MHz (Class I)
+ * @NM_SETTING_GSM_BAND_U1800: WCDMA 3GPP UMTS 1800 MHz (Class III)
+ * @NM_SETTING_GSM_BAND_U17IV: WCDMA 3GPP AWS 1700/2100 MHz (Class IV)
+ * @NM_SETTING_GSM_BAND_U800: WCDMA 3GPP UMTS 800 MHz (Class VI)
+ * @NM_SETTING_GSM_BAND_U850: WCDMA 3GPP UMTS 850 MHz (Class V)
+ * @NM_SETTING_GSM_BAND_U900: WCDMA 3GPP UMTS 900 MHz (Class VIII)
+ * @NM_SETTING_GSM_BAND_U17IX: WCDMA 3GPP UMTS 1700 MHz (Class IX)
+ * @NM_SETTING_GSM_BAND_U1900: WCDMA 3GPP UMTS 1900 MHz (Class II)
+ * @NM_SETTING_GSM_BAND_U2600: WCDMA 3GPP UMTS 2600 MHz (Class VII, internal)
+ *
+ * #NMSettingGsmNetworkBand values indicate the allowed frequency bands
+ * the device may use when connecting to this network.
+ */
 typedef enum {
 	NM_SETTING_GSM_BAND_UNKNOWN      = 0x00000000,
 	NM_SETTING_GSM_BAND_ANY          = 0x00000001,