fix up EggDBusConnection docs

3 files changed, 157 insertions, 55 deletions

diff --git a/docs/eggdbus/eggdbus-docs.xml b/docs/eggdbus/eggdbus-docs.xml
index 2e087e4..eeac764 100644
--- a/docs/eggdbus/eggdbus-docs.xml
+++ b/docs/eggdbus/eggdbus-docs.xml
@@ -70,11 +70,8 @@
     <xi:include href="xml/eggdbusmethodinvocation.xml"/>
     <chapter id="collections">
         <title>Collections</title>
-        <xi:include href="xml/eggdbusarray.xml"/>
         <xi:include href="xml/eggdbusarrayseq.xml"/>
         <xi:include href="xml/eggdbushashmap.xml"/>
-        <xi:include href="xml/eggdbuslist.xml"/>
-        <xi:include href="xml/eggdbushashtable.xml"/>
         <xi:include href="xml/eggdbusvariant.xml"/>
         <xi:include href="xml/eggdbusstructure.xml"/>
     </chapter>
diff --git a/docs/eggdbus/eggdbus-sections.txt b/docs/eggdbus/eggdbus-sections.txt
index 7deb9fe..4cbeaef 100644
--- a/docs/eggdbus/eggdbus-sections.txt
+++ b/docs/eggdbus/eggdbus-sections.txt
@@ -16,8 +16,8 @@ egg_dbus_variant_new_for_signature_array
 egg_dbus_variant_new_for_byte
 egg_dbus_variant_new_for_int16
 egg_dbus_variant_new_for_uint16
-egg_dbus_variant_new_for_int32
-egg_dbus_variant_new_for_uint32
+egg_dbus_variant_new_for_int
+egg_dbus_variant_new_for_uint
 egg_dbus_variant_new_for_int64
 egg_dbus_variant_new_for_uint64
 egg_dbus_variant_new_for_boolean
@@ -34,8 +34,8 @@ egg_dbus_variant_set_signature_array
 egg_dbus_variant_set_byte
 egg_dbus_variant_set_int16
 egg_dbus_variant_set_uint16
-egg_dbus_variant_set_int32
-egg_dbus_variant_set_uint32
+egg_dbus_variant_set_int
+egg_dbus_variant_set_uint
 egg_dbus_variant_set_int64
 egg_dbus_variant_set_uint64
 egg_dbus_variant_set_boolean
@@ -52,8 +52,8 @@ egg_dbus_variant_get_signature_array
 egg_dbus_variant_get_byte
 egg_dbus_variant_get_int16
 egg_dbus_variant_get_uint16
-egg_dbus_variant_get_int32
-egg_dbus_variant_get_uint32
+egg_dbus_variant_get_int
+egg_dbus_variant_get_uint
 egg_dbus_variant_get_int64
 egg_dbus_variant_get_uint64
 egg_dbus_variant_get_boolean
@@ -71,8 +71,8 @@ egg_dbus_variant_is_signature_array
 egg_dbus_variant_is_byte
 egg_dbus_variant_is_int16
 egg_dbus_variant_is_uint16
-egg_dbus_variant_is_int32
-egg_dbus_variant_is_uint32
+egg_dbus_variant_is_int
+egg_dbus_variant_is_uint
 egg_dbus_variant_is_int64
 egg_dbus_variant_is_uint64
 egg_dbus_variant_is_boolean
diff --git a/src/eggdbus/eggdbusconnection.c b/src/eggdbus/eggdbusconnection.c
index 4afab75..5700985 100644
--- a/src/eggdbus/eggdbusconnection.c
+++ b/src/eggdbus/eggdbusconnection.c
@@ -42,7 +42,7 @@
  * @title: EggDBusConnection
  * @short_description: Connection
  *
- * The @EggDBusConnection class is used to connect to other processes or message buses.
+ * The #EggDBusConnection class is used to connect to other processes or message buses.
  */
 
 /* TODO: need locking to be MT-safe */
@@ -551,6 +551,15 @@ egg_dbus_connection_class_init (EggDBusConnectionClass *klass)
                                                         G_PARAM_STATIC_BLURB));
 }
 
+/**
+ * egg_dbus_connection_get_for_bus:
+ * @bus_type: The type of bus to get a connection for.
+ *
+ * Gets a connection to the bus specified by @bus_type. Note that this connection
+ * is shared with other processes; use TODO() to get a private connection.
+ *
+ * Returns: A #EggDBusConnection. Free with g_object_unref().
+ **/
 EggDBusConnection *
 egg_dbus_connection_get_for_bus (EggDBusBusType bus_type)
 {
@@ -592,6 +601,50 @@ egg_dbus_connection_get_for_bus (EggDBusBusType bus_type)
   return connection;
 }
 
