From c9e0e66a80429cc6564e47425c86856136d4a329 Mon Sep 17 00:00:00 2001
From: Dan Winship <danw@gnome.org>
Date: Sun, 5 Oct 2014 11:11:26 -0400
Subject: [PATCH] libnm, libnm-glib: clarify nm_client_activate_connection()
 semantics

nm_client_activate_connection() and
nm_client_add_and_activate_connection() return when the activation has
*started*, not when it *finishes*. Clarify this a bit more in the
libnm docs, and copy that clarification to libnm-glib as well.

https://bugzilla.gnome.org/show_bug.cgi?id=736233
---
 libnm-glib/nm-client.c | 10 ++++++++++
 libnm/nm-client.c      |  6 ++++--
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/libnm-glib/nm-client.c b/libnm-glib/nm-client.c
index 329f1e1ad1..f4efc607e5 100644
--- a/libnm-glib/nm-client.c
+++ b/libnm-glib/nm-client.c
@@ -605,6 +605,11 @@ activate_nm_not_running (gpointer user_data)
  *
  * If @connection is not given for a device-based activation, NetworkManager
  * picks the best available connection for the device and activates it.
+ *
+ * Note that the callback is invoked when NetworkManager has started activating
+ * the new connection, not when it finishes. You can used the returned
+ * #NMActiveConnection object (in particular, #NMActiveConnection:state) to
+ * track the activation to its completion.
  **/
 void
 nm_client_activate_connection (NMClient *client,
@@ -689,6 +694,11 @@ add_activate_cb (DBusGProxy *proxy,
  * automatically filling in missing settings with the capabilities of the
  * given device and specific object.  The new connection is then activated.
  * Cannot be used for VPN connections at this time.
+ *
+ * Note that the callback is invoked when NetworkManager has started activating
+ * the new connection, not when it finishes. You can used the returned
+ * #NMActiveConnection object (in particular, #NMActiveConnection:state) to
+ * track the activation to its completion.
  **/
 void
 nm_client_add_and_activate_connection (NMClient *client,
diff --git a/libnm/nm-client.c b/libnm/nm-client.c
index 0f64786b9d..053f75ceae 100644
--- a/libnm/nm-client.c
+++ b/libnm/nm-client.c
@@ -626,7 +626,8 @@ activate_cb (GObject *object,
  *
  * Note that the callback is invoked when NetworkManager has started activating
  * the new connection, not when it finishes. You can used the returned
- * #NMActiveConnection object to track the activation to its completion.
+ * #NMActiveConnection object (in particular, #NMActiveConnection:state) to
+ * track the activation to its completion.
  **/
 void
 nm_client_activate_connection_async (NMClient *client,
@@ -748,7 +749,8 @@ add_activate_cb (GObject *object,
  *
  * Note that the callback is invoked when NetworkManager has started activating
  * the new connection, not when it finishes. You can used the returned
- * #NMActiveConnection object to track the activation to its completion.
+ * #NMActiveConnection object (in particular, #NMActiveConnection:state) to
+ * track the activation to its completion.
  **/
 void
 nm_client_add_and_activate_connection_async (NMClient *client,