diff --git a/introspection/nm-access-point.xml b/introspection/nm-access-point.xml
index 2acd0e39af..10d8c0c391 100644
--- a/introspection/nm-access-point.xml
+++ b/introspection/nm-access-point.xml
@@ -7,7 +7,7 @@
 
         Flags describing the capabilities of the access point.
 
-        Returns: #NM80211ApFlags
+        Returns: <link linkend="NM80211ApFlags">NM80211ApFlags</link>
     -->
     <property name="Flags" type="u" access="read"/>
 
@@ -17,7 +17,7 @@
         Flags describing the access point's capabilities according to WPA (Wifi
         Protected Access).
 
-        Returns: #NM80211ApSecurityFlags
+        Returns: <link linkend="NM80211ApSecurityFlags">NM80211ApSecurityFlags</link>
     -->
     <property name="WpaFlags" type="u" access="read"/>
 
@@ -27,7 +27,7 @@
         Flags describing the access point's capabilities according to the RSN
         (Robust Secure Network) protocol.
 
-        Returns: #NM80211ApSecurityFlags
+        Returns: <link linkend="NM80211ApSecurityFlags">NM80211ApSecurityFlags</link>
     -->
     <property name="RsnFlags" type="u" access="read"/>
 
@@ -62,7 +62,7 @@
 
         Describes the operating mode of the access point.
 
-        Returns: #NM80211Mode
+        Returns: <link linkend="NM80211Mode">NM80211Mode</link>
     -->
     <property name="Mode" type="u" access="read"/>
 
diff --git a/introspection/nm-active-connection.xml b/introspection/nm-active-connection.xml
index 343e6afed8..950dadf77d 100644
--- a/introspection/nm-active-connection.xml
+++ b/introspection/nm-active-connection.xml
@@ -75,7 +75,7 @@
 
         The state of this active connection.
 
-        Returns: #NMActiveConnectionState
+        Returns: <link linkend="NMActiveConnectionState">NMActiveConnectionState</link>
     -->
     <property name="State" type="u" access="read"/>
 
diff --git a/introspection/nm-agent-manager.xml b/introspection/nm-agent-manager.xml
index 183fb3b83b..4f1bbbf5a0 100644
--- a/introspection/nm-agent-manager.xml
+++ b/introspection/nm-agent-manager.xml
@@ -16,7 +16,7 @@
     <!--
         RegisterWithCapabilities:
         @identifier: See the Register() method's identifier argument.