+/**
+ * egg_dbus_connection_get_bus:
+ * @connection: A #EggDBusConnection.
+ *
+ * Gets the #EggDBusBus interface proxy for the <literal>org.freedesktop.DBus</literal> interface
+ * of the message bus daemon for @connection.
+ *
+ * This interface proxy is typically used to claim a well-known name on the message bus or to
+ * listen for signals like #EggDBusBus::name-acquired or #EggDBusBus::name-lost. For example,
+ * to claim the well-known name <literal>com.example.AwesomeProduct</literal> on the session
+ * message bus you would do this:
+ *
+ * <programlisting>
+ * EggDBusConnection *connection;
+ * EggDBusRequestNameReply request_name_reply;
+ * GError *error;
+ *
+ * connection = egg_dbus_connection_get_for_bus (EGG_DBUS_BUS_TYPE_SESSION);
+ *
+ * error = NULL;
+ * if (!egg_dbus_bus_invoke_request_name_sync (egg_dbus_connection_get_bus (connection),
+ *                                             EGG_DBUS_CALL_FLAGS_NONE,
+ *                                             "com.example.AwesomeProduct",
+ *                                             EGG_DBUS_REQUEST_NAME_FLAGS_NONE,
+ *                                             &request_name_reply,
+ *                                             NULL,
+ *                                             &error))
+ *   {
+ *     g_warning ("Error claiming com.example.AwesomeProduct on session bus: %s", error->message);
+ *     g_error_free (error);
+ *     goto error;
+ *   }
+ *
+ * if (request_name_reply != EGG_DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER)
+ *   {
+ *     g_warning ("Could not become primary owner of com.example.AwesomeProduct");
+ *     goto error;
+ *   }
+ *
+ * /<!-- -->* We now own com.example.AwesomeProduct  *<!-- -->/
+ * </programlisting>
+ *
+ * Returns: A #EggDBusBus. Do not free this object, it is owned by @connection.
+ **/
 EggDBusBus *
 egg_dbus_connection_get_bus (EggDBusConnection *connection)
 {
@@ -605,6 +658,16 @@ egg_dbus_connection_get_bus (EggDBusConnection *connection)
 }
 
 
