Complete Documentation for Status stuff.

4 files changed, 220 insertions, 65 deletions

diff --git a/docs/reference/telepathy-ytstenut-glib-docs.sgml b/docs/reference/telepathy-ytstenut-glib-docs.sgml
index 75d9934..6f15dfb 100644
--- a/docs/reference/telepathy-ytstenut-glib-docs.sgml
+++ b/docs/reference/telepathy-ytstenut-glib-docs.sgml
@@ -14,14 +14,16 @@
   </bookinfo>
 
   <chapter>
-    <title>Using Ytstenut Services</title>
+    <title>Using Ytstenut Objects</title>
     <xi:include href="xml/account-manager.xml"/>
+    <xi:include href="xml/status.xml"/>
   </chapter>
 
   <chapter>
-    <title>Implementing Ytstenut Services</title>
-    <xi:include href="xml/svc-account-manager.xml"/>
+    <title>Implementing Ytstenut Objects</title>
     <xi:include href="tp-svc.xml"/>
+    <xi:include href="xml/svc-account-manager.xml"/>
+    <xi:include href="xml/svc-status.xml"/>
   </chapter>
 
   <chapter>
@@ -37,7 +39,6 @@
     <xi:include href="xml/svc.xml"/>
     <xi:include href="xml/enums.xml"/>
     <xi:include href="xml/gtypes-body.xml"/>
-    <xi:include href="xml/cli-status.xml"/>
     <xi:include href="xml/interfaces-body.xml"/>
     <xi:include href="xml/gtypes.xml"/>
     <xi:include href="xml/cli-channel.xml"/>
diff --git a/docs/reference/telepathy-ytstenut-glib-sections.txt b/docs/reference/telepathy-ytstenut-glib-sections.txt
index fe219a6..1c1530b 100644
--- a/docs/reference/telepathy-ytstenut-glib-sections.txt
+++ b/docs/reference/telepathy-ytstenut-glib-sections.txt
@@ -24,7 +24,6 @@ tp_yts_account_manager_call_hold
 tp_yts_account_manager_callback_for_release
 tp_yts_account_manager_call_release
 tp_yts_iface_quark_account_manager
-
 </SECTION>
 
 <SECTION>
@@ -46,6 +45,63 @@ TP_YTS_SVC_ACCOUNT_MANAGER_GET_CLASS
 </SECTION>
 
 <SECTION>
+<FILE>status</FILE>
+TpYtsStatus
+TpYtsStatusClass
+tp_yts_status_ensure_for_connection_async
+tp_yts_status_ensure_for_connection_finish
+tp_yts_status_get_discovered_services
+tp_yts_status_get_discovered_statuses
+tp_yts_status_advertise_status_async
+tp_yts_status_advertise_status_finish
+TP_YTS_HASH_TYPE_CONTACT_CAPABILITY_MAP
+TP_YTS_HASH_TYPE_CAPABILITY_SERVICE_MAP
+TP_YTS_HASH_TYPE_SERVICE_STATUS_MAP
+TP_YTS_HASH_TYPE_LOCALIZED_NAME_MAP
+TP_YTS_HASH_TYPE_SERVICE_MAP
+TP_YTS_STRUCT_TYPE_SERVICE
+<SUBSECTION Standard>
+tp_yts_status_get_type
+TP_IS_YTS_STATUS
+TP_IS_YTS_STATUS_CLASS
+TP_TYPE_YTS_STATUS
+TP_YTS_STATUS
+TP_YTS_STATUS_CLASS
+TP_YTS_STATUS_GET_CLASS
+TpYtsStatusPrivate
+tp_yts_status_callback_for_advertise_status
+tp_yts_status_call_advertise_status
+EXTENSIONS_IFACE_CONNECTION_FUTURE
+EXTENSIONS_IFACE_QUARK_CONNECTION_FUTURE
+extensions_cli_connection_future_call_ensure_sidecar
+extensions_cli_connection_future_callback_for_ensure_sidecar
+extensions_iface_quark_connection_future
+extensions_tp_connection_future_ensure_sidecar_async
+extensions_tp_connection_future_ensure_sidecar_finish
+tp_yts_type_dbus_hash_ss
+tp_yts_type_dbus_hash_sa_7bsa_7bss_7d_7d
+tp_yts_type_dbus_hash_s_28sa_7bss_7das_29
+tp_yts_type_dbus_hash_sa_7bss_7d
+tp_yts_type_dbus_struct_sa_7bss_7das
+tp_yts_type_dbus_array_of_a_7bss_7d
+</SECTION>
+
+<SECTION>
+<FILE>svc-status</FILE>
+TpYtsSvcStatus
+TpYtsSvcStatusClass
+tp_yts_svc_status_advertise_status_impl
+tp_yts_svc_status_implement_advertise_status
+tp_yts_svc_status_return_from_advertise_status
+<SUBSECTION Standard>
+tp_yts_svc_status_get_type
+TP_TYPE_YTS_SVC_STATUS
+TP_YTS_SVC_STATUS
+TP_IS_YTS_SVC_STATUS
+TP_YTS_SVC_STATUS_GET_CLASS
+</SECTION>
+
+<SECTION>
 <FILE>svc</FILE>
 TpYtsSvcChannel
 TpYtsSvcChannelClass
