[next] telepathy-glib: TpSimpleClientFactory: suggest getting objects from "larger" objects

[Simon McVittie]

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

Author: Simon McVittie <simon.mcvittie at collabora.co.uk>
Date:   Fri Sep  6 12:00:12 2013 +0100

TpSimpleClientFactory: suggest getting objects from "larger" objects

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=54061
Reviewed-by: Guillaume Desmottes <guillaume.desmottes at collabora.co.uk>

---

 telepathy-glib/simple-client-factory.c |   14 +++++++++++++-
 1 files changed, 13 insertions(+), 1 deletions(-)

diff --git a/telepathy-glib/simple-client-factory.c b/telepathy-glib/simple-client-factory.c
index 34ad54c..71b8e6b 100644
--- a/telepathy-glib/simple-client-factory.c
+++ b/telepathy-glib/simple-client-factory.c
@@ -36,7 +36,8 @@
  *
  * Currently supported classes are #TpAccount, #TpConnection,
  * #TpChannel and #TpContact. Those objects should always be acquired through a
- * factory, rather than being constructed directly.
+ * factory or a "larger" object (e.g. getting the #TpConnection from
+ * a #TpAccount), rather than being constructed directly.
  *
  * One can subclass #TpSimpleClientFactory and override some of its virtual
  * methods to construct more specialized objects. See #TpAutomaticClientFactory
@@ -451,6 +452,10 @@ tp_simple_client_factory_get_dbus_daemon (TpSimpleClientFactory *self)
  * is responsible for calling tp_proxy_prepare_async() with the desired
  * features (as given by tp_simple_client_factory_dup_account_features()).
  *
+ * This function is rather low-level. tp_account_manager_dup_valid_accounts()
+ * and #TpAccountManager::validity-changed are more appropriate for most
+ * applications.
+ *
  * Returns: (transfer full): a reference to a #TpAccount;
  *  see tp_account_new().
  *
@@ -576,6 +581,9 @@ tp_simple_client_factory_add_account_features_varargs (
  * caller is responsible for calling tp_proxy_prepare_async() with the desired
  * features (as given by tp_simple_client_factory_dup_connection_features()).
  *
+ * This function is rather low-level. #TpAccount:connection is more
+ * appropriate for most applications.
+ *
  * Returns: (transfer full): a reference to a #TpConnection;
  *  see tp_connection_new().
  *
@@ -702,6 +710,10 @@ tp_simple_client_factory_add_connection_features_varargs (
  * caller is responsible for calling tp_proxy_prepare_async() with the desired
  * features (as given by tp_simple_client_factory_dup_channel_features()).
  *
+ * This function is rather low-level.
+ * #TpAccountChannelRequest and #TpBaseClient are more appropriate ways
+ * to obtain channels for most applications.
+ *
  * Returns: (transfer full): a reference to a #TpChannel;
  *  see tp_channel_new_from_properties().
  *