[telepathy-glib/master] account{, -manager}: add notes about guarantees for properties/getters if the features is not ready yet

[Jonny Lamb]

Signed-off-by: Jonny Lamb <jonny.lamb at collabora.co.uk>
---
 telepathy-glib/account-manager.c |   11 ++++++++
 telepathy-glib/account.c         |   51 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+), 0 deletions(-)

diff --git a/telepathy-glib/account-manager.c b/telepathy-glib/account-manager.c
index 5f5c726..8e5da0b 100644
--- a/telepathy-glib/account-manager.c
+++ b/telepathy-glib/account-manager.c
@@ -1093,6 +1093,10 @@ tp_account_manager_ensure_account (TpAccountManager *manager,
  * g_list_foreach (accounts, (GFunc) g_object_ref, NULL);
  * ]|
  *
+ * The return value of this function is not guaranteed to have been retrieved
+ * until tp_account_manager_prepare_async() has finished; until then, the
+ * value is %NULL.
+ *
  * Returns: a newly allocated #GList of accounts in @manager
  *
  * Since: 0.7.UNRELEASED
@@ -1126,6 +1130,9 @@ tp_account_manager_get_accounts (TpAccountManager *manager)
  * You can find the most available presence across all accounts by calling
  * tp_account_manager_get_most_available_presence().
  *
+ * Setting a requested presence on all accounts will have no effect
+ * until tp_account_manager_prepare_async() has finished.
+ *
  * Since: 0.7.UNRELEASED
  */
 void
@@ -1183,6 +1190,10 @@ tp_account_manager_set_all_requested_presences (TpAccountManager *manager,
  * If no accounts are enabled or valid the output will be
  * (%TP_CONNECTION_PRESENCE_TYPE_OFFLINE, "offline", "").
  *
+ * The return value of this function is not guaranteed to have been retrieved
+ * until tp_account_manager_prepare_async() has finished; until then, the
+ * value will be the same as if no accounts are enabled or valid.
+ *
  * Returns: the most available presence across all accounts
  *
  * Since: 0.7.UNRELEASED
diff --git a/telepathy-glib/account.c b/telepathy-glib/account.c
index cc1beb5..7e1247c 100644
--- a/telepathy-glib/account.c
+++ b/telepathy-glib/account.c
@@ -972,6 +972,9 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is FALSE.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_ENABLED,
@@ -990,6 +993,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %TP_CONNECTION_PRESENCE_TYPE_UNSET.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_CURRENT_PRESENCE_TYPE,
@@ -1010,6 +1017,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %NULL.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_CURRENT_STATUS,
@@ -1028,6 +1039,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %NULL.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_CURRENT_STATUS_MESSAGE,
@@ -1046,6 +1061,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %TP_CONNECTION_STATUS_DISCONNECTED.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_CONNECTION_STATUS,
@@ -1066,6 +1085,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %TP_CONNECTION_STATUS_REASON_NONE_SPECIFIED.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_CONNECTION_STATUS_REASON,
@@ -1087,6 +1110,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %NULL.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_CONNECTION,
@@ -1105,6 +1132,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %NULL.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_DISPLAY_NAME,
@@ -1152,6 +1183,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %NULL.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_ICON_NAME,
@@ -1171,6 +1206,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %FALSE.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_CONNECT_AUTOMATICALLY,
@@ -1189,6 +1228,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %FALSE.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_HAS_BEEN_ONLINE,
@@ -1207,6 +1250,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %FALSE.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_VALID,
@@ -1281,6 +1328,10 @@ tp_account_class_init (TpAccountClass *klass)
    * to the #GObject::notify signal and using this property as the signal
    * detail.
    *
+   * This is not guaranteed to have been retrieved until
+   * tp_account_prepare_async() has finished; until then, the value is
+   * %NULL.
+   *
    * Since: 0.7.UNRELEASED
    */
   g_object_class_install_property (object_class, PROP_NICKNAME,
-- 
1.5.6.5