@@ -65,17 +121,6 @@ tp_yts_svc_channel_implement_fail
 tp_yts_svc_channel_return_from_fail
 tp_yts_svc_channel_emit_replied
 tp_yts_svc_channel_emit_failed
-TpYtsSvcStatus
-TpYtsSvcStatusClass
-tp_yts_svc_status_get_type
-TP_TYPE_YTS_SVC_STATUS
-TP_YTS_SVC_STATUS
-TP_IS_YTS_SVC_STATUS
-TP_YTS_SVC_STATUS_GET_CLASS
-tp_yts_svc_status_advertise_status_impl
-tp_yts_svc_status_implement_advertise_status
-tp_yts_svc_status_return_from_advertise_status
-tp_yts_svc_status_emit_status_changed
 </SECTION>
 
 <SECTION>
@@ -102,10 +147,6 @@ tp_yts_channel_callback_for_reply
 tp_yts_channel_call_reply
 tp_yts_channel_callback_for_fail
 tp_yts_channel_call_fail
-tp_yts_status_signal_callback_status_changed
-tp_yts_status_connect_to_status_changed
-tp_yts_status_callback_for_advertise_status
-tp_yts_status_call_advertise_status
 </SECTION>
 
 <SECTION>
@@ -133,48 +174,6 @@ NUM_TP_YTS_ERROR_TYPES
 </SECTION>
 
 <SECTION>
-<FILE>gtypes-body</FILE>
-tp_yts_type_dbus_hash_ss
-tp_yts_type_dbus_hash_sa_7bsa_7bss_7d_7d
-tp_yts_type_dbus_hash_s_28sa_7bss_7das_29
-tp_yts_type_dbus_hash_sa_7bss_7d
-tp_yts_type_dbus_struct_sa_7bss_7das
-tp_yts_type_dbus_array_of_a_7bss_7d
-</SECTION>
-
-<SECTION>
-<FILE>cli-status</FILE>
-tp_yts_status_signal_callback_status_changed
-tp_yts_status_connect_to_status_changed
-tp_yts_status_callback_for_advertise_status
-tp_yts_status_call_advertise_status
-</SECTION>
-
-<SECTION>
-<FILE>interfaces-body</FILE>
-tp_yts_iface_quark_channel
-tp_yts_iface_quark_status
-</SECTION>
-
-<SECTION>
-<FILE>gtypes</FILE>
-TP_YTS_HASH_TYPE_MESSAGE_ATTRS
-TP_YTS_ARRAY_TYPE_MESSAGE_ATTRS_LIST
-TP_YTS_HASH_TYPE_CONTACT_CAPABILITY_MAP
-TP_YTS_HASH_TYPE_CAPABILITY_SERVICE_MAP
-TP_YTS_HASH_TYPE_SERVICE_STATUS_MAP
-TP_YTS_HASH_TYPE_LOCALIZED_NAME_MAP
-TP_YTS_HASH_TYPE_SERVICE_MAP
-tp_yts_type_dbus_hash_ss
-tp_yts_type_dbus_hash_sa_7bsa_7bss_7d_7d
-tp_yts_type_dbus_hash_s_28sa_7bss_7das_29
-tp_yts_type_dbus_hash_sa_7bss_7d
-TP_YTS_STRUCT_TYPE_SERVICE
-tp_yts_type_dbus_struct_sa_7bss_7das
-tp_yts_type_dbus_array_of_a_7bss_7d
-</SECTION>
-
-<SECTION>
 <FILE>cli-channel</FILE>
 tp_yts_channel_signal_callback_replied
 tp_yts_channel_connect_to_replied
@@ -186,4 +185,6 @@ tp_yts_channel_callback_for_reply
 tp_yts_channel_call_reply
 tp_yts_channel_callback_for_fail
 tp_yts_channel_call_fail
