[glibmm] DBusConnection: Add docs to some methods.

[José Alburquerque <jaalburqu src gnome org>]

commit 31f5957ecdce914e52994a08709de5dcfb50ceaa
Author: José Alburquerque <jaalburqu svn gnome org>
Date:   Tue Oct 26 20:30:22 2010 -0400

    	DBusConnection: Add docs to some methods.
    
    	* gio/src/dbusconnection.hg: Add Doxygen docs to wrapped methods
    	without them.
    	* gio/src/dbusproxy.hg: Typo.

 ChangeLog                 |    8 ++
 gio/src/dbusconnection.hg |  191 +++++++++++++++++++++++++++++++++++++++++----
 gio/src/dbusproxy.hg      |    4 +-
 3 files changed, 187 insertions(+), 16 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 7621961..3676d32 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2010-10-26  José Alburquerque  <jaalburqu svn gnome org>
 
+	DBusConnection: Add docs to some methods.
+
+	* gio/src/dbusconnection.hg: Add Doxygen docs to wrapped methods
+	without them.
+	* gio/src/dbusproxy.hg: Typo.
+
+2010-10-26  José Alburquerque  <jaalburqu svn gnome org>
+
 	DBusProxy: Add get_cached_property().
 
 	* gio/src/dbusproxy.{ccg,hg}: Add get_cached_property(), wrapping
diff --git a/gio/src/dbusconnection.hg b/gio/src/dbusconnection.hg
index b0e8bda..988bdc1 100644
--- a/gio/src/dbusconnection.hg
+++ b/gio/src/dbusconnection.hg
@@ -85,7 +85,19 @@ protected:
 
 public:
 
-  /** TODO
+  /** Asynchronously connects to the message bus specified by @a bus_type.
+   *
+   * When the operation is finished, @a slot will be invoked. You can then
+   * call get_finish() to get the result of the operation.
+   *
+   * This is a asynchronous failable function. See get_sync() for the
+   * synchronous version.
+   *
+   * @param bus_type A BusType.
+   * @param slot A SlotAsyncReady to call when the request is satisfied.
+   * @param cancellable A Cancellable.
+   *
+   * @newin{2,26}
    */
   void get(BusType bus_type, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable = Glib::RefPtr<Cancellable>());
   _IGNORE(g_bus_get)
@@ -128,52 +140,203 @@ public:
     DBusConnectionFlags flags, const Glib::RefPtr<DBusAuthObserver>& observer,
     const Glib::RefPtr<Cancellable>& cancellable = Glib::RefPtr<Cancellable>());
 
-  //TODO: Documentation.
+  /** Closes the connection. Note that this never causes the process to exit
+   * (this might only happen if the other end of a shared message bus
+   * connection disconnects, see property_exit_on_close()).
+   *
+   * Once the connection is closed, operations such as sending a message will
+   * return with the error Gio::IO_ERROR_CLOSED. Closing a connection will not
+   * automatically flush the connection so queued messages may be lost. Use
+   * flush() if you need such guarantees.
+   *
+   * If the connection is already closed, this method fails with
+   * Gio::IO_ERROR_CLOSED.
+   *
+   * When the connection has been closed, the "closed" signal is emitted in
+   * the thread-default main loop of the thread that connection was
+   * constructed in.
+   *
+   * This is an asynchronous method.  See close_sync() for the synchronous
+   * version.
+   *
+   * @newin{2,26}
+   */
   void close();
 
