fix up docs for EggDBusObjectProxy

2 files changed, 120 insertions, 4 deletions

diff --git a/src/eggdbus/eggdbusobjectproxy.c b/src/eggdbus/eggdbusobjectproxy.c
index 2afaadd..df16ada 100644
--- a/src/eggdbus/eggdbusobjectproxy.c
+++ b/src/eggdbus/eggdbusobjectproxy.c
@@ -43,7 +43,72 @@
  * @short_description: Proxy for remote objects
  * @see_also: #EggDBusConnection
  *
- * Instances of #EggDBusObjectProxy represents a remote object.
+ * Instances of the #EggDBusObjectProxy class represents remote objects. You can't instantiate
+ * this class directly, you have to use egg_dbus_connection_get_object_proxy(). The tripple
+ * consisting of a connection, bus name and object path uniquely identifies a remote object.
+ *
+ * You can get the connection name, object path for a #EggDBusObjectProxy instance from the
+ * #EggDBusObjectProxy:connection, #EggDBusObjectProxy:name and #EggDBusObjectProxy:object-path
+ * properties. Also, the <emphasis>current</emphasis> owner of the name the object proxy is
+ * associated with can be obtained from the #EggDBusObjectProxy:name-owner property.
+ *
+ * Note that an #EggDBusObjectProxy instance may refer to a non-existant remote object. For
+ * example names on the message bus can come and go (can be checked with #EggDBusObjectProxy:name-owner)
+ * and the remote object itself may be destroyed (for example if the object represents a
+ * piece of hardware on the system, the object may disappear when the hardware is unplugged).
+ * One way (if the remote service supports introspection) to find out if a remote object exists
+ * is to use the egg_dbus_object_proxy_introspect() method. If the call succeeds and the result
+ * includes one or more interfaces, the object is alive:
+ *
+ * <programlisting>
+ * EggDBusInterfaceNodeInfo *node_info;
+ * GError *error;
+ *
+ * error = NULL;
+ * node_info = egg_dbus_object_proxy_introspect_sync (slash_object_proxy,
+ *                                                    EGG_DBUS_CALL_FLAGS_NONE,
+ *                                                    NULL,
+ *                                                    &error);
+ * if (node_info == NULL)
+ *   {
+ *     /<!-- -->* handle error *<!-- -->/
+ *   }
+ * else
+ *   {
+ *     if (node_info->num_interfaces > 0)
+ *       {
+ *         /<!-- -->* object is alive, look at node_info for more information *<!-- -->/
+ *       }
+ *     egg_dbus_interface_node_info_free (node_info);
+ *   }
+ * </programlisting>
+ *
+ * To use a D-Bus interface on a #EggDBusObjectProxy instance you will need a #EggDBusInterfaceProxy
+ * instance for the D-Bus interface in question. Interface proxies can be obtained using the
+ * egg_dbus_object_proxy_query_interface() method. Typically language bindings will provide a
+ * way to obtain it; for generated C/GObject code, a macro is generated. For example, to invoke the
+ * <literal>Ping</literal> method on the <literal>org.freedesktop.DBus.Peer</literal> interface
+ * on a #EggDBusObjectProxy, the #EggDBusPeer interface proxy is used:
+ *
+ * <programlisting>
+ * EggDBusPeer *peer;
+ * GError *error;
+ *
+ * peer = EGG_DBUS_QUERY_INTERFACE_PEER (object_proxy);
+ *
+ * error = NULL;
+ * if (!egg_dbus_peer_invoke_ping_sync (peer,
+ *                                      EGG_DBUS_CALL_FLAGS_NONE,
+ *                                      NULL, /<!-- -->* GCancellable *<!-- -->/
+ *                                      &error))
+ *   {
+ *     g_warning ("Error: %s", error->message);
+ *     g_error_free (error);
+ *     goto error;
+ *   }
+ * </programlisting>
+ *
+ * See the #EggDBusInterfaceProxy class for more details on using D-Bus interfaces.
  */
 
 typedef struct
@@ -359,6 +424,11 @@ egg_dbus_object_proxy_class_init (EggDBusObjectProxyClass *klass)
 
   g_type_class_add_private (klass, sizeof (EggDBusObjectProxyPrivate));
 
+  /**
+   * EggDBusObjectProxy:name:
+   *
+   * The name on the bus that the #EggDBusObjectProxy instance is associated with.
+   */
   g_object_class_install_property (gobject_class,
                                    PROP_NAME,
                                    g_param_spec_string ("name",
@@ -387,7 +457,7 @@ egg_dbus_object_proxy_class_init (EggDBusObjectProxyClass *klass)
    * <literal>:1.42</literal>), then this property is equal to that
    * name only if the remote end with the given name is connected to
    * the bus. If the remote end disconnects, the property changes to
-   * %NULL.  If this is the case then the object_proxy is pretty much useless
+   * %NULL.  If this is the case then the object proxy is pretty much useless
    * as unique names are never recycled.
    *
    * Connect to the #GObject::notify signal to track changes to this
@@ -404,6 +474,11 @@ egg_dbus_object_proxy_class_init (EggDBusObjectProxyClass *klass)
                                                         G_PARAM_STATIC_NICK |
                                                         G_PARAM_STATIC_BLURB));
 