+TP_YTS_HASH_TYPE_MESSAGE_ATTRS
+TP_YTS_ARRAY_TYPE_MESSAGE_ATTRS_LIST
 </SECTION>
diff --git a/telepathy-ytstenut-glib/status.c b/telepathy-ytstenut-glib/status.c
index 394b91e..7bd7235 100644
--- a/telepathy-ytstenut-glib/status.c
+++ b/telepathy-ytstenut-glib/status.c
@@ -46,8 +46,22 @@
  * @title: TpYtsStatus
  * @short_description: proxy object for Ytstenut service status
  *
- * The #TpYtsStatus object is used to communicate with the Ytstenut
- * Status service.
+ * The #TpYtsStatus object is a proxy which is used to communicate with the
+ * Ytstenut Status service.
+ *
+ * Each Ytstenut Status object is associated with a relevant Ytstenut-enabled
+ * telepathy connection, represented by a #TpConnection object. To create a new
+ * TpYtsStatus object for a given connection use the
+ * use tp_yts_status_ensure_for_connection_async() function.
+ *
+ * This object automatically keeps track of all the discovered Ytstenut
+ * services and their statuses. Use tp_yts_status_get_discovered_statuses()
+ * and tp_yts_status_get_discovered_services() or the equivalent properties
+ * to access this information. To be notified when these discovered properties
+ * change, use the #GObject::notify signal.
+ *
+ * To advertise the status of your service via Ytstenut use the
+ * tp_yts_status_advertise_status_async() function.
  */
 
 /**
@@ -154,12 +168,52 @@ tp_yts_status_class_init (TpYtsStatusClass *klass)
 
   g_type_add_class_private (TP_TYPE_YTS_STATUS, sizeof (TpYtsStatus));
 
+  /**
+   * TpYtsStatus:discovered-services:
+   *
+   * Get the discovered Ytstenut services. The hash table is of
+   * #TP_YTS_HASH_TYPE_SERVICE_MAP type, and has the following contents:
+   *
+   * <code><literallayout>
+   *    GHashTable (
+   *        gchar *service_name,
+   *        GValueArray (
+   *            gchar *service_type,
+   *            GHashTable (
+   *                gchar *language,
+   *                gchar *localized_name
+   *            )
+   *            gchar **capabilities
+   *        )
+   *    )
+   * </literallayout></code>
+   */
   g_object_class_install_property (object_class, PROP_DISCOVERED_SERVICES,
       g_param_spec_boxed ("discovered-services", "Discovered Services",
           "Discovered Ytstenut Service Information",
           TP_YTS_HASH_TYPE_SERVICE_MAP,
           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
+  /**
+   * TpYtsStatus:discovered-statuses:
+   *
+   * Get the discovered Ytstenut statuses for services. The hash table is of
+   * #TP_YTS_HASH_TYPE_CONTACT_CAPABILITY_MAP type, and has the following
+   * contents:
+   *
+   * <code><literallayout>
+   *    GHashTable (
+   *        gchar *contact_id,
+   *        GHashTable (
+   *            gchar *capability,
+   *            GHashTable (
+   *                gchar *service_name,
+   *                gchar *status_xml
+   *            )
+   *        )
+   *    )
+   * </literallayout></code>
+   */
   g_object_class_install_property (object_class, PROP_DISCOVERED_STATUSES,
       g_param_spec_boxed ("discovered-statuses", "Discovered Statuses",
           "Discovered Ytstenut Status Information",
@@ -329,6 +383,15 @@ on_connection_future_ensure_sidecar_returned (GObject *source_object,
   g_free (object_path);
 }
 
+/**
+ * tp_yts_status_ensure_for_connection_async:
+ * @connection: The Ytstenut enabled connection
+ * @cancellable: Not used
+ * @callback: A callback which should be called when the result is ready
+ * @user_data: Data to pass to the callback
+ *
+ * Create a #TpYtsStatus object for a Ytstenut enabled connection.
+ */
 void
 tp_yts_status_ensure_for_connection_async (TpConnection *connection,
     GCancellable *cancellable,
@@ -347,6 +410,17 @@ tp_yts_status_ensure_for_connection_async (TpConnection *connection,
       on_connection_future_ensure_sidecar_returned, res);
 }
 
+/**
+ * tp_yts_status_ensure_for_connection_finish:
+ * @connection: The Ytstenut enabled connection
+ * @result: The result object passed to the callback
+ * @error: If an error occurred, this will be set
+ *
+ * Complete an asynchronous operation to create a #TpYtsStatus object.
+ *
+ * Returns: A new #TpYtsStatus proxy, which you can use to access
+ * the Ytstenut Status service. If the operation failed, %NULL will be returned.
+ */
 TpYtsStatus *
 tp_yts_status_ensure_for_connection_finish (TpConnection *connection,
     GAsyncResult *result,
@@ -384,7 +458,20 @@ on_status_advertise_status_returned (TpYtsStatus *self,
   g_simple_async_result_complete (res);
 }
 
-void tp_yts_status_advertise_status_async (TpYtsStatus *self,
+/**
+ * tp_yts_status_advertise_status_async:
+ * @self: The status proxy
+ * @capability: The Ytstenut string of the capability to advertise.
+ * @service_name: The Ytstenut service name for this service.
+ * @status_xml: The Ytstenut status as a UTF-8 encoded string.
+ * @cancellable: Not used
+ * @callback: A callback which should be called when the result is ready
+ * @user_data: Data to pass to the callback
+ *
+ * Advertise Ytstenut status for a service running on this device.
+ */
+void
+tp_yts_status_advertise_status_async (TpYtsStatus *self,
     const gchar *capability,
     const gchar *service_name,
     const gchar *status_xml,
@@ -404,6 +491,16 @@ void tp_yts_status_advertise_status_async (TpYtsStatus *self,
       res, g_object_unref, G_OBJECT (self));
 }
 
+/**
+ * tp_yts_status_advertise_status_finish:
+ * @self: The status proxy
+ * @result: The result object passed to the callback
+ * @error: If an error occurred, this will be set
+ *
+ * Complete an asynchronous operation advertise Ytstenut service status.
+ *
+ * Returns: %TRUE if the operation succeeded.
+ */
 gboolean
 tp_yts_status_advertise_status_finish (TpYtsStatus *self,
     GAsyncResult *result,
@@ -424,6 +521,30 @@ tp_yts_status_advertise_status_finish (TpYtsStatus *self,
   return TRUE;
 }
 
+/**
+ * tp_yts_status_get_discovered_statuses:
+ * @self: The status proxy
+ *
+ * Get the discovered Ytstenut statuses for services. The hash table is of
+ * #TP_YTS_HASH_TYPE_CONTACT_CAPABILITY_MAP type, and has the following
+ * contents:
+ *
+ * <code><literallayout>
+ *    GHashTable (
+ *        gchar *contact_id,
+ *        GHashTable (
+ *            gchar *capability,
+ *            GHashTable (
+ *                gchar *service_name,
+ *                gchar *status_xml
+ *            )
+ *        )
+ *    )
+ * </literallayout></code>
+ *
+ * Returns: The service statuses. This table is owned by the #TpYtsStatus
+ *      object and should not be freed or modified.
+ */
 GHashTable *
 tp_yts_status_get_discovered_statuses (TpYtsStatus *self)
 {
@@ -431,6 +552,30 @@ tp_yts_status_get_discovered_statuses (TpYtsStatus *self)
   return self->priv->discovered_statuses;
 }
 
+/**
+ * tp_yts_status_get_discovered_services:
+ * @self: The status proxy
+ *
+ * Get the discovered Ytstenut services. The hash table is of
+ * #TP_YTS_HASH_TYPE_SERVICE_MAP type, and has the following contents:
+ *
+ * <code><literallayout>
+ *    GHashTable (
+ *        gchar *service_name,
+ *        GValueArray (
+ *            gchar *service_type,
+ *            GHashTable (
+ *                gchar *language,
+ *                gchar *localized_name
+ *            )
+ *            gchar **capabilities
+ *        )
+ *    )
+ * </literallayout></code>
+ *
+ * Returns: The services. This table is owned by the #TpYtsStatus
+ *      object and should not be freed or modified.
+ */
 GHashTable *
 tp_yts_status_get_discovered_services (TpYtsStatus *self)
 {
diff --git a/telepathy-ytstenut-glib/telepathy-ytstenut-glib.c b/telepathy-ytstenut-glib/telepathy-ytstenut-glib.c
index bd33afe..5507332 100644
--- a/telepathy-ytstenut-glib/telepathy-ytstenut-glib.c
+++ b/telepathy-ytstenut-glib/telepathy-ytstenut-glib.c
@@ -18,6 +18,14 @@
  */
 
 /**
+ * SECTION:svc-status
+ * @title: Implementing Status
+ * @short_description: helper for implementing Status
+ *
+ * A telepathy-glib helper for implementing the Status DBus interface.
+ */
+
+/**
  * SECTION:interfaces
  * @title: Ytstenut Interface Constants
  * @short_description: The various DBus interfaces involved in Ytstenut