docs: misc small fixes

Cleans up all of the warnings that aren't overly annoying to clean up.

16 files changed, 114 insertions, 81 deletions

diff --git a/docs/libnm-glib/Makefile.am b/docs/libnm-glib/Makefile.am
index 9c2dbb3921..5c3c492ffc 100644
--- a/docs/libnm-glib/Makefile.am
+++ b/docs/libnm-glib/Makefile.am
@@ -30,6 +30,7 @@ CFILE_GLOB=$(top_srcdir)/libnm-glib/*.c
 
 # Header files to ignore when scanning.
 IGNORE_HFILES= \
+	common.h \
 	nm-dbus-helpers-private.h \
 	nm-device-private.h \
 	nm-object-cache.h \
diff --git a/docs/libnm-util/Makefile.am b/docs/libnm-util/Makefile.am
index 07bd2fe32e..f5c44ace85 100644
--- a/docs/libnm-util/Makefile.am
+++ b/docs/libnm-util/Makefile.am
@@ -35,7 +35,8 @@ IGNORE_HFILES= \
 	nm-utils-private.h \
 	nm-setting-private.h \
 	nm-param-spec-specialized.h \
-	nm-test-utils.h
+	nm-test-utils.h \
+	nm-version.h
 
 # Images to copy into HTML directory.
 HTML_IMAGES = 
diff --git a/docs/libnm-util/libnm-util-docs.sgml b/docs/libnm-util/libnm-util-docs.sgml
index 2a23a17366..14139181d6 100644
--- a/docs/libnm-util/libnm-util-docs.sgml
+++ b/docs/libnm-util/libnm-util-docs.sgml
@@ -73,6 +73,8 @@
     <xi:include href="xml/nm-setting-pppoe.xml"/>
     <xi:include href="xml/nm-setting-vpn.xml"/>
     <xi:include href="xml/nm-utils.xml"/>
+    <xi:include href="xml/NetworkManager.xml"/>
+    <xi:include href="xml/NetworkManagerVPN.xml"/>
 
   </chapter>
   <chapter id="object-tree">
diff --git a/libnm-core/nm-setting-ip-config.c b/libnm-core/nm-setting-ip-config.c
index b8cde39b3f..e6f0401a01 100644
--- a/libnm-core/nm-setting-ip-config.c
+++ b/libnm-core/nm-setting-ip-config.c
@@ -130,7 +130,8 @@ struct NMIPAddress {
 
 /**
  * nm_ip_address_new:
- * @family: the IP address family (%AF_INET or %AF_INET6)
+ * @family: the IP address family (<literal>AF_INET</literal> or
+ *   <literal>AF_INET6</literal>)
  * @addr: the IP address
  * @prefix: the address prefix length
  * @error: location to store error, or %NULL
@@ -166,7 +167,8 @@ nm_ip_address_new (int family,
 
 /**
  * nm_ip_address_new_binary:
- * @family: the IP address family (%AF_INET or %AF_INET6)
+ * @family: the IP address family (<literal>AF_INET</literal> or
+ *   <literal>AF_INET6</literal>)
  * @addr: the IP address
  * @prefix: the address prefix length
  * @error: location to store error, or %NULL
@@ -522,7 +524,8 @@ struct NMIPRoute {
 
 /**
  * nm_ip_route_new:
- * @family: the IP address family (%AF_INET or %AF_INET6)
+ * @family: the IP address family (<literal>AF_INET</literal> or
+ *   <literal>AF_INET6</literal>)
  * @dest: the IP address of the route's destination
  * @prefix: the address prefix length
  * @next_hop: (allow-none): the IP address of the next hop (or %NULL)
@@ -568,7 +571,8 @@ nm_ip_route_new (int family,
 
 /**
  * nm_ip_route_new_binary:
- * @family: the IP address family (%AF_INET or %AF_INET6)
+ * @family: the IP address family (<literal>AF_INET</literal> or
+ *   <literal>AF_INET6</literal>)
  * @dest: the IP address of the route's destination
  * @prefix: the address prefix length
  * @next_hop: (allow-none): the IP address of the next hop (or %NULL)
diff --git a/libnm-core/nm-utils.c b/libnm-core/nm-utils.c
index e5a49d74b1..e14775ff22 100644
--- a/libnm-core/nm-utils.c
+++ b/libnm-core/nm-utils.c
@@ -2549,12 +2549,13 @@ nm_utils_wifi_strength_bars (guint8 strength)
 
 /**
  * nm_utils_hwaddr_len:
- * @type: the type of address; either %ARPHRD_ETHER or %ARPHRD_INFINIBAND
+ * @type: the type of address; either <literal>ARPHRD_ETHER</literal> or
+ * <literal>ARPHRD_INFINIBAND</literal>
  *
  * Returns the length in octets of a hardware address of type @type.
  *
- * It is an error to call this function with any value other than %ARPHRD_ETHER
- * or %ARPHRD_INFINIBAND.
+ * It is an error to call this function with any value other than
+ * <literal>ARPHRD_ETHER</literal> or <literal>ARPHRD_INFINIBAND</literal>.
  *
  * Return value: the length.
  */