+/**
+ * egg_dbus_connection_get_unique_name:
+ * @connection: A #EggDBusConnection.
+ *
+ * Gets the unique name (as assigned by the message bus daemon) of @connection. This
+ * method can only be used when @connection is a message bus connection.
+ *
+ * Returns: A unique bus name such as <literal>:1.42</literal>. Do not free this
+ * string, it is owned by @connection.
+ **/
 const gchar *
 egg_dbus_connection_get_unique_name (EggDBusConnection *connection)
 {
@@ -706,13 +769,20 @@ remove_match_rule_cb (EggDBusBus    *bus,
  * Gets a #EggDBusObjectProxy that represents a remote object at @object_path
  * owned by @name.
  *
- * The @connection object will track @name and report changes via the
- * #EggDBusObjectProxy:name-owner property on the returned #EggDBusObjectProxy object.
- * To track changes to #EggDBusObjectProxy:name-owner, connect to the #GObject::notify
- * signal on the returned object.
+ * The returned object proxy can be used to obtain interface proxies for calling methods, listen
+ * to signals and read/write properties on the D-Bus interfaces supported by the remote object.
+ * See the #EggDBusObjectProxy class for details.
+ *
+ * This method never fails. If either @name doesn't exist or it doesn't export an object
+ * at @object_path, you won't find out until you start invoking messages on it. You can
+ * use egg_dbus_object_proxy_introspect() to find out if the remote object exists in addition
+ * to what D-Bus interfaces it supports.
  *
- * Returns: A #EggDBusObjectProxy object. Call g_object_unref() when done with
- * it.
+ * Note that @connection will track @name and report changes via the #EggDBusObjectProxy:name-owner
+ * property on the returned #EggDBusObjectProxy object. To track changes to #EggDBusObjectProxy:name-owner,
+ * simply connect to the #GObject::notify signal on the returned object.
+ *
+ * Returns: A #EggDBusObjectProxy object. Free with g_object_unref().
  **/
 EggDBusObjectProxy *
 egg_dbus_connection_get_object_proxy (EggDBusConnection       *connection,
@@ -871,7 +941,7 @@ _egg_dbus_connection_unregister_object_proxy  (EggDBusConnection *connection,
  */
 gchar *
 _egg_dbus_connection_get_owner_for_name (EggDBusConnection *connection,
-                                       const gchar     *name)
+                                         const gchar     *name)
 {
   EggDBusConnectionPrivate *priv;
 
@@ -1173,8 +1243,9 @@ marshal_signal_onto_dbus (GClosure     *_closure,
  * @out_interface_stubs: Return location for the #GObject derived instances implementing the
  * corresponding #GInterface or %NULL.
  *
- * Looks up the interfaces at @object_path for @connection registered
- * using egg_dbus_connection_register_interface().
+ * This method looks up the interfaces at @object_path for @connection registered
+ * using egg_dbus_connection_register_interface(). This method is only useful when
+ * exporting a D-Bus service.
  *
  * Returns: Number of interfaces registered at @object_path. If zero is
  * returned @out_interface_types and @out_interface_stubs will be set
@@ -1244,8 +1315,9 @@ egg_dbus_connection_lookup_interface (EggDBusConnection   *connection,
  * @interface_type: A #GType for the type of #GInterface that represents the D-Bus interface to be unregistered.
  * @...: Zero or more #GType<!-- -->s (like @interface_type), terminated by #G_TYPE_INVALID.
  *
- * Unregisters one or more D-Bus interfaces at @object_path on @connection
- * previously registered with egg_dbus_connection_register_interface().
+ * Unregisters one or more D-Bus interfaces at @object_path on @connection previously
+ * registered with egg_dbus_connection_register_interface(). This method is only useful
+ * when exporting a D-Bus service.
  **/
 void
 egg_dbus_connection_unregister_interface (EggDBusConnection   *connection,
@@ -1325,30 +1397,24 @@ egg_dbus_connection_unregister_interface_valist (EggDBusConnection   *connection
  * @interface_type: A #GType for the type of #GInterface that represents the D-Bus interface to be registered.
  * @...: A #GObject derived instance implementing @interface_type, followed by more <literal>(type, instance pairs)</literal>, terminated by #G_TYPE_INVALID.
  *
- * Registers one or more D-Bus interfaces at @object_path on
- * @connection.
+ * Registers one or more D-Bus interfaces at @object_path on @connection. This function
+ * is only useful when exporting a D-Bus service.
  *
- * This function may be called multiple times for the same
- * @object_path. If an existing #GType for an interface is already
- * registered, it will be replaced.
+ * This function may be called multiple times for the same @object_path. If an existing
+ * #GType for an interface is already registered, it will be replaced.
  *
- * Only a weak reference to the given #GObject instances will be
- * taken; if the object is finalized it will automatically be
- * unregistered. Use egg_dbus_connection_unregister_interface() to
+ * Only a weak reference to the given #GObject instances will be taken; if a registered object is
+ * finalized it will automatically be unregistered. Use egg_dbus_connection_unregister_interface() to
  * manually unregister the interface.
  *
- * Note that the #EggDBusProperties, #EggDBusIntrospectable and
- * #EggDBusPeer interfaces will be automatically handled for
- * @object_path unless they specifically registered.
- *
- * For objects with relatively simple D-Bus interfaces (where there
- * are no name clashes on property and signal names), a single #GObject derived
- * class implementing multiple #GInterface<!-- -->s (each corresponding to a
- * D-Bus interface) can be used.
+ * Note that the #EggDBusProperties, #EggDBusIntrospectable and #EggDBusPeer interfaces will be
+ * automatically handled for @object_path unless they specifically registered.
  *
- * For more complex objects (with name clashes), separate #GObject
- * derived classes (typically one for each D-Bus interface) must be
- * used for disambiguation.
+ * For objects with relatively simple D-Bus interfaces (where there are no name clashes on property
+ * and signal names), a single #GObject derived class implementing multiple #GInterface<!-- -->s (each
+ * corresponding to a D-Bus interface) can be used. For more complex objects (with name clashes),
+ * separate #GObject derived classes (typically one for each D-Bus interface) must be used for
+ * disambiguation.
  */
 void
 egg_dbus_connection_register_interface (EggDBusConnection   *connection,
@@ -2151,6 +2217,14 @@ filter_function_handle_method_call (DBusConnection *dconnection,
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * egg_dbus_connection_send_message:
+ * @connection: A #EggDBusConnection.
+ * @message: A #EggDBusMessage.
+ *
+ * Sends @message on @connection without waiting for a reply. This method is
+ * only useful for language bindings.
+ **/
 void
 egg_dbus_connection_send_message (EggDBusConnection       *connection,
                                   EggDBusMessage          *message)
@@ -2180,16 +2254,18 @@ egg_dbus_connection_send_message_with_reply_sync_cb (EggDBusConnection *connecti
 
 /**
  * egg_dbus_connection_send_message_with_reply_sync:
- * @connection: 
- * @call_flags: 
- * @message: 
- * @error_types: 
- * @cancellable: 
- * @error: 
+ * @connection: A #EggDBusConnection.
+ * @call_flags: Flags from #EggDBusCallFlags detailing how the message should be sent.
+ * @message: The message to send.
+ * @error_types: Either %NULL or a #G_TYPE_INVALID terminated list of #GType<!-- -->s for #GError error domains to use
+ * when processing an error reply.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error.
  *
- * TODO: document.
+ * Queues @message to be sent and waits until a reply arrives. This method is
+ * only useful for language bindings.
  *
- * Returns: 
+ * Returns: The reply or %NULL if @error is set.
  **/
 EggDBusMessage *
 egg_dbus_connection_send_message_with_reply_sync (EggDBusConnection       *connection,
@@ -2341,7 +2417,7 @@ egg_dbus_connection_send_message_with_reply_cb (DBusPendingCall    *pending_call
  * egg_dbus_connection_pending_call_cancel:
  * @connection: A #EggDBusConnection.
  * @pending_call_id: A valid pending call id obtained from egg_dbus_connection_send_message_with_reply()
- * or similar wrapper functions (such as egg_dbus_bus_invoke_request_name_async()).
+ * or similar wrapper functions (such as egg_dbus_bus_invoke_request_name()).
  *
  * Cancels an asynchronous method invocation expecting a reply. The
  * #GAsyncReadyCallback callback given to
@@ -2391,7 +2467,7 @@ egg_dbus_connection_pending_call_cancel (EggDBusConnection *connection,
  * before this function returns.
  *
  * Depending on how the call was issued (e.g. what set of #EggDBusCallFlags was
- * passed), this function may uses a recursive #GMainLoop for blocking.
+ * passed), this function may use a recursive #GMainLoop for blocking.
  **/
 void
 egg_dbus_connection_pending_call_block (EggDBusConnection *connection,
@@ -2450,10 +2526,11 @@ egg_dbus_connection_pending_call_block (EggDBusConnection *connection,
  * @callback: Callback when the asynchronous operation finishes.
  * @user_data: User data to pass to @callback.
  *
- * Queues @message to be sent and invokes @callback (on the main thread) when there is a reply.
+ * Queues @message to be sent and invokes @callback (on the main thread) when there is a reply. This method is
+ * only useful for language bindings.
  *
- * In @callback, egg_dbus_connection_send_message_with_reply_finish()
- * should be used to extract the reply or error.
+ * In @callback, egg_dbus_connection_send_message_with_reply_finish() should be used to
+ * extract the reply or error.
  *
  * Returns: A pending call id (never zero) that can be used with egg_dbus_connection_pending_call_cancel() or
  * egg_dbus_connection_pending_call_block().
@@ -2589,6 +2666,20 @@ out:
 
 /* ---------------------------------------------------------------------------------------------------- */
 
+/**
+ * egg_dbus_connection_new_message_for_signal:
+ * @connection: A #EggDBusConnection.
+ * @sender: Sender of the signal or %NULL to use unique name for @connection.
+ * @destination: Destination of signal or %NULL to multi-cast to all recipients on the bus.
+ * @object_path: The object path to broadcast the signal on.
+ * @interface_name: The interface name to which @signal_name belongs.
+ * @signal_name: Name of the signal to broadcast.
+ *
+ * Creates a new #EggDBusMessage for sending a signal. This method is
+ * only useful for language bindings.
+ *
+ * Returns: A new #EggDBusMessage. Free with g_object_unref().
+ **/
 EggDBusMessage *
 egg_dbus_connection_new_message_for_signal (EggDBusConnection       *connection,
                                             const gchar             *sender,
@@ -2612,6 +2703,20 @@ egg_dbus_connection_new_message_for_signal (EggDBusConnection       *connection,
                                        NULL));
 }
 
+/**
+ * egg_dbus_connection_new_message_for_method_call:
+ * @connection: A #EggDBusConnection.
+ * @sender: Sender of the message or %NULL to use unique name for @connection.
+ * @destination: Destination of name to invoke method on.
+ * @object_path: The object to invoke the method on.
+ * @interface_name: The interface name to which @method_name belongs.
+ * @method_name: The name of the method to invoke.
+ *
+ * Creates a new #EggDBusMessage for invoking a method. This method is
+ * only useful for language bindings.
+ *
+ * Returns: A new #EggDBusMessage. Free with g_object_unref().
+ **/
 EggDBusMessage *
 egg_dbus_connection_new_message_for_method_call (EggDBusConnection       *connection,
                                                  const gchar             *sender,