[next] telepathy-glib: account-manager: document what signal is used for new accounts

[Simon McVittie]

Module: telepathy-glib
Branch: next
Commit: d4cbc804089b0888126f94f37afb3a2de3be3a74
URL:    http://cgit.freedesktop.org/telepathy/telepathy-glib/commit/?id=d4cbc804089b0888126f94f37afb3a2de3be3a74

Author: Jonny Lamb <jonny.lamb at collabora.co.uk>
Date:   Wed Apr 25 16:00:17 2012 +0100

account-manager: document what signal is used for new accounts

Signed-off-by: Jonny Lamb <jonny.lamb at collabora.co.uk>

---

 telepathy-glib/account-manager.c |   23 +++++++++++++++++++++++
 1 files changed, 23 insertions(+), 0 deletions(-)

diff --git a/telepathy-glib/account-manager.c b/telepathy-glib/account-manager.c
index 576ea73..1779197 100644
--- a/telepathy-glib/account-manager.c
+++ b/telepathy-glib/account-manager.c
@@ -50,6 +50,26 @@
  * The #TpAccountManager object is used to communicate with the Telepathy
  * AccountManager service.
  *
+ * A new #TpAccountManager object can be created with
+ * tp_account_manager_dup().
+ *
+ * To list the existing valid accounts, the client should first
+ * prepare the %TP_ACCOUNT_MANAGER_FEATURE_CORE feature using
+ * tp_proxy_prepare_async(), then call
+ * tp_account_manager_get_valid_accounts().
+ *
+ * The #TpAccountManager::account-validity-changed signal is emitted
+ * to notify of the validity of an account changing. New accounts are
+ * also indicated by the emission of this signal on an account that
+ * did not previously exist. (The rationale behind indicating new
+ * accounts by an account validity change signal is that clients
+ * interested in this kind of thing should be connected to this signal
+ * anyway: an account having just become valid is effectively a new
+ * account to a client.)
+ *
+ * The #TpAccountManager::account-removed signal is emitted when
+ * existing accounts.
+ *
  * Since: 0.7.32
  */
 
@@ -589,6 +609,9 @@ tp_account_manager_class_init (TpAccountManagerClass *klass)
    *
    * Emitted when the validity on @account changes.
    *
+   * This signal is also used to indicate a new account that did not
+   * previously exist has been added (with @valid to %TRUE).
+   *
    * @account is guaranteed to have %TP_ACCOUNT_FEATURE_CORE prepared, along
    * with all features previously passed to
    * tp_simple_client_factory_add_account_features().