Sight doc cleanup

Signed-off-by: David Zeuthen <davidz@redhat.com>

3 files changed, 41 insertions, 9 deletions

diff --git a/src/gdbusobjectproxy.c b/src/gdbusobjectproxy.c
index 16d2a36..ad9271c 100644
--- a/src/gdbusobjectproxy.c
+++ b/src/gdbusobjectproxy.c
@@ -153,6 +153,10 @@ g_dbus_object_proxy_class_init (GDBusObjectProxyClass *klass)
    * @interface_proxy: The #GDBusProxy that was added.
    *
    * Emitted when @interface_proxy is added to @proxy.
+   *
+   * This signal is emitted in the
+   * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+   * that the #GDBusProxyManager owning @proxy was constructed in.
    */
   signals[INTERFACE_PROXY_ADDED_SIGNAL] =
     g_signal_new ("interface-proxy-added",
@@ -172,6 +176,10 @@ g_dbus_object_proxy_class_init (GDBusObjectProxyClass *klass)
    * @interface_proxy: The #GDBusProxy that was removed.
    *
    * Emitted when @interface_proxy is removed from @proxy.
+   *
+   * This signal is emitted in the
+   * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+   * that the #GDBusProxyManager owning @proxy was constructed in.
    */
   signals[INTERFACE_PROXY_REMOVED_SIGNAL] =
     g_signal_new ("interface-proxy-removed",
diff --git a/src/gdbusproxymanager.c b/src/gdbusproxymanager.c
index 5f98ab9..f59bdae 100644
--- a/src/gdbusproxymanager.c
+++ b/src/gdbusproxymanager.c
@@ -89,6 +89,14 @@
  * including the <emphasis><quote>half the proxy is from the old owner
  * and the other half is from the new owner</quote></emphasis> problem
  * cannot happen.
+ *
+ * Note that all callbacks and signals are emitted in the
+ * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * that the #GDBusProxyManager object was constructed
+ * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
+ * originating from the #GDBusProxyManager object will be created in
+ * the same context and, consequently, will deliver signals in the
+ * same main loop.
  */
 
 struct _GDBusProxyManagerPrivate
@@ -333,7 +341,7 @@ g_dbus_proxy_manager_class_init (GDBusProxyManagerClass *klass)
   /**
    * GDBusProxyManager:object-path:
    *
-   * The object path of the control object.
+   * The object path the manager is for.
    */
   g_object_class_install_property (gobject_class,
                                    PROP_OBJECT_PATH,
@@ -349,13 +357,13 @@ g_dbus_proxy_manager_class_init (GDBusProxyManagerClass *klass)
   /**
    * GDBusProxyManager:name:
    *
-   * The owner of the control object (unique or well-known name).
+   * The well-known name or unique name that the manager is for.
    */
   g_object_class_install_property (gobject_class,
                                    PROP_NAME,
                                    g_param_spec_string ("name",
                                                         "Name",
-                                                        "The owner of the control object",
+                                                        "Name that the manager is for",
                                                         NULL,
                                                         G_PARAM_READABLE |
                                                         G_PARAM_WRITABLE |
@@ -365,7 +373,9 @@ g_dbus_proxy_manager_class_init (GDBusProxyManagerClass *klass)
   /**
    * GDBusProxyManager:name-owner:
    *
-   * The owner of #GDBusProxyManager:name.
+   * The unique name that owns #GDBusProxyManager:name or %NULL if
+   * no-one is currently owning the name. Connect to the
+   * #GObject::notify signal to track changes to this property.
    */
   g_object_class_install_property (gobject_class,
                                    PROP_NAME_OWNER,
@@ -413,6 +423,10 @@ g_dbus_proxy_manager_class_init (GDBusProxyManagerClass *klass)
    * @object_proxy: The #GDBusObjectProxy that was added.
    *
    * Emitted when @object_proxy is added to @manager.
+   *
+   * This signal is emitted in the
+   * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+   * that @manager was constructed in.
    */
   signals[OBJECT_PROXY_ADDED_SIGNAL] =
     g_signal_new ("object-proxy-added",
@@ -432,6 +446,10 @@ g_dbus_proxy_manager_class_init (GDBusProxyManagerClass *klass)
    * @object_proxy: The #GDBusObjectProxy that was removed.
    *
    * Emitted when @object_proxy is removed from @manager.
+   *
+   * This signal is emitted in the
+   * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+   * that @manager was constructed in.
    */
   signals[OBJECT_PROXY_REMOVED_SIGNAL] =
     g_signal_new ("object-proxy-removed",
@@ -611,7 +629,8 @@ g_dbus_proxy_manager_new_finish (GAsyncResult   *res,
  * @cancellable: A #GCancellable or %NULL
  * @error: Return location for error or %NULL.
  *
- * Like g_dbus_proxy_manager_new_sync() but takes a #GBusType instead of a #GDBusConnection.
+ * Like g_dbus_proxy_manager_new_sync() but takes a #GBusType instead
+ * of a #GDBusConnection.
  *
  * This is a synchronous failable constructor - the calling thread is
  * blocked until a reply is received. See g_dbus_proxy_manager_new()
@@ -665,7 +684,8 @@ g_dbus_proxy_manager_new_for_bus_sync (GBusType                bus_type,
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
  * @user_data: The data to pass to @callback.
  *
- * Like g_dbus_proxy_manager_new() but takes a #GBusType instead of a #GDBusConnection.
+ * Like g_dbus_proxy_manager_new() but takes a #GBusType instead of a
+ * #GDBusConnection.
  *
  * This is an asynchronous failable constructor. When the result is
  * ready, @callback will be invoked in the
@@ -756,7 +776,7 @@ g_dbus_proxy_manager_get_connection (GDBusProxyManager *manager)
  * g_dbus_proxy_manager_get_object_path:
  * @manager: A #GDBusProxyManager
  *
- * Gets the object path that @manager is using for the control object.
+ * Gets the object path that @manager is for.
  *
  * Returns: An object path. Do not free, the string belongs to
  * @manager.
@@ -772,7 +792,7 @@ g_dbus_proxy_manager_get_object_path (GDBusProxyManager *manager)
  * g_dbus_proxy_manager_get_name:
  * @manager: A #GDBusProxyManager
  *
- * Gets the owner that @manager is using for the control object.
+ * Gets the name that @manager is for.
  *
  * Returns: A unique or well-known name. Do not free, the string
  * belongs to @manager.
@@ -805,7 +825,7 @@ g_dbus_proxy_manager_get_flags (GDBusProxyManager *manager)
  * @manager: A #GDBusProxyManager.
  *
  * The unique name that owns the name that @manager is for or %NULL if
- * no-one currently owns that name. You may connect to the
+ * no-one currently owns that name. You can connect to the
  * #GObject::notify signal to track changes to the
  * #GDBusProxyManager:name-owner property.
  *
diff --git a/src/gdbusproxymanager.h b/src/gdbusproxymanager.h
index b42d48d..badfba5 100644
--- a/src/gdbusproxymanager.h
+++ b/src/gdbusproxymanager.h
@@ -85,6 +85,10 @@ struct _GDBusProxyManagerClass
  * Function signature for a function used to determine the #GType to
  * use for an interface proxy.
  *
+ * This function is called in the
+ * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * that @manager was constructed in.
+ *
  * Returns: A #GType to use for the remote object. The returned type
  * must be a #GDBusProxy derived type.
  */