diff --git a/libnm-glib/nm-active-connection.c b/libnm-glib/nm-active-connection.c
index e446d93c2d..6b3c782154 100644
--- a/libnm-glib/nm-active-connection.c
+++ b/libnm-glib/nm-active-connection.c
@@ -204,7 +204,7 @@ _nm_active_connection_type_for_path_async (DBusGConnection *connection,
  * nm_active_connection_get_connection:
  * @connection: a #NMActiveConnection
  *
- * Gets the #NMConnection<!-- -->'s DBus object path.
+ * Gets the #NMConnection's DBus object path.
  *
  * Returns: the object path of the #NMConnection inside of #NMActiveConnection.
  * This is the internal string used by the connection, and must not be modified.
@@ -222,7 +222,7 @@ nm_active_connection_get_connection (NMActiveConnection *connection)
  * nm_active_connection_get_uuid:
  * @connection: a #NMActiveConnection
  *
- * Gets the #NMConnection<!-- -->'s UUID.
+ * Gets the #NMConnection's UUID.
  *
  * Returns: the UUID of the #NMConnection that backs the #NMActiveConnection.
  * This is the internal string used by the connection, and must not be modified.
@@ -258,9 +258,9 @@ nm_active_connection_get_specific_object (NMActiveConnection *connection)
  * nm_active_connection_get_devices:
  * @connection: a #NMActiveConnection
  *
- * Gets the #NMDevice<!-- -->s used for the active connections.
+ * Gets the #NMDevices used for the active connections.
  *
- * Returns: (element-type NMClient.Device): the #GPtrArray containing #NMDevice<!-- -->s.
+ * Returns: (element-type NMClient.Device): the #GPtrArray containing #NMDevices.
  * This is the internal copy used by the connection, and must not be modified.
  **/
 const GPtrArray *
diff --git a/libnm-glib/nm-client.c b/libnm-glib/nm-client.c
index 44fb24dc7d..f34b685ced 100644
--- a/libnm-glib/nm-client.c
+++ b/libnm-glib/nm-client.c
@@ -374,7 +374,7 @@ client_recheck_permissions (DBusGProxy *proxy, gpointer user_data)
  * nm_device_ethernet_get_hw_address().
  *
  * Returns: (transfer none) (element-type NMClient.Device): a #GPtrArray
- * containing all the #NMDevice<!-- -->s.  The returned array is owned by the
+ * containing all the #NMDevices.  The returned array is owned by the
  * #NMClient object and should not be modified.
  **/
 const GPtrArray *
@@ -789,7 +789,7 @@ nm_client_deactivate_connection (NMClient *client, NMActiveConnection *active)
  * Gets the active connections.
  *
  * Returns: (transfer none) (element-type NMClient.ActiveConnection): a #GPtrArray
- *  containing all the active #NMActiveConnection<!-- -->s.
+ *  containing all the active #NMActiveConnections.
  * The returned array is owned by the client and should not be modified.
  **/
 const GPtrArray * 
diff --git a/libnm-glib/nm-device-bond.c b/libnm-glib/nm-device-bond.c
index 0b313b17de..04188a43bf 100644
--- a/libnm-glib/nm-device-bond.c
+++ b/libnm-glib/nm-device-bond.c
@@ -144,7 +144,7 @@ nm_device_bond_get_carrier (NMDeviceBond *device)
  * Gets the devices currently slaved to @device.
  *
  * Returns: (element-type NMClient.Device): the #GPtrArray containing
- * #NMDevice<!-- -->s that are slaves of @device. This is the internal
+ * #NMDevices that are slaves of @device. This is the internal
  * copy used by the device, and must not be modified.
  *
  * Since: 0.9.6.4
diff --git a/libnm-glib/nm-device-bridge.c b/libnm-glib/nm-device-bridge.c
index 6e00920e13..e632a9b2ea 100644
--- a/libnm-glib/nm-device-bridge.c
+++ b/libnm-glib/nm-device-bridge.c
@@ -152,7 +152,7 @@ nm_device_bridge_get_carrier (NMDeviceBridge *device)
  * Gets the devices currently slaved to @device.
  *
  * Returns: (element-type NMClient.Device): the #GPtrArray containing
- * #NMDevice<!-- -->s that are slaves of @device. This is the internal
+ * #NMDevices that are slaves of @device. This is the internal
  * copy used by the device, and must not be modified.
  *
  * Since: 0.9.8
diff --git a/libnm-glib/nm-device-team.c b/libnm-glib/nm-device-team.c
index 3d1abedfdc..67f0d1d44f 100644
--- a/libnm-glib/nm-device-team.c
+++ b/libnm-glib/nm-device-team.c
@@ -142,7 +142,7 @@ nm_device_team_get_carrier (NMDeviceTeam *device)
  * Gets the devices currently enslaved to @device.
  *
  * Returns: (element-type NMClient.Device): the #GPtrArray containing
- * #NMDevice<!-- -->s that are slaves of @device. This is the internal
+ * #NMDevices that are slaves of @device. This is the internal
  * copy used by the device, and must not be modified.
  **/
 const GPtrArray *
diff --git a/libnm-glib/nm-device-wifi.c b/libnm-glib/nm-device-wifi.c
index ebad1210dc..69a3e0e5ca 100644
--- a/libnm-glib/nm-device-wifi.c
+++ b/libnm-glib/nm-device-wifi.c
@@ -278,7 +278,7 @@ nm_device_wifi_get_active_access_point (NMDeviceWifi *device)
  * Gets all the scanned access points of the #NMDeviceWifi.
  *
  * Returns: (element-type NMClient.AccessPoint): a #GPtrArray containing all the
- * scanned #NMAccessPoint<!-- -->s.
+ * scanned #NMAccessPoints.
  * The returned array is owned by the client and should not be modified.
  **/
 const GPtrArray *
diff --git a/libnm-glib/nm-device-wimax.c b/libnm-glib/nm-device-wimax.c
index c676e13440..012b926e98 100644
--- a/libnm-glib/nm-device-wimax.c
+++ b/libnm-glib/nm-device-wimax.c
@@ -189,7 +189,7 @@ nm_device_wimax_get_active_nsp (NMDeviceWimax *wimax)
  * Gets all the scanned NSPs of the #NMDeviceWimax.
  *
  * Returns: (element-type NMClient.WimaxNsp): a #GPtrArray containing
- *          all the scanned #NMWimaxNsp<!-- -->s.
+ *          all the scanned #NMWimaxNsps.
  * The returned array is owned by the client and should not be modified.
  **/
 const GPtrArray *
diff --git a/libnm-glib/nm-ip4-config.c b/libnm-glib/nm-ip4-config.c
index ab53e382f1..e657ed1f91 100644
--- a/libnm-glib/nm-ip4-config.c
+++ b/libnm-glib/nm-ip4-config.c
@@ -254,7 +254,7 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class)
 	/**
 	 * NMIP4Config:addresses:
 	 *
-	 * The #GPtrArray containing #NMSettingIP4Address<!-- -->es of the configuration.
+	 * The #GPtrArray containing #NMIP4Address<!-- -->es of the configuration.
 	 **/
 	g_object_class_install_property
 	    (object_class, PROP_ADDRESSES,
@@ -266,7 +266,7 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class)
 	/**
 	 * NMIP4Config:routes:
 	 *
-	 * The #GPtrArray containing #NMSettingIP4Route<!-- -->s of the configuration.
+	 * The #GPtrArray containing #NMSettingIP4Routes of the configuration.
 	 **/
 	g_object_class_install_property
 	    (object_class, PROP_ROUTES,
@@ -278,7 +278,7 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class)
 	/**
 	 * NMIP4Config:nameservers:
 	 *
-	 * The #GArray containing name servers (%guint32<!-- -->es) of the configuration.
+	 * The #GArray containing name servers (#guint32s) of the configuration.
 	 **/
 	g_object_class_install_property
 	    (object_class, PROP_NAMESERVERS,
@@ -319,7 +319,7 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class)
 	/**
 	 * NMIP4Config:wins-servers:
 	 *
-	 * The #GArray containing WINS servers (%guint32<!-- -->es) of the configuration.
+	 * The #GArray containing WINS servers (#guint32s) of the configuration.
 	 **/
 	g_object_class_install_property
 	    (object_class, PROP_WINS_SERVERS,
@@ -391,8 +391,9 @@ nm_ip4_config_get_addresses (NMIP4Config *config)
  *
  * Gets the domain name servers (DNS).
  *
- * Returns: (element-type guint32): the #GArray containing %guint32<!-- -->s. This is the internal copy used by the
- * configuration and must not be modified.
+ * Returns: (element-type guint32): the #GArray containing #guint32s.
+ * This is the internal copy used by the configuration and must not be
+ * modified.
  **/
 const GArray *
 nm_ip4_config_get_nameservers (NMIP4Config *config)
@@ -447,8 +448,9 @@ nm_ip4_config_get_searches (NMIP4Config *config)
  *
  * Gets the Windows Internet Name Service servers (WINS).
  *
- * Returns: (element-type guint32): the #GArray containing %guint32<!-- -->s.
- * This is the internal copy used by the configuration and must not be modified.
+ * Returns: (element-type guint32): the #GArray containing #guint32s.
+ * This is the internal copy used by the configuration and must not be
+ * modified.
  **/
 const GArray *
 nm_ip4_config_get_wins_servers (NMIP4Config *config)
@@ -466,7 +468,7 @@ nm_ip4_config_get_wins_servers (NMIP4Config *config)
  * Gets the routes.
  *
  * Returns: (element-type NetworkManager.IP4Route): the #GSList containing
- * #NMIP4Route<!-- -->s. This is the internal copy used by the configuration,
+ * #NMIP4Routes. This is the internal copy used by the configuration,
  * and must not be modified.
  **/
 const GSList *
diff --git a/libnm-glib/nm-ip6-config.c b/libnm-glib/nm-ip6-config.c
index 3d22c31d89..cd717c095c 100644
--- a/libnm-glib/nm-ip6-config.c
+++ b/libnm-glib/nm-ip6-config.c
@@ -259,7 +259,7 @@ nm_ip6_config_get_searches (NMIP6Config *config)
  * Gets the routes.
  *
  * Returns: (element-type NetworkManager.IP6Route): the #GSList containing
- * #NMIP6Route<!-- -->s. This is the internal copy used by the configuration,
+ * #NMIP6Routes. This is the internal copy used by the configuration,
  * and must not be modified.
  **/
 const GSList *
diff --git a/libnm-util/nm-utils.c b/libnm-util/nm-utils.c
index c0b18f63ad..05e68d856c 100644
--- a/libnm-util/nm-utils.c
+++ b/libnm-util/nm-utils.c
@@ -461,7 +461,7 @@ value_dup (gpointer key, gpointer val, gpointer user_data)
  * nm_utils_gvalue_hash_dup:
  * @hash: a #GHashTable mapping string:GValue
  *
- * Utility function to duplicate a hash table of GValues.
+ * Utility function to duplicate a hash table of #GValues.
  *
  * Returns: (transfer container) (element-type utf8 GObject.Value): a newly allocated duplicated #GHashTable, caller must free the
  * returned hash with g_hash_table_unref() or g_hash_table_destroy()
@@ -883,11 +883,11 @@ nm_utils_wpa_psk_valid (const char *psk)
 
 /**
  * nm_utils_ip4_addresses_from_gvalue:
- * @value: gvalue containing a GPtrArray of GArrays of guint32s
+ * @value: #GValue containing a #GPtrArray of #GArrays of #guint32s
  *
- * Utility function to convert a #GPtrArray of #GArrays of guint32s representing
+ * Utility function to convert a #GPtrArray of #GArrays of #guint32s representing
  * a list of NetworkManager IPv4 addresses (which is a tuple of address, gateway,
- * and prefix) into a GSList of #NMIP4Address objects.  The specific format of
+ * and prefix) into a #GSList of #NMIP4Address objects.  The specific format of
  * this serialization is not guaranteed to be stable and the #GArray may be
  * extended in the future.
  *
@@ -928,7 +928,7 @@ nm_utils_ip4_addresses_from_gvalue (const GValue *value)
  * g_value_unset().
  *
  * Utility function to convert a #GSList of #NMIP4Address objects into a
- * GPtrArray of GArrays of guint32s representing a list of NetworkManager IPv4
+ * #GPtrArray of #GArrays of #guint32s representing a list of NetworkManager IPv4
  * addresses (which is a tuple of address, gateway, and prefix).   The specific
  * format of this serialization is not guaranteed to be stable and may be
  * extended in the future.
@@ -965,11 +965,11 @@ nm_utils_ip4_addresses_to_gvalue (GSList *list, GValue *value)
 
 /**
  * nm_utils_ip4_routes_from_gvalue:
- * @value: gvalue containing a GPtrArray of GArrays of guint32s
+ * @value: #GValue containing a #GPtrArray of #GArrays of #guint32s
  *
- * Utility function to convert a GPtrArray of GArrays of guint32s representing
+ * Utility function to convert a #GPtrArray of #GArrays of #guint32s representing
  * a list of NetworkManager IPv4 routes (which is a tuple of route, next hop,
- * prefix, and metric) into a GSList of #NMIP4Route objects.  The specific
+ * prefix, and metric) into a #GSList of #NMIP4Route objects.  The specific
  * format of this serialization is not guaranteed to be stable and may be
  * extended in the future.
  *
@@ -1011,7 +1011,7 @@ nm_utils_ip4_routes_from_gvalue (const GValue *value)
  * g_value_unset().
  *
  * Utility function to convert a #GSList of #NMIP4Route objects into a
- * GPtrArray of GArrays of guint32s representing a list of NetworkManager IPv4
+ * #GPtrArray of #GArrays of #guint32s representing a list of NetworkManager IPv4
  * routes (which is a tuple of route, next hop, prefix, and metric).   The
  * specific format of this serialization is not guaranteed to be stable and may
  * be extended in the future.
@@ -1128,11 +1128,11 @@ nm_utils_ip4_get_default_prefix (guint32 ip)
 
 /**
  * nm_utils_ip6_addresses_from_gvalue:
- * @value: gvalue containing a GPtrArray of GValueArrays of (GArray of guchars) and guint32
+ * @value: gvalue containing a GPtrArray of GValueArrays of (GArray of guchars) and #guint32
  *
- * Utility function to convert a #GPtrArray of #GValueArrays of (#GArray of guchars) and guint32
+ * Utility function to convert a #GPtrArray of #GValueArrays of (#GArray of guchars) and #guint32
  * representing a list of NetworkManager IPv6 addresses (which is a tuple of address,
- * prefix, and gateway), into a GSList of #NMIP6Address objects.  The specific format of
+ * prefix, and gateway), into a #GSList of #NMIP6Address objects.  The specific format of
  * this serialization is not guaranteed to be stable and the #GValueArray may be
  * extended in the future.
  *
@@ -1213,7 +1213,7 @@ nm_utils_ip6_addresses_from_gvalue (const GValue *value)
  * g_value_unset().
  *
  * Utility function to convert a #GSList of #NMIP6Address objects into a
- * GPtrArray of GValueArrays representing a list of NetworkManager IPv6 addresses
+ * #GPtrArray of #GValueArrays representing a list of NetworkManager IPv6 addresses
  * (which is a tuple of address, prefix, and gateway). The specific format of
  * this serialization is not guaranteed to be stable and may be extended in the
  * future.
@@ -1264,13 +1264,13 @@ nm_utils_ip6_addresses_to_gvalue (GSList *list, GValue *value)
 
 /**
  * nm_utils_ip6_routes_from_gvalue:
- * @value: gvalue containing a GPtrArray of GValueArrays of (GArray or guchars), guint32,
- * (GArray of guchars), and guint32
+ * @value: #GValue containing a #GPtrArray of #GValueArrays of (#GArray of #guchars), #guint32,
+ * (#GArray of #guchars), and #guint32
  *
- * Utility function GPtrArray of GValueArrays of (GArray or guchars), guint32,
- * (GArray of guchars), and guint32 representing a list of NetworkManager IPv6
+ * Utility function #GPtrArray of #GValueArrays of (#GArray of #guchars), #guint32,
+ * (#GArray of #guchars), and #guint32 representing a list of NetworkManager IPv6
  * routes (which is a tuple of destination, prefix, next hop, and metric)
- * into a GSList of #NMIP6Route objects.  The specific format of this serialization
+ * into a #GSList of #NMIP6Route objects.  The specific format of this serialization
  * is not guaranteed to be stable and may be extended in the future.
  *
  * Returns: (transfer full) (element-type NetworkManager.IP6Route): a newly allocated #GSList of #NMIP6Route objects
@@ -1334,8 +1334,8 @@ nm_utils_ip6_routes_from_gvalue (const GValue *value)
  * which should be unset by the caller (when no longer needed) with
  * g_value_unset().
  *
- * Utility function to convert a #GSList of #NMIP6Route objects into a GPtrArray of
- * GValueArrays of (GArray or guchars), guint32, (GArray of guchars), and guint32
+ * Utility function to convert a #GSList of #NMIP6Route objects into a #GPtrArray of
+ * #GValueArrays of (#GArray of #guchars), #guint32, (#GArray of #guchars), and #guint32
  * representing a list of NetworkManager IPv6 routes (which is a tuple of destination,
  * prefix, next hop, and metric).  The specific format of this serialization is not 
  * guaranteed to be stable and may be extended in the future.
@@ -1396,7 +1396,7 @@ nm_utils_ip6_routes_to_gvalue (GSList *list, GValue *value)
  * @value: a #GValue
  *
  * Converts a #GValue containing a #GPtrArray of IP6 DNS, represented as
- * #GByteArray<!-- -->s into a #GSList of #in6_addr<!-- -->s.
+ * #GByteArrays into a #GSList of <literal><type>struct in6_addr</type></literal>s.
  *
  * Returns: (transfer full) (element-type Posix.in6_addr): a #GSList of IP6
  * addresses.
@@ -1434,10 +1434,11 @@ nm_utils_ip6_dns_from_gvalue (const GValue *value)
  * addresses, which should be unset by the caller (when no longer needed) with
  * g_value_unset().
  *
- * Utility function to convert a #GSList of 'struct in6_addr' structs into a
- * GPtrArray of GByteArrays representing each server's IPv6 addresses in
- * network byte order.  The specific format of this serialization is not
- * guaranteed to be stable and may be extended in the future.
+ * Utility function to convert a #GSList of <literal><type>struct
+ * in6_addr</type></literal> structs into a #GPtrArray of #GByteArrays
+ * representing each server's IPv6 addresses in network byte order.
+ * The specific format of this serialization is not guaranteed to be
+ * stable and may be extended in the future.
  */
 void
 nm_utils_ip6_dns_to_gvalue (GSList *list, GValue *value)