-        @capabilities: (#NMSecretAgentCapabilities) Indicates various agent capabilities to NetworkManager.
+        @capabilities: (<link linkend="NMSecretAgentCapabilities">NMSecretAgentCapabilities</link>) Indicates various agent capabilities to NetworkManager.
 
         Like Register() but indicates agent capabilities to NetworkManager.
     -->
diff --git a/introspection/nm-device-bt.xml b/introspection/nm-device-bt.xml
index 80b9020f4f..e4129fc670 100644
--- a/introspection/nm-device-bt.xml
+++ b/introspection/nm-device-bt.xml
@@ -21,7 +21,7 @@
 
         Bluetooth capabilities of the device (either DUN or NAP).
 
-        Returns: #NMBluetoothCapabilities
+        Returns: <link linkend="NMBluetoothCapabilities">NMBluetoothCapabilities</link>
     -->
     <property name="BtCapabilities" type="u" access="read"/>
 
diff --git a/introspection/nm-device-modem.xml b/introspection/nm-device-modem.xml
index 3478bb3c7c..eeb6a4afd2 100644
--- a/introspection/nm-device-modem.xml
+++ b/introspection/nm-device-modem.xml
@@ -18,7 +18,7 @@
         firmware reload or other reinitialization to switch between eg CDMA/EVDO
         and GSM/UMTS.
 
-        Returns: #NMDeviceModemCapabilities
+        Returns: <link linkend="NMDeviceModemCapabilities">NMDeviceModemCapabilities</link>
     -->
     <property name="ModemCapabilities" type="u" access="read"/>
 
@@ -28,7 +28,7 @@
         The generic family of access technologies the modem currently supports
         without a firmware reload or reinitialization.
 
-        Returns: #NMDeviceModemCapabilities
+        Returns: <link linkend="NMDeviceModemCapabilities">NMDeviceModemCapabilities</link>
     -->
     <property name="CurrentCapabilities" type="u" access="read"/>
 
diff --git a/introspection/nm-device-wifi.xml b/introspection/nm-device-wifi.xml
index d72e376a22..33c87f5638 100644
--- a/introspection/nm-device-wifi.xml
+++ b/introspection/nm-device-wifi.xml
@@ -56,7 +56,7 @@
 
         The operating mode of the wireless device.
 
-        Returns: #NM80211Mode
+        Returns: <link linkend="NM80211Mode">NM80211Mode</link>
     -->
     <property name="Mode" type="u" access="read"/>
 
@@ -87,7 +87,7 @@
 
         The capabilities of the wireless device.
 
-        Returns: #NMDeviceWifiCapabilities
+        Returns: <link linkend="NMDeviceWifiCapabilities">NMDeviceWifiCapabilities</link>
     -->
     <property name="WirelessCapabilities" type="u" access="read"/>
 
diff --git a/introspection/nm-device.xml b/introspection/nm-device.xml
index 08bec827fe..e185e4eb63 100644
--- a/introspection/nm-device.xml
+++ b/introspection/nm-device.xml
@@ -62,7 +62,7 @@
 
         Flags describing the capabilities of the device.
 
-        Returns: #NMDeviceCapabilities
+        Returns: <link linkend="NMDeviceCapabilities">NMDeviceCapabilities</link>
     -->
     <property name="Capabilities" type="u" access="read"/>
 
@@ -79,7 +79,7 @@
 
         The current state of the device.
 
-        Returns: #NMDeviceState
+        Returns: <link linkend="NMDeviceState">NMDeviceState</link>
     -->
     <property name="State" type="u" access="read"/>
 
@@ -88,7 +88,7 @@
 
         The current state and reason for changing to that state.
 
-        Returns: #NMDeviceStateReasonStruct
+        Returns: <link linkend="NMDeviceStateReasonStruct">NMDeviceStateReasonStruct</link>
     -->
     <property name="StateReason" type="(uu)" access="read"/>
 
@@ -180,7 +180,7 @@
 
         The general type of the network device; ie Ethernet, WiFi, etc.
 
-        Returns: #NMDeviceType
+        Returns: <link linkend="NMDeviceType">NMDeviceType</link>
     -->
     <property name="DeviceType" type="u" access="read"/>
 
@@ -215,7 +215,7 @@
         Whether the amount of traffic flowing through the device is subject to
         limitations, for example set by service providers.
 
-        Returns: #NMMetered
+        Returns: <link linkend="NMMetered">NMMetered</link>
     -->
     <property name="Metered" type="u" access="read"/>
 
@@ -308,9 +308,9 @@
 
     <!--
         StateChanged:
-        @new_state: (#NMDeviceState) The new state of the device.
-        @old_state: (#NMDeviceState) The previous state of the device.
-        @reason: (#NMDeviceStateReason) A reason for the state transition.
+        @new_state: (<link linkend="NMDeviceState">NMDeviceState</link>) The new state of the device.
+        @old_state: (<link linkend="NMDeviceState">NMDeviceState</link>) The previous state of the device.
+        @reason: (<link linkend="NMDeviceStateReason">NMDeviceStateReason</link>) A reason for the state transition.
     -->
     <signal name="StateChanged">
       <arg name="new_state" type="u"/>
diff --git a/introspection/nm-manager.xml b/introspection/nm-manager.xml
index a0b22efc18..9990f4e3ed 100644
--- a/introspection/nm-manager.xml
+++ b/introspection/nm-manager.xml
@@ -158,7 +158,7 @@
 
     <!--
         CheckConnectivity:
-        @connectivity: (#NMConnectivityState) The current connectivity state.
+        @connectivity: (<link linkend="NMConnectivityState">NMConnectivityState</link>) The current connectivity state.
 
         Re-check the network connectivity state.
     -->
@@ -168,7 +168,7 @@
 
     <!--
         state:
-        @state: #NMState
+        @state: <link linkend="NMState">NMState</link>
 
         The overall networking state as determined by the NetworkManager daemon,
         based on the state of network devices under it's management.
@@ -281,7 +281,7 @@
         Indicates whether the connectivity is metered. This is equivalent to the
         metered property of the device associated with the primary connection.
 
-        Returns: #NMMetered
+        Returns: <link linkend="NMMetered">NMMetered</link>
     -->
     <property name="Metered" type="u" access="read"/>
 
@@ -315,13 +315,13 @@
 
         The overall state of the NetworkManager daemon.
 
-        Returns: #NMState
+        Returns: <link linkend="NMState">NMState</link>
     -->
     <property name="State" type="u" access="read"/>
 
     <!--
         StateChanged:
-        @state: (#NMState) The new state of NetworkManager.
+        @state: (<link linkend="NMState">NMState</link>) The new state of NetworkManager.
 
         NetworkManager's state changed.
     -->
@@ -334,7 +334,7 @@
 
         The network connectivity state.
 
-        Returns: #NMConnectivityState
+        Returns: <link linkend="NMConnectivityState">NMConnectivityState</link>
     -->
     <property name="Connectivity" type="u" access="read"/>
 
diff --git a/introspection/nm-secret-agent.xml b/introspection/nm-secret-agent.xml
index 8fe13183f6..7a551b9419 100644
--- a/introspection/nm-secret-agent.xml
+++ b/introspection/nm-secret-agent.xml
@@ -22,7 +22,7 @@
         @connection_path: Object path of the connection for which secrets are being requested.
         @setting_name: Setting name for which secrets are being requested.
         @hints: Array of strings of key names in the requested setting for which NetworkManager thinks a secrets may be required, and/or well-known identifiers and data that may be useful to the client in processing the secrets request. Note that it's not always possible to determine which secret is required, so in some cases no hints may be given. The Agent should return any secrets it has, or that it thinks are required, regardless of what hints NetworkManager sends in this request. Some hints have special prefixes that provide information to the agent; for example, VPN requests may send server-specific messages prefixed with "x-vpn-message:".
-        @flags: (#NMSecretAgentGetSecretsFlags) Flags which modify the behavior of the secrets request. If true, new secrets are assumed to be invalid or incorrect, and the agent should ask the user for new secrets. If false, existing secrets should be retrieved from storage and returned without interrupting the user.
+        @flags: (<link linkend="NMSecretAgentGetSecretsFlags">NMSecretAgentGetSecretsFlags</link>) Flags which modify the behavior of the secrets request. If true, new secrets are assumed to be invalid or incorrect, and the agent should ask the user for new secrets. If false, existing secrets should be retrieved from storage and returned without interrupting the user.
         @secrets: Nested settings maps containing secrets. Each setting MUST contain at least the 'name' field, containing the name of the setting, and one or more secrets.
 
         Retrieve and return stored secrets, if any, or request new secrets from
diff --git a/introspection/nm-vpn-connection.xml b/introspection/nm-vpn-connection.xml
index bdad5ccf52..41734b8e30 100644
--- a/introspection/nm-vpn-connection.xml
+++ b/introspection/nm-vpn-connection.xml
@@ -22,7 +22,7 @@
 
         The VPN-specific state of the connection.
 
-        Returns: #NMVpnConnectionState
+        Returns: <link linkend="NMVpnConnectionState">NMVpnConnectionState</link>
     -->
     <property name="VpnState" type="u" access="read"/>
 
@@ -35,8 +35,8 @@
 
     <!--
         VpnStateChanged:
-        @state: (#NMVpnConnectionState) The new state of the VPN connection.
-        @reason: (#NMVpnConnectionStateReason) Reason code describing the change to the new state.
+        @state: (<link linkend="NMVpnConnectionState">NMVpnConnectionState</link>) The new state of the VPN connection.
+        @reason: (<link linkend="NMVpnConnectionStateReason">NMVpnConnectionStateReason</link>) Reason code describing the change to the new state.
 
         Emitted when the state of the VPN connection has changed.
     -->
diff --git a/introspection/nm-vpn-plugin.xml b/introspection/nm-vpn-plugin.xml
index 063b842c7c..d071d0eac0 100644
--- a/introspection/nm-vpn-plugin.xml
+++ b/introspection/nm-vpn-plugin.xml
@@ -109,13 +109,13 @@
 
         The state of the plugin.
 
-        Returns: #NMVpnServiceState
+        Returns: <link linkend="NMVpnServiceState">NMVpnServiceState</link>
     -->
     <property name="State" type="u" access="read"/>
 
     <!--
         StateChanged:
-        @state: (#NMVpnServiceState) The new state of the plugin.
+        @state: (<link linkend="NMVpnServiceState">NMVpnServiceState</link>) The new state of the plugin.
 
         Emitted when the plugin state changes.
     -->
@@ -191,7 +191,7 @@
 
     <!--
         Failure:
-        @reason: (#NMVpnPluginFailure) Reason code for the failure.
+        @reason: (<link linkend="NMVpnPluginFailure">NMVpnPluginFailure</link>) Reason code for the failure.
 
         Emitted when a failure in the VPN plugin occurs.
     -->
diff --git a/introspection/nm-wimax-nsp.xml b/introspection/nm-wimax-nsp.xml
index b655e02f77..0f2ceccc3b 100644
--- a/introspection/nm-wimax-nsp.xml
+++ b/introspection/nm-wimax-nsp.xml
@@ -21,7 +21,7 @@
 
         The network type of the NSP.
 
-        Returns: #NMWimaxNspNetworkType
+        Returns: <link linkend="NMWimaxNspNetworkType">NMWimaxNspNetworkType</link>
     -->
     <property name="NetworkType" type="u" access="read"/>