-  //TODO: Documentation.
+  /** Closes the connection. Note that this never causes the process to exit
+   * (this might only happen if the other end of a shared message bus
+   * connection disconnects, see property_exit_on_close()).
+   *
+   * Once the connection is closed, operations such as sending a message will
+   * return with the error Gio::IO_ERROR_CLOSED. Closing a connection will not
+   * automatically flush the connection so queued messages may be lost. Use
+   * flush() if you need such guarantees.
+   *
+   * If the connection is already closed, this method fails with
+   * Gio::IO_ERROR_CLOSED.
+   *
+   * When the connection has been closed, the "closed" signal is emitted in
+   * the thread-default main loop of the thread that connection was
+   * constructed in.
+   *
+   * This is an asynchronous method. When the operation is finished, @a slot
+   * will be invoked in the thread-default main loop of the thread you are
+   * calling this method from. You can then call close_finish() to get the
+   * result of the operation. See close_sync() for the synchronous version.
+   *
+   * @param slot A SlotAsyncReady to call when the request is satisfied.
+   * @param cancellable A Cancellable.
+   *
+   * @newin{2,26}
+   */
   void close(const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
 
-  //TODO: Documentation.
+  /** Closes the connection. Note that this never causes the process to exit
+   * (this might only happen if the other end of a shared message bus
+   * connection disconnects, see property_exit_on_close()).
+   *
+   * Once the connection is closed, operations such as sending a message will
+   * return with the error Gio::IO_ERROR_CLOSED. Closing a connection will not
+   * automatically flush the connection so queued messages may be lost. Use
+   * flush() if you need such guarantees.
+   *
+   * If the connection is already closed, this method fails with
+   * Gio::IO_ERROR_CLOSED.
+   *
+   * When the connection has been closed, the "closed" signal is emitted in
+   * the thread-default main loop of the thread that connection was
+   * constructed in.
+   *
+   * This is an asynchronous method. When the operation is finished, @a slot
+   * will be invoked in the thread-default main loop of the thread you are
+   * calling this method from. You can then call close_finish() to get the
+   * result of the operation. See close_sync() for the synchronous version.
+   *
+   * @param slot A SlotAsyncReady to call when the request is satisfied.
+   *
+   * @newin{2,26}
+   */
   void close(const SlotAsyncReady& slot);
   _IGNORE(g_dbus_connection_close)
 
   _WRAP_METHOD(bool close_finish(const Glib::RefPtr<AsyncResult>& result),
                g_dbus_connection_close_finish, errthrow)
 
-  //TODO: Documentation.
+  /** Synchronously closees the connection. The calling thread is blocked
+   * until this is done. See close() for the asynchronous version of this
+   * method and more details about what it does.
+   *
+   * @newin{2,26}
+   *
+   * @throw Glib::Error.
+   */
   void close_sync();
 
-  //TODO: Documentation.
   _WRAP_METHOD(void close_sync(const Glib::RefPtr<Cancellable>& cancellable), g_dbus_connection_close_sync, errthrow)
 
-
-  //TODO: Documentation.
+  /** Asynchronously flushes the connection, that is, writes all queued
+   * outgoing message to the transport and then flushes the transport (using
+   * Gio::OutputStream::flush_async()). This is useful in programs that wants
+   * to emit a D-Bus signal and then exit immediately. Without flushing the
+   * connection, there is no guarantee that the message has been sent to the
+   * networking buffers in the OS kernel.
+   *
+   * This is an asynchronous method. See flush_sync() for the synchronous
+   * version.
+   *
+   * @newin{2,26}
+   */
   void flush();
 
-  //TODO: Documentation.
+  /** Asynchronously flushes the connection, that is, writes all queued
+   * outgoing message to the transport and then flushes the transport (using
+   * Gio::OutputStream::flush_async()). This is useful in programs that wants
+   * to emit a D-Bus signal and then exit immediately. Without flushing the
+   * connection, there is no guarantee that the message has been sent to the
+   * networking buffers in the OS kernel.
+   *
+   * This is an asynchronous method. When the operation is finished, @a slot
+   * will be invoked in the thread-default main loop of the thread you are
+   * calling this method from. You can then call flush_finish() to get the
+   * result of the operation. See flush_sync() for the synchronous version.
+   *
+   * @param slot A SlotAsyncReady to call when the request is satisfied.
+   * @param cancellable A Cancellable.
+   *
+   * @newin{2,26}
+   */
   void flush(const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
 
-  //TODO: Documentation.
+  /** Asynchronously flushes the connection, that is, writes all queued
+   * outgoing message to the transport and then flushes the transport (using
+   * Gio::OutputStream::flush_async()). This is useful in programs that wants
+   * to emit a D-Bus signal and then exit immediately. Without flushing the
+   * connection, there is no guarantee that the message has been sent to the
+   * networking buffers in the OS kernel.
+   *
+   * This is an asynchronous method. When the operation is finished, @a slot
+   * will be invoked in the thread-default main loop of the thread you are
+   * calling this method from. You can then call flush_finish() to get the
+   * result of the operation. See flush_sync() for the synchronous version.
+   *
+   * @param slot A SlotAsyncReady to call when the request is satisfied.
+   *
+   * @newin{2,26}
+   */
   void flush(const SlotAsyncReady& slot);
   _IGNORE(g_dbus_connection_flush)
 
   _WRAP_METHOD(bool flush_finish(const Glib::RefPtr<AsyncResult>& result),
                g_dbus_connection_flush_finish, errthrow)
 
-  //TODO: Documentation.
+  /** Synchronously flushes the connection. The calling thread is blocked
+   * until this is done. See flush() for the asynchronous version of this
+   * method and more details about what it does.
+   *
+   * @newin{2,26}
+   *
+   * @throw Glib::Error.
+   */
   void flush_sync();
 
-  //TODO: Documentation.
   _WRAP_METHOD(void flush_sync(const Glib::RefPtr<Cancellable>& cancellable), g_dbus_connection_flush_sync, errthrow)
 
   //TODO: In the C API, out_serial is volatile, but gmmproc can't parse that.
   #m4 _CONVERSION(`guint32*',`volatile guint32*',`($3)')
   _WRAP_METHOD(bool send_message(const Glib::RefPtr<DBusMessage>& message, DBusSendMessageFlags flags, guint32* out_serial), g_dbus_connection_send_message, errthrow)
 
-    //TODO: Documentation.
-  _IGNORE(g_dbus_connection_send_message_with_reply)
+  /** Asynchronously sends message to the peer represented by connection.
+   *
+   * Unless flags contain the Gio::DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL
+   * flag, the serial number will be assigned by connection and set on message
+   * via Gio::DBusMessage::set_serial().
+   *
+   * If the connection is closed then the operation will fail with
+   * Gio::IO_ERROR_CLOSED. If @a cancellable is canceled, the operation will
+   * fail with Gio::IO_ERROR_CANCELLED. If @a message is not well-formed, the
+   * operation fails with Gio::IO_ERROR_INVALID_ARGUMENT.
+   *
+   * This is an asynchronous method. When the operation is finished, @a slot
+   * will be invoked in the thread-default main loop of the thread you are
+   * calling this method from. You can then call
+   * send_message_with_reply_finish() to get the result of the operation. See
+   * send_message_with_reply_sync() for the synchronous version.
+   *
+   * Note that message must be unlocked, unless flags contain the
+   * Gio::DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
+   *
+   * See the C API docs for examples.
+   *
+   * @param message A DBusMessage.
+   * @param timeout_msec The timeout in milliseconds or -1 to use the default
+   * timeout.
+   * @param slot A SlotAsyncReady to call when the request is satisfied.
+   * @param cancellable A Cancellable.
+   *
+   * @newin{2,26}
+   */
   void send_message_with_reply(const Glib::RefPtr<DBusMessage>& message, int timeout_msec, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable = Glib::RefPtr<Cancellable>());
+  _IGNORE(g_dbus_connection_send_message_with_reply)
 
   /// @throw Glib::Error.
   _WRAP_METHOD(Glib::RefPtr<DBusMessage> send_message_with_reply_finish(const Glib::RefPtr<AsyncResult>& result), g_dbus_connection_send_message_with_reply_finish, errthrow)
diff --git a/gio/src/dbusproxy.hg b/gio/src/dbusproxy.hg
index a3f56e6..af1dc1d 100644
--- a/gio/src/dbusproxy.hg
+++ b/gio/src/dbusproxy.hg
@@ -147,8 +147,8 @@ public:
   /** Looks up the value for a property from the cache. This call does no
    * blocking IO.
    *
-   * If proxy has an expected interface (see property_interface_info()), then
-   * @a property_name (for existence) is checked against it.
+   * If proxy has an expected interface (see property_g_interface_info()),
+   * then @a property_name (for existence) is checked against it.
    *
    * @param property_name Property name.
    *