introspection: document the meaning of active connections

diff --git a/introspection/nm-active-connection.xml b/introspection/nm-active-connection.xml
index 4d5d15a..203437b 100644 (file)
--- a/introspection/nm-active-connection.xml
+++ b/introspection/nm-active-connection.xml
@@ -9,6 +9,15 @@
       The Connection.Active object tracks the life-cycle of the connection
       attempt and if successful indicates whether the connected network is the
       "default" or preferred network for access.
+      NetworkManager has the concept of connections, which can be thought of as
+      settings, a profile or a configuration that can be applied on a networking
+      device.
+      Such settings-connections are exposed as D-Bus object and the active-connection
+      expresses this relationship between device and settings-connection.
+      At any time a settings-connection can only be activated on one device and vice
+      versa. However, during activation and deactivation multiple active-connections
+      can reference the same device or settings-connection as they are waiting to
+      be activated or to be deactivated.
     </tp:docstring>
 
     <property name="Connection" type="o" access="read">