@@ -2812,10 +2813,11 @@ _nm_utils_hwaddr_canonical_or_invalid (const char *mac, gssize length)
  *      a zero-filled buffer @hwaddr1_len or @hwaddr2_len bytes long.
  *
  *   3. If @hwaddr1 and @hwaddr2 are InfiniBand hardware addresses (that is, if
- *      they are %INFINIBAND_ALEN bytes long in binary form) then only the last
- *      8 bytes are compared, since those are the only bytes that actually
- *      identify the hardware. (The other 12 bytes will change depending on the
- *      configuration of the InfiniBand fabric that the device is connected to.)
+ *      they are <literal>INFINIBAND_ALEN</literal> bytes long in binary form)
+ *      then only the last 8 bytes are compared, since those are the only bytes
+ *      that actually identify the hardware. (The other 12 bytes will change
+ *      depending on the configuration of the InfiniBand fabric that the device
+ *      is connected to.)
  *
  * If a passed-in ASCII hardware address cannot be parsed, or would parse to an
  * address larger than %NM_UTILS_HWADDR_LEN_MAX, then it will silently fail to
@@ -3082,13 +3084,14 @@ static char _nm_utils_inet_ntop_buffer[NM_UTILS_INET_ADDRSTRLEN];
 /**
  * nm_utils_inet4_ntop: (skip)
  * @inaddr: the address that should be converted to string.
- * @dst: the destination buffer, it must contain at least %INET_ADDRSTRLEN
- *  or %NM_UTILS_INET_ADDRSTRLEN characters. If set to %NULL, it will return
- *  a pointer to an internal, static buffer (shared with nm_utils_inet6_ntop()).
- *  Beware, that the internal buffer will be overwritten with ever new call
- *  of nm_utils_inet4_ntop() or nm_utils_inet6_ntop() that does not provied it's
- *  own @dst buffer. Also, using the internal buffer is not thread safe. When
- *  in doubt, pass your own @dst buffer to avoid these issues.
+ * @dst: the destination buffer, it must contain at least
+ *  <literal>INET_ADDRSTRLEN</literal> or %NM_UTILS_INET_ADDRSTRLEN
+ *  characters. If set to %NULL, it will return a pointer to an internal, static
+ *  buffer (shared with nm_utils_inet6_ntop()).  Beware, that the internal
+ *  buffer will be overwritten with ever new call of nm_utils_inet4_ntop() or
+ *  nm_utils_inet6_ntop() that does not provied it's own @dst buffer. Also,
+ *  using the internal buffer is not thread safe. When in doubt, pass your own
+ *  @dst buffer to avoid these issues.
  *
  * Wrapper for inet_ntop.
  *
@@ -3105,13 +3108,14 @@ nm_utils_inet4_ntop (in_addr_t inaddr, char *dst)
 /**
  * nm_utils_inet6_ntop: (skip)
  * @in6addr: the address that should be converted to string.
- * @dst: the destination buffer, it must contain at least %INET6_ADDRSTRLEN
- *  or %NM_UTILS_INET_ADDRSTRLEN characters. If set to %NULL, it will return
- *  a pointer to an internal, static buffer (shared with nm_utils_inet4_ntop()).
- *  Beware, that the internal buffer will be overwritten with ever new call
- *  of nm_utils_inet4_ntop() or nm_utils_inet6_ntop() that does not provied it's
- *  own @dst buffer. Also, using the internal buffer is not thread safe. When
- *  in doubt, pass your own @dst buffer to avoid these issues.
+ * @dst: the destination buffer, it must contain at least
+ *  <literal>INET6_ADDRSTRLEN</literal> or %NM_UTILS_INET_ADDRSTRLEN
+ *  characters. If set to %NULL, it will return a pointer to an internal, static
+ *  buffer (shared with nm_utils_inet4_ntop()).  Beware, that the internal
+ *  buffer will be overwritten with ever new call of nm_utils_inet4_ntop() or
+ *  nm_utils_inet6_ntop() that does not provied it's own @dst buffer. Also,
+ *  using the internal buffer is not thread safe. When in doubt, pass your own
+ *  @dst buffer to avoid these issues.
  *
  * Wrapper for inet_ntop.
  *
@@ -3129,7 +3133,8 @@ nm_utils_inet6_ntop (const struct in6_addr *in6addr, char *dst)
 
 /**
  * nm_utils_ipaddr_valid:
- * @family: %AF_INET or %AF_INET6, or %AF_UNSPEC to accept either
+ * @family: <literal>AF_INET</literal> or <literal>AF_INET6</literal>, or
+ *   <literal>AF_UNSPEC</literal> to accept either
  * @ip: an IP address
  *
  * Checks if @ip contains a valid IP address of the given family.
diff --git a/libnm-glib/nm-client.c b/libnm-glib/nm-client.c
index ac26143d18..a29664c6ba 100644
--- a/libnm-glib/nm-client.c
+++ b/libnm-glib/nm-client.c
@@ -360,9 +360,9 @@ client_recheck_permissions (DBusGProxy *proxy, gpointer user_data)
  * @client: a #NMClient
  *
  * Gets all the known network devices.  Use nm_device_get_type() or the
- * NM_IS_DEVICE_XXXX() functions to determine what kind of device member of the
- * returned array is, and then you may use device-specific methods such as
- * nm_device_ethernet_get_hw_address().
+ * <literal>NM_IS_DEVICE_XXXX</literal> functions to determine what kind of
+ * device member of the returned array is, and then you may use device-specific
+ * methods such as nm_device_ethernet_get_hw_address().
  *
  * Returns: (transfer none) (element-type NMDevice): a #GPtrArray
  * containing all the #NMDevices.  The returned array is owned by the
diff --git a/libnm-glib/nm-device.c b/libnm-glib/nm-device.c
index 53d2a69f74..bd5d16374e 100644
--- a/libnm-glib/nm-device.c
+++ b/libnm-glib/nm-device.c
@@ -1759,8 +1759,7 @@ get_short_vendor (NMDevice *device)
  * nm_device_get_description:
  * @device: an #NMDevice
  *
- * Gets a description of @device, incorporating the results of
- * nm_device_get_short_vendor() and nm_device_get_short_product().
+ * Gets a description of @device, based on its vendor and product names.
  *
  * Returns: a description of @device. If either the vendor or the
  *   product name is unknown, this returns the interface name.
diff --git a/libnm-glib/nm-secret-agent.h b/libnm-glib/nm-secret-agent.h
index f593b3e648..b7df874531 100644
--- a/libnm-glib/nm-secret-agent.h
+++ b/libnm-glib/nm-secret-agent.h
@@ -59,7 +59,7 @@ typedef enum {
  * NMSecretAgentCapabilities:
  * @NM_SECRET_AGENT_CAPABILITY_NONE: the agent supports no special capabilities
  * @NM_SECRET_AGENT_CAPABILITY_VPN_HINTS: the agent supports sending hints given
- * by the NMSecretAgentClass::get_secrets() class method to VPN plugin
+ * by the <literal>get_secrets</literal> class method to VPN plugin
  * authentication dialogs.
  * @NM_SECRET_AGENT_CAPABILITY_LAST: bounds checking value; should not be used.
  *
diff --git a/libnm-glib/nm-wimax-nsp.h b/libnm-glib/nm-wimax-nsp.h
index e0cfe1e895..74008d18e0 100644
--- a/libnm-glib/nm-wimax-nsp.h
+++ b/libnm-glib/nm-wimax-nsp.h
@@ -40,6 +40,15 @@ G_BEGIN_DECLS
 #define NM_WIMAX_NSP_SIGNAL_QUALITY "signal-quality"
 #define NM_WIMAX_NSP_NETWORK_TYPE   "network-type"
 
+/**
+ * NMWimaxNspNetworkType:
+ * @NM_WIMAX_NSP_NETWORK_TYPE_UNKNOWN: unknown network type
+ * @NM_WIMAX_NSP_NETWORK_TYPE_HOME: home network
+ * @NM_WIMAX_NSP_NETWORK_TYPE_PARTNER: partner network
+ * @NM_WIMAX_NSP_NETWORK_TYPE_ROAMING_PARTNER: roaming partner network
+ *
+ * WiMAX network type.
+ */
 typedef enum {
 	NM_WIMAX_NSP_NETWORK_TYPE_UNKNOWN         = 0,
 	NM_WIMAX_NSP_NETWORK_TYPE_HOME            = 1,
diff --git a/libnm-util/nm-setting-8021x.c b/libnm-util/nm-setting-8021x.c
index 53d59a07d7..6d5268a17b 100644
--- a/libnm-util/nm-setting-8021x.c
+++ b/libnm-util/nm-setting-8021x.c
@@ -840,7 +840,7 @@ nm_setting_802_1x_get_client_cert_path (NMSetting8021x *setting)
  * @setting: the #NMSetting8021x
  * @cert_path: when @scheme is set to either %NM_SETTING_802_1X_CK_SCHEME_PATH
  *   or %NM_SETTING_802_1X_CK_SCHEME_BLOB, pass the path of the client
- *   certificate file (PEM, DER, or PKCS#12 format).  The path must be UTF-8
+ *   certificate file (PEM, DER, or PKCS#<!-- -->12 format).  The path must be UTF-8
  *   encoded; use g_filename_to_utf8() to convert if needed.  Passing %NULL with
  *   any @scheme clears the client certificate.
  * @scheme: desired storage scheme for the certificate
@@ -1425,7 +1425,7 @@ nm_setting_802_1x_get_phase2_client_cert_path (NMSetting8021x *setting)
  * @setting: the #NMSetting8021x
  * @cert_path: when @scheme is set to either %NM_SETTING_802_1X_CK_SCHEME_PATH
  *   or %NM_SETTING_802_1X_CK_SCHEME_BLOB, pass the path of the "phase2" client
- *   certificate file (PEM, DER, or PKCS#12 format).  The path must be UTF-8
+ *   certificate file (PEM, DER, or PKCS#<!-- -->12 format).  The path must be UTF-8
  *   encoded; use g_filename_to_utf8() to convert if needed.  Passing %NULL with
  *   any @scheme clears the "phase2" client certificate.
  * @scheme: desired storage scheme for the certificate
@@ -1700,7 +1700,7 @@ file_to_byte_array (const char *filename)
  * @setting: the #NMSetting8021x
  * @key_path: when @scheme is set to either %NM_SETTING_802_1X_CK_SCHEME_PATH or
  *   %NM_SETTING_802_1X_CK_SCHEME_BLOB, pass the path of the private key file
- *   (PEM, DER, or PKCS#12 format).  The path must be UTF-8 encoded; use
+ *   (PEM, DER, or PKCS#<!-- -->12 format).  The path must be UTF-8 encoded; use
  *   g_filename_to_utf8() to convert if needed.  Passing %NULL with any @scheme
  *   clears the private key.
  * @password: password used to decrypt the private key, or %NULL if the password
@@ -2011,7 +2011,7 @@ nm_setting_802_1x_get_phase2_private_key_path (NMSetting8021x *setting)
  * @setting: the #NMSetting8021x
  * @key_path: when @scheme is set to either %NM_SETTING_802_1X_CK_SCHEME_PATH or
  *   %NM_SETTING_802_1X_CK_SCHEME_BLOB, pass the path of the "phase2" private
- *   key file (PEM, DER, or PKCS#12 format).  The path must be UTF-8 encoded;
+ *   key file (PEM, DER, or PKCS#<!-- -->12 format).  The path must be UTF-8 encoded;
  *   use g_filename_to_utf8() to convert if needed.  Passing %NULL with any
  *   @scheme clears the private key.
  * @password: password used to decrypt the private key, or %NULL if the password
@@ -3530,15 +3530,15 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * should be set to the key's encrypted PEM encoded data. When using private
 	 * keys with the path scheme, this property should be set to the full UTF-8
 	 * encoded path of the key, prefixed with the string "file://" and ending
-	 * with a terminating NUL byte. When using PKCS#12 format private keys and
-	 * the blob scheme, this property should be set to the PKCS#12 data and the
+	 * with a terminating NUL byte. When using PKCS#<!-- -->12 format private keys and
+	 * the blob scheme, this property should be set to the PKCS#<!-- -->12 data and the
 	 * #NMSetting8021x:private-key-password property must be set to password
-	 * used to decrypt the PKCS#12 certificate and key. When using PKCS#12 files
+	 * used to decrypt the PKCS#<!-- -->12 certificate and key. When using PKCS#<!-- -->12 files
 	 * and the path scheme, this property should be set to the full UTF-8
 	 * encoded path of the key, prefixed with the string "file://" and and
 	 * ending with a terminating NUL byte, and as with the blob scheme the
 	 * "private-key-password" property must be set to the password used to
-	 * decode the PKCS#12 private key and certificate.
+	 * decode the PKCS#<!-- -->12 private key and certificate.
 	 *
 	 * Setting this property directly is discouraged; use the
 	 * nm_setting_802_1x_set_private_key() function instead.
@@ -3561,7 +3561,7 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 *
 	 * The password used to decrypt the private key specified in the
 	 * #NMSetting8021x:private-key property when the private key either uses the
-	 * path scheme, or if the private key is a PKCS#12 format key.  Setting this
+	 * path scheme, or if the private key is a PKCS#<!-- -->12 format key.  Setting this
 	 * property directly is not generally necessary except when returning
 	 * secrets to NetworkManager; it is generally set automatically when setting
 	 * the private key by the nm_setting_802_1x_set_private_key() function.
@@ -3601,15 +3601,15 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 * should be set to the key's encrypted PEM encoded data. When using private
 	 * keys with the path scheme, this property should be set to the full UTF-8
 	 * encoded path of the key, prefixed with the string "file://" and ending
-	 * with a terminating NUL byte. When using PKCS#12 format private keys and
-	 * the blob scheme, this property should be set to the PKCS#12 data and the
+	 * with a terminating NUL byte. When using PKCS#<!-- -->12 format private keys and
+	 * the blob scheme, this property should be set to the PKCS#<!-- -->12 data and the
 	 * #NMSetting8021x:phase2-private-key-password property must be set to
-	 * password used to decrypt the PKCS#12 certificate and key. When using
-	 * PKCS#12 files and the path scheme, this property should be set to the
+	 * password used to decrypt the PKCS#<!-- -->12 certificate and key. When using
+	 * PKCS#<!-- -->12 files and the path scheme, this property should be set to the
 	 * full UTF-8 encoded path of the key, prefixed with the string "file://"
 	 * and and ending with a terminating NUL byte, and as with the blob scheme
 	 * the #NMSetting8021x:phase2-private-key-password property must be set to
-	 * the password used to decode the PKCS#12 private key and certificate.
+	 * the password used to decode the PKCS#<!-- -->12 private key and certificate.
 	 *
 	 * Setting this property directly is discouraged; use the
 	 * nm_setting_802_1x_set_phase2_private_key() function instead.
@@ -3626,7 +3626,7 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
 	 *
 	 * The password used to decrypt the "phase 2" private key specified in the
 	 * #NMSetting8021x:phase2-private-key property when the private key either
-	 * uses the path scheme, or is a PKCS#12 format key.  Setting this property
+	 * uses the path scheme, or is a PKCS#<!-- -->12 format key.  Setting this property
 	 * directly is not generally necessary except when returning secrets to
 	 * NetworkManager; it is generally set automatically when setting the
 	 * private key by the nm_setting_802_1x_set_phase2_private_key() function.
diff --git a/libnm-util/nm-setting-8021x.h b/libnm-util/nm-setting-8021x.h
index 2121f63b62..62b4390502 100644
--- a/libnm-util/nm-setting-8021x.h
+++ b/libnm-util/nm-setting-8021x.h
@@ -33,7 +33,7 @@ G_BEGIN_DECLS
  * @NM_SETTING_802_1X_CK_FORMAT_X509: file contains an X.509 format certificate
  * @NM_SETTING_802_1X_CK_FORMAT_RAW_KEY: file contains an old-style OpenSSL PEM
  * or DER private key
- * @NM_SETTING_802_1X_CK_FORMAT_PKCS12: file contains a PKCS#12 certificate
+ * @NM_SETTING_802_1X_CK_FORMAT_PKCS12: file contains a PKCS#<!-- -->12 certificate
  * and private key
  *
  * #NMSetting8021xCKFormat values indicate the general type of a certificate
diff --git a/libnm-util/nm-setting-bluetooth.c b/libnm-util/nm-setting-bluetooth.c
index 4a9c8eb643..2867d73bae 100644
--- a/libnm-util/nm-setting-bluetooth.c
+++ b/libnm-util/nm-setting-bluetooth.c
@@ -103,7 +103,8 @@ NMSetting *nm_setting_bluetooth_new (void)
  * 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
+ * Returns: the type, either %NM_SETTING_BLUETOOTH_TYPE_PANU or
+ *   %NM_SETTING_BLUETOOTH_TYPE_DUN
  **/
 const char *
 nm_setting_bluetooth_get_connection_type (NMSettingBluetooth *setting)
diff --git a/libnm-util/nm-utils.c b/libnm-util/nm-utils.c
index b6a9dc3004..203803f238 100644
--- a/libnm-util/nm-utils.c
+++ b/libnm-util/nm-utils.c
@@ -1730,9 +1730,9 @@ nm_utils_rsa_key_encrypt_aes (const GByteArray *data,
  * nm_utils_file_is_pkcs12:
  * @filename: name of the file to test
  *
- * Utility function to find out if the @filename is in PKCS#12 format.
+ * Utility function to find out if the @filename is in PKCS#<!-- -->12 format.
  *
- * Returns: %TRUE if the file is PKCS#12, %FALSE if it is not
+ * Returns: %TRUE if the file is PKCS#<!-- -->12, %FALSE if it is not
  **/
 gboolean
 nm_utils_file_is_pkcs12 (const char *filename)
@@ -2027,7 +2027,8 @@ nm_utils_wifi_is_channel_valid (guint32 channel, const char *band)
 
 /**
  * nm_utils_hwaddr_len:
- * @type: the type of address; either %ARPHRD_ETHER or %ARPHRD_INFINIBAND
+ * @type: the type of address; either <literal>ARPHRD_ETHER</literal> or
+ *   <literal>ARPHRD_INFINIBAND</literal>
  *
  * Returns the length in octets of a hardware address of type @type.
  *
@@ -2048,11 +2049,12 @@ nm_utils_hwaddr_len (int type)
  * nm_utils_hwaddr_type:
  * @len: the length of hardware address in bytes
  *
- * Returns the type (either %ARPHRD_ETHER or %ARPHRD_INFINIBAND) of
- * the raw address given its length.
+ * Returns the type (either <literal>ARPHRD_ETHER</literal> or
+ * <literal>ARPHRD_INFINIBAND</literal>) of the raw address given its length.
  *
- * Return value: the type, either %ARPHRD_ETHER or %ARPHRD_INFINIBAND.
- * If the length is unexpected, return -1 (unsupported type/length).
+ * Return value: the type, either <literal>ARPHRD_ETHER</literal> or
+ * <literal>ARPHRD_INFINIBAND</literal>.  If the length is unexpected, return -1
+ * (unsupported type/length).
  *
  * Deprecated: This could not be extended to cover other types, since
  * there is not a one-to-one mapping between types and lengths. This
@@ -2077,7 +2079,8 @@ nm_utils_hwaddr_type (int len)
 /**
  * nm_utils_hwaddr_aton:
  * @asc: the ASCII representation of a hardware address
- * @type: the type of address; either %ARPHRD_ETHER or %ARPHRD_INFINIBAND
+ * @type: the type of address; either <literal>ARPHRD_ETHER</literal> or
+ *   <literal>ARPHRD_INFINIBAND</literal>
  * @buffer: buffer to store the result into
  *
  * Parses @asc and converts it to binary form in @buffer. See
@@ -2104,7 +2107,8 @@ nm_utils_hwaddr_aton (const char *asc, int type, gpointer buffer)
 /**
  * nm_utils_hwaddr_atoba:
  * @asc: the ASCII representation of a hardware address
- * @type: the type of address; either %ARPHRD_ETHER or %ARPHRD_INFINIBAND
+ * @type: the type of address; either <literal>ARPHRD_ETHER</literal> or
+ *   <literal>ARPHRD_INFINIBAND</literal>
  *
  * Parses @asc and converts it to binary form in a #GByteArray. See
  * nm_utils_hwaddr_aton() if you don't want a #GByteArray.
@@ -2136,7 +2140,8 @@ nm_utils_hwaddr_atoba (const char *asc, int type)
 /**
  * nm_utils_hwaddr_ntoa:
  * @addr: a binary hardware address
- * @type: the type of address; either %ARPHRD_ETHER or %ARPHRD_INFINIBAND
+ * @type: the type of address; either <literal>ARPHRD_ETHER</literal> or
+ *   <literal>ARPHRD_INFINIBAND</literal>
  *
  * Converts @addr to textual form.
  *
@@ -2469,13 +2474,14 @@ static char _nm_utils_inet_ntop_buffer[NM_UTILS_INET_ADDRSTRLEN];
 /**
  * nm_utils_inet4_ntop: (skip)
  * @inaddr: the address that should be converted to string.
- * @dst: the destination buffer, it must contain at least %INET_ADDRSTRLEN
- *  or %NM_UTILS_INET_ADDRSTRLEN characters. If set to %NULL, it will return
- *  a pointer to an internal, static buffer (shared with nm_utils_inet6_ntop()).
- *  Beware, that the internal buffer will be overwritten with ever new call
- *  of nm_utils_inet4_ntop() or nm_utils_inet6_ntop() that does not provied it's
- *  own @dst buffer. Also, using the internal buffer is not thread safe. When
- *  in doubt, pass your own @dst buffer to avoid these issues.
+ * @dst: the destination buffer, it must contain at least
+ *  <literal>INET_ADDRSTRLEN</literal> or %NM_UTILS_INET_ADDRSTRLEN
+ *  characters. If set to %NULL, it will return a pointer to an internal, static
+ *  buffer (shared with nm_utils_inet6_ntop()).  Beware, that the internal
+ *  buffer will be overwritten with ever new call of nm_utils_inet4_ntop() or
+ *  nm_utils_inet6_ntop() that does not provied it's own @dst buffer. Also,
+ *  using the internal buffer is not thread safe. When in doubt, pass your own
+ *  @dst buffer to avoid these issues.
  *
  * Wrapper for inet_ntop.
  *
@@ -2494,13 +2500,14 @@ nm_utils_inet4_ntop (in_addr_t inaddr, char *dst)
 /**
  * nm_utils_inet6_ntop: (skip)
  * @in6addr: the address that should be converted to string.
- * @dst: the destination buffer, it must contain at least %INET6_ADDRSTRLEN
- *  or %NM_UTILS_INET_ADDRSTRLEN characters. If set to %NULL, it will return
- *  a pointer to an internal, static buffer (shared with nm_utils_inet4_ntop()).
- *  Beware, that the internal buffer will be overwritten with ever new call
- *  of nm_utils_inet4_ntop() or nm_utils_inet6_ntop() that does not provied it's
- *  own @dst buffer. Also, using the internal buffer is not thread safe. When
- *  in doubt, pass your own @dst buffer to avoid these issues.
+ * @dst: the destination buffer, it must contain at least
+ *  <literal>INET6_ADDRSTRLEN</literal> or %NM_UTILS_INET_ADDRSTRLEN
+ *  characters. If set to %NULL, it will return a pointer to an internal, static
+ *  buffer (shared with nm_utils_inet4_ntop()).  Beware, that the internal
+ *  buffer will be overwritten with ever new call of nm_utils_inet4_ntop() or
+ *  nm_utils_inet6_ntop() that does not provied it's own @dst buffer. Also,
+ *  using the internal buffer is not thread safe. When in doubt, pass your own
+ *  @dst buffer to avoid these issues.
  *
  * Wrapper for inet_ntop.
  *
diff --git a/libnm/nm-client.c b/libnm/nm-client.c
index 729dab62a6..ef73e329b2 100644
--- a/libnm/nm-client.c
+++ b/libnm/nm-client.c
@@ -702,9 +702,9 @@ nm_client_save_hostname_finish (NMClient *client,
  * @client: a #NMClient
  *
  * Gets all the known network devices.  Use nm_device_get_type() or the
- * NM_IS_DEVICE_XXXX() functions to determine what kind of device member of the
- * returned array is, and then you may use device-specific methods such as
- * nm_device_ethernet_get_hw_address().
+ * <literal>NM_IS_DEVICE_XXXX</literal> functions to determine what kind of
+ * device member of the returned array is, and then you may use device-specific
+ * methods such as nm_device_ethernet_get_hw_address().
  *
  * Returns: (transfer none) (element-type NMDevice): a #GPtrArray
  * containing all the #NMDevices.  The returned array is owned by the
diff --git a/libnm/nm-dhcp-config.c b/libnm/nm-dhcp-config.c
index 4a58bf27a6..7227abac33 100644
--- a/libnm/nm-dhcp-config.c
+++ b/libnm/nm-dhcp-config.c
@@ -143,7 +143,8 @@ nm_dhcp_config_class_init (NMDhcpConfigClass *config_class)
 	/**
 	 * NMDhcpConfig:family:
 	 *
-	 * The IP address family of the configuration; either %AF_INET or %AF_INET6.
+	 * The IP address family of the configuration; either
+	 * <literal>AF_INET</literal> or <literal>AF_INET6</literal>.
 	 **/
 	g_object_class_install_property
 		(object_class, PROP_FAMILY,
@@ -173,7 +174,8 @@ nm_dhcp_config_class_init (NMDhcpConfigClass *config_class)
  *
  * Gets the IP address family of the configuration
  *
- * Returns: the IP address family; either %AF_INET or %AF_INET6
+ * Returns: the IP address family; either <literal>AF_INET</literal> or
+ *   <literal>AF_INET6</literal>
  **/
 int
 nm_dhcp_config_get_family (NMDhcpConfig *config)
diff --git a/libnm/nm-ip-config.c b/libnm/nm-ip-config.c
index e8c450fa39..d057903e27 100644
--- a/libnm/nm-ip-config.c
+++ b/libnm/nm-ip-config.c
@@ -269,7 +269,8 @@ nm_ip_config_class_init (NMIPConfigClass *config_class)
 	/**
 	 * NMIPConfig:family:
 	 *
-	 * The IP address family of the configuration; either %AF_INET or %AF_INET6.
+	 * The IP address family of the configuration; either
+	 * <literal>AF_INET</literal> or <literal>AF_INET6</literal>.
 	 **/
 	g_object_class_install_property
 	    (object_class, PROP_FAMILY,
@@ -370,7 +371,8 @@ nm_ip_config_class_init (NMIPConfigClass *config_class)
  *
  * Gets the IP address family
  *
- * Returns: the IP address family; either %AF_INET or %AF_INET6
+ * Returns: the IP address family; either <literal>AF_INET</literal> or
+ * <literal>AF_INET6</literal>
  **/
 int
 nm_ip_config_get_family (NMIPConfig *config)