+  /**
+   * EggDBusObjectProxy:object-path:
+   *
+   * The object path that the #EggDBusObjectProxy instance is associated with.
+   */
   g_object_class_install_property (gobject_class,
                                    PROP_OBJECT_PATH,
                                    g_param_spec_boxed ("object-path",
@@ -416,11 +491,16 @@ egg_dbus_object_proxy_class_init (EggDBusObjectProxyClass *klass)
                                                        G_PARAM_STATIC_NICK |
                                                        G_PARAM_STATIC_BLURB));
 
+  /**
+   * EggDBusObjectProxy:connection:
+   *
+   * The connection that the #EggDBusObjectProxy instance is associated with.
+   */
   g_object_class_install_property (gobject_class,
                                    PROP_CONNECTION,
                                    g_param_spec_object ("connection",
                                                         "Connection",
-                                                        "The connection that owns the object_proxy",
+                                                        "The connection that owns the object proxy",
                                                         EGG_DBUS_TYPE_CONNECTION,
                                                         G_PARAM_READWRITE |
                                                         G_PARAM_CONSTRUCT_ONLY |
@@ -442,6 +522,15 @@ _egg_dbus_object_proxy_new (EggDBusConnection *connection,
                                      NULL));
 }
 
+/**
+ * egg_dbus_object_proxy_get_connection:
+ * @object_proxy: A #EggDBusObjectProxy.
+ *
+ * C getter for the #EggDBusObjectProxy:connection property.
+ *
+ * Returns: The #EggDBusConnection that @object_proxy is associated with. Do not free, the
+ *          connection object is owned by @object_proxy.
+ **/
 EggDBusConnection *
 egg_dbus_object_proxy_get_connection (EggDBusObjectProxy *object_proxy)
 {
@@ -452,6 +541,15 @@ egg_dbus_object_proxy_get_connection (EggDBusObjectProxy *object_proxy)
   return priv->connection;
 }
 
+/**
+ * egg_dbus_object_proxy_get_name:
+ * @object_proxy: A #EggDBusObjectProxy.
+ *
+ * C getter for the #EggDBusObjectProxy:name property.
+ *
+ * Returns: The bus name that @object_proxy is associated with. Do not free, the
+ *          string is owned by @object_proxy.
+ **/
 const gchar *
 egg_dbus_object_proxy_get_name (EggDBusObjectProxy *object_proxy)
 {
@@ -462,6 +560,15 @@ egg_dbus_object_proxy_get_name (EggDBusObjectProxy *object_proxy)
   return priv->name;
 }
 
+/**
+ * egg_dbus_object_proxy_get_object_path:
+ * @object_proxy: A #EggDBusObjectProxy.
+ *
+ * C getter for the #EggDBusObjectProxy:object-path property.
+ *
+ * Returns: The object path that @object_proxy is associated with. Do not free, the
+ *          string is owned by @object_proxy.
+ **/
 const gchar *
 egg_dbus_object_proxy_get_object_path (EggDBusObjectProxy *object_proxy)
 {
@@ -472,6 +579,15 @@ egg_dbus_object_proxy_get_object_path (EggDBusObjectProxy *object_proxy)
   return priv->object_path;
 }
 
+/**
+ * egg_dbus_object_proxy_get_name_owner:
+ * @object_proxy: A #EggDBusObjectProxy.
+ *
+ * C getter for the #EggDBusObjectProxy:name-owner property.
+ *
+ * Returns: The unique name, if any, that owns the name that @object_proxy is associated
+ *          with. Free with g_free().
+ **/
 gchar *
 egg_dbus_object_proxy_get_name_owner (EggDBusObjectProxy *object_proxy)
 {
diff --git a/src/tests/testclient.c b/src/tests/testclient.c
index 8d298fd..3fd68d7 100644
--- a/src/tests/testclient.c
+++ b/src/tests/testclient.c
@@ -3066,7 +3066,7 @@ test_register_interface (void)
   EggDBusObjectProxy *slash_object_proxy;
   EggDBusObjectProxy *slash_foo_object_proxy;
   EggDBusObjectProxy *slash_foo_bar0_object_proxy;
-  EggDBusInterfaceNodeInfo*node_info;
+  EggDBusInterfaceNodeInfo *node_info;
   GError *error;
   gchar *s;