diff --git a/introspection/nm-device.xml b/introspection/nm-device.xml
index 040f9c55f5..13c542a6d0 100644
--- a/introspection/nm-device.xml
+++ b/introspection/nm-device.xml
@@ -4,7 +4,18 @@
   <interface name="org.freedesktop.NetworkManager.Device">
     <property name="Udi" type="s" access="read">
       <tp:docstring>
-        Unique Device Identifier.
+        Operating-system specific transient device hardware identifier.  This
+        is an opaque string representing the underlying hardware for the device,
+        and shouldn't be used to keep track of individual devices.  For some
+        device types (Bluetooth, Modems) it is an identifier used by the
+        hardware service (ie bluez or ModemManager) to refer to that device,
+        and client programs use it get additional information from those
+        services which NM does not provide.  The Udi is not guaranteed to be
+        consistent across reboots or hotplugs of the hardware. If you're looking
+        for a way to uniquely track each device in your application, use the
+        object path.  If you're looking for a way to track a specific piece of
+        hardware across reboot or hotplug, use a MAC address or USB serial
+        number.
       </tp:docstring>
     </property>
     <property name="Interface" type="s" access="read">
diff --git a/libnm-glib/nm-device.c b/libnm-glib/nm-device.c
index 3d640cee34..b198f526cb 100644
--- a/libnm-glib/nm-device.c
+++ b/libnm-glib/nm-device.c
@@ -522,7 +522,12 @@ nm_device_class_init (NMDeviceClass *device_class)
 	/**
 	 * NMDevice:udi:
 	 *
-	 * The Unique Device Identifier of the device.
+	 * An operating-system specific device hardware identifier; this is not
+	 * unique to a specific hardware device across reboots or hotplugs.  It
+	 * is an opaque string which for some device types (Bluetooth, Modem)
+	 * contains an identifier provided by the underlying hardware service daemon
+	 * such as Bluez or ModemManager, and clients can use this property to
+	 * request more information about the device from those services.
 	 **/
 	g_object_class_install_property
 		(object_class, PROP_UDI,