Add some documentation.

        * gio/src/dbusintrospection.hg:
        * gio/src/dbusserver.ccg:
        * gio/src/inputstream.hg:
        * gio/src/menu.hg:
        * gio/src/menuitem.hg:
        * gio/src/outputstream.hg:
        * glib/src/threads.hg: Deal with some TODOS, mostly
adding documentation based on the C documentation.

8 files changed, 168 insertions, 90 deletions

diff --git a/ChangeLog b/ChangeLog
index 5071ddd6..13dacb11 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,18 @@
 2012-10-21  Murray Cumming  <murrayc@murrayc.com>
 
+        Add some documentation.
+
+        * gio/src/dbusintrospection.hg:
+        * gio/src/dbusserver.ccg:
+        * gio/src/inputstream.hg:
+        * gio/src/menu.hg:
+        * gio/src/menuitem.hg:
+        * gio/src/outputstream.hg:
+        * glib/src/threads.hg: Deal with some TODOS, mostly
+	adding documentation based on the C documentation.
+
+2012-10-21  Murray Cumming  <murrayc@murrayc.com>
+
         Create only .tar.xz tarballs.
 
         * configure.ac: This is what ftp.gnome.org wants, so this avoids
diff --git a/gio/src/dbusintrospection.hg b/gio/src/dbusintrospection.hg
index 729b25d0..1e156374 100644
--- a/gio/src/dbusintrospection.hg
+++ b/gio/src/dbusintrospection.hg
@@ -141,10 +141,12 @@ public:
   _WRAP_METHOD(Glib::RefPtr<InterfaceInfo> lookup_interface(const Glib::ustring& name), g_dbus_node_info_lookup_interface, refreturn)
   _WRAP_METHOD(Glib::RefPtr<const InterfaceInfo> lookup_interface(const Glib::ustring& name) const, g_dbus_node_info_lookup_interface, constversion, refreturn)
  
-  //TODO: Documentation: 
+  /** Looks up information about the first interface.
+   */
   Glib::RefPtr<InterfaceInfo> lookup_interface();
 
-  //TODO: Documentation:
+  /** Looks up information about the first interface.
+   */
   Glib::RefPtr<const InterfaceInfo> lookup_interface() const;
   
   //TODO: _WRAP_METHOD(void generate_xml(guint indent, GString* string_builder), g_dbus_node_info_generate_xml)
diff --git a/gio/src/dbusserver.ccg b/gio/src/dbusserver.ccg
index 9454bf2c..8e22657c 100644
--- a/gio/src/dbusserver.ccg
+++ b/gio/src/dbusserver.ccg
@@ -87,26 +87,8 @@ Glib::RefPtr<Server> Server::create_sync(const std::string& address,
   const Glib::RefPtr<Cancellable>& cancellable,
   ServerFlags flags)
 {
-  //TODO: Use the constructor instead of the code underneath when
-  //g_dbus_server_new_sync() does not do more than call g_initable_new().
-  //https://bugzilla.gnome.org/show_bug.cgi?id=639478
-  //return Glib::RefPtr<Server>(new Server(address, guid, observer,
-    //cancellable, flags));
-
-  GError* gerror = 0;
-
-  Glib::RefPtr<Server> result =
-    Glib::wrap(g_dbus_server_new_sync(address.c_str(),
-                                      static_cast<GDBusServerFlags>(flags),
-                                      guid.c_str(),
-                                      Glib::unwrap(observer),
-                                      Glib::unwrap(cancellable),
-                                      &gerror));
-
-  if(gerror)
-    ::Glib::Error::throw_exception(gerror);
-
-  return result;
+  return Glib::RefPtr<Server>(new Server(address, guid, observer,
+    cancellable, flags));
 }
 
 Glib::RefPtr<Server> Server::create_sync(const std::string& address,
@@ -114,25 +96,8 @@ Glib::RefPtr<Server> Server::create_sync(const std::string& address,
   const Glib::RefPtr<Cancellable>& cancellable,
   ServerFlags flags)
 {
-  //TODO: Use the constructor instead of the code underneath when
-  //g_dbus_server_new_sync() does not do more than call g_initable_new().
-  //https://bugzilla.gnome.org/show_bug.cgi?id=639478
-  //return Glib::RefPtr<Server>(new Server(address, guid,
-    //cancellable, flags));
-
-  GError* gerror = 0;
-
-  Glib::RefPtr<Server> result =
-    Glib::wrap(g_dbus_server_new_sync(address.c_str(),
-                                      static_cast<GDBusServerFlags>(flags),
-                                      guid.c_str(), 0,
-                                      Glib::unwrap(cancellable),
-                                      &gerror));
-
-  if(gerror)
-    ::Glib::Error::throw_exception(gerror);
-
-  return result;
+  return Glib::RefPtr<Server>(new Server(address, guid,
+    cancellable, flags));
 }
 
 Glib::RefPtr<Server> Server::create_sync(const std::string& address,
@@ -140,48 +105,15 @@ Glib::RefPtr<Server> Server::create_sync(const std::string& address,
   const Glib::RefPtr<AuthObserver>& observer,
   ServerFlags flags)
 {
-  //TODO: Use the constructor instead of the code underneath when
-  //g_dbus_server_new_sync() does not do more than call g_initable_new().
-  //https://bugzilla.gnome.org/show_bug.cgi?id=639478
-  //return Glib::RefPtr<Server>(new Server(address, guid, observer,
-    //flags));
-
-  GError* gerror = 0;
-
-  Glib::RefPtr<Server> result =
-    Glib::wrap(g_dbus_server_new_sync(address.c_str(),
-                                      static_cast<GDBusServerFlags>(flags),
-                                      guid.c_str(),
-                                      Glib::unwrap(observer),
-                                      0,
-                                      &gerror));
-
-  if(gerror)
-    ::Glib::Error::throw_exception(gerror);
-
-  return result;
+  return Glib::RefPtr<Server>(new Server(address, guid, observer,
+    flags));
 }
 
 Glib::RefPtr<Server> Server::create_sync(const std::string& address,
   const std::string& guid,
   ServerFlags flags)
 {
-  //TODO: Use the constructor instead of the code underneath when
-  //g_dbus_server_new_sync() does not do more than call g_initable_new().
-  //https://bugzilla.gnome.org/show_bug.cgi?id=639478
-  //return Glib::RefPtr<Server>(new Server(address, guid, flags));
-
-  GError* gerror = 0;
-
-  Glib::RefPtr<Server> result =
-    Glib::wrap(g_dbus_server_new_sync(address.c_str(),
-                                      static_cast<GDBusServerFlags>(flags),
-                                      guid.c_str(), 0, 0, &gerror));
-
-  if(gerror)
-    ::Glib::Error::throw_exception(gerror);
-
-  return result;
+  return Glib::RefPtr<Server>(new Server(address, guid, flags));
 }
 
 } // namespace DBus
diff --git a/gio/src/inputstream.hg b/gio/src/inputstream.hg
index acfb9d35..ba55fa29 100644
--- a/gio/src/inputstream.hg
+++ b/gio/src/inputstream.hg
@@ -64,13 +64,60 @@ public:
 
   _WRAP_METHOD(Glib::RefPtr<Glib::Bytes> read_bytes(gsize count, const Glib::RefPtr<Cancellable>& cancellable), g_input_stream_read_bytes, errthrow)
 
-  //TODO: Documentation.
-  /**
+  //TODO: Why not use _WRAP_METHOD() for this?
+  /** Request an asynchronous read of @a count bytes from the stream into a
+   * new Glib::Bytes. When the operation is finished @a slot will be called. 
+   * You can then call read_bytes_finish() to get the result of the 
+   * operation.
+   *
+   * During an async request no other sync and async calls are allowed, and will
+   * result in Gio::Error with PENDING being thrown. 
+   *
+   * A value of @a count larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown.
+   *
+   * On success, the new Glib::Bytes will be passed to the callback. It is
+   * not an error if this is smaller than the requested size, as it can
+   * happen e.g. near the end of a file, but generally we try to read as
+   * many bytes as requested. Zero is returned on end of file (or if
+   * @a count is zero), but never otherwise.
+   *
+   * Any outstanding I/O request with higher priority (lower numerical
+   * value) will be executed before an outstanding request with lower
+   * priority. The default priority is PRIORITY_DEFAULT.
+   *
+   * @param count The number of bytes that will be read from the stream.
+   * @param slot Callback to call when the request is satisfied.
+   * @param cancellable A Cancellable object.
+   * @param io_priority The I/O priority of the request.
+   *
    * @newin{2,34}
    */
   void read_bytes_async(gsize count, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = Glib::PRIORITY_DEFAULT);
 
-  /**
+  /** Request an asynchronous read of @a count bytes from the stream into a
+   * new Glib::Bytes. When the operation is finished @a slot will be called. 
+   * You can then call read_bytes_finish() to get the result of the 
+   * operation.
+   *
+   * During an async request no other sync and async calls are allowed, and will
+   * result in Gio::Error with PENDING being thrown. 
+   *
+   * A value of @a count larger than MAXSSIZE will cause a Gio::Error with INVALID_ARGUMENT to be thrown.
+   *
+   * On success, the new Glib::Bytes will be passed to the callback. It is
+   * not an error if this is smaller than the requested size, as it can
+   * happen e.g. near the end of a file, but generally we try to read as
+   * many bytes as requested. Zero is returned on end of file (or if
+   * @a count is zero), but never otherwise.
+   *
+   * Any outstanding I/O request with higher priority (lower numerical
+   * value) will be executed before an outstanding request with lower
+   * priority. The default priority is PRIORITY_DEFAULT.
+   *
+   * @param count The number of bytes that will be read from the stream.
+   * @param slot Callback to call when the request is satisfied.h
+   * @param io_priority The I/O priority of the request.
+   *
    * @newin{2,34}
    */
   void read_bytes_async(gsize count, const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT);
@@ -117,7 +164,7 @@ public:
    * @param count The number of bytes that will be read from the stream.
    * @param slot Callback to call when the request is satisfied.
    * @param cancellable A Cancellable object.
-   * @param io_priority The I/O priority of the request. 
+   * @param io_priority The I/O priority of the request.
    */
   void read_async(void* buffer, gsize count, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = Glib::PRIORITY_DEFAULT);
 
diff --git a/gio/src/menu.hg b/gio/src/menu.hg
index 0f527340..d6e05e40 100644
--- a/gio/src/menu.hg
+++ b/gio/src/menu.hg
@@ -24,7 +24,14 @@ _PINCLUDE(giomm/private/menumodel_p.h)
 namespace Gio
 {
 
-/** TODO
+/** A simple implementation of GMenuModel.
+ * You populate a Menu by adding MenuItem instances to it.
+ *
+ * There are some convenience methods to allow you to directly
+ * add items (avoiding MenuItem) for the common cases. To add
+ * a regular item, use insert(). To add a section, use
+ * insert_section(). To add a submenu, use
+ * insert_submenu().
  *
  * @newin{2,32}
  */
diff --git a/gio/src/menuitem.hg b/gio/src/menuitem.hg
index 04bf0682..51e5e84a 100644
--- a/gio/src/menuitem.hg
+++ b/gio/src/menuitem.hg
@@ -24,7 +24,7 @@ _PINCLUDE(glibmm/private/object_p.h)
 namespace Gio
 {
 
-/** TODO
+/** A menu item for use with Gio::Menu.
  *
  * @newin{2,32}
  */
@@ -64,9 +64,13 @@ public:
   // Ignore varargs function.
   _IGNORE(g_menu_item_get_attribute)
  
-  //TODO: Documentation:
+  //TODO: Rename this to unset_action_target() and deprecate this one.
+  /** Unsets the target for the specified @a action.
+   */
   void set_action_and_target(const Glib::ustring& action);
 
+  //TODO: Add unset_action_and_target().
+
   _WRAP_METHOD(void set_action_and_target(const Glib::ustring& action, const Glib::VariantBase& target_value), g_menu_item_set_action_and_target_value)
   _IGNORE(g_menu_item_set_action_and_target)
   _WRAP_METHOD(void set_detailed_action(const Glib::ustring& detailed_action), g_menu_item_set_detailed_action)
diff --git a/gio/src/outputstream.hg b/gio/src/outputstream.hg
index bcda7c9c..fbfc6f15 100644
--- a/gio/src/outputstream.hg
+++ b/gio/src/outputstream.hg
@@ -128,13 +128,71 @@ public:
 
   _WRAP_METHOD(gssize write_bytes(const Glib::RefPtr<const Glib::Bytes>& bytes, const Glib::RefPtr<Cancellable>& cancellable{?}), g_output_stream_write_bytes, errthrow)
 
-  //TODO: Documentation.
-  /**
+  /** Request an asynchronous write of the data in @a bytes to the stream.
+   * When the operation is finished @a slot will be called. You can
+   * then call write_bytes_finish() to get the result of
+   * the operation.
+   *
+   * During an async request no other sync and async calls are allowed, 
+   * and will result in Gio::Error with PENDING being thrown. 
+   *
+   * A Glib:Bytes larger than MAXSSIZE will cause a Gio::Error with  
+   * INVALID_ARGUMENT to be thrown.
+   * 
+   * On success, the number of bytes written will be passed to the
+   * callback @a slot. It is not an error if this is not the same as the
+   * requested size, as it can happen e.g. on a partial I/O error,
+   * but generally we try to write as many bytes as requested.
+   *
+   * You are guaranteed that this method will never fail with
+   * IO_ERROR_WOULD_BLOCK - if the stream can't accept more data, the
+   * method will just wait until this changes.
+   *
+   * Any outstanding I/O request with higher priority (lower numerical 
+   * value) will be executed before an outstanding request with lower 
+   * priority. Default priority is Glib::PRIORITY_DEFAULT.
+   * 
+   * For the synchronous, blocking version of this function, see write_bytes().
+   *
+   * @param bytes The bytes to 
+   * @param slot Callback slot to call when the request is satisfied.
+   * @param cancellable Cancellable object.
+   * @param io_priority The io priority of the request.
+   *
    * @newin{2,34}
    */
   void write_bytes_async(const Glib::RefPtr<const Glib::Bytes>& bytes, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = Glib::PRIORITY_DEFAULT);
 
-  /**
+  /** Request an asynchronous write of the data in @a bytes to the stream.
+   * When the operation is finished @a slot will be called. You can
+   * then call write_bytes_finish() to get the result of
+   * the operation.
+   *
+   * During an async request no other sync and async calls are allowed, 
+   * and will result in Gio::Error with PENDING being thrown. 
+   *
+   * A Glib:Bytes larger than MAXSSIZE will cause a Gio::Error with  
+   * INVALID_ARGUMENT to be thrown.
+   * 
+   * On success, the number of bytes written will be passed to the
+   * callback @a slot. It is not an error if this is not the same as the
+   * requested size, as it can happen e.g. on a partial I/O error,
+   * but generally we try to write as many bytes as requested.
+   *
+   * You are guaranteed that this method will never fail with
+   * IO_ERROR_WOULD_BLOCK - if the stream can't accept more data, the
+   * method will just wait until this changes.
+   *
+   * Any outstanding I/O request with higher priority (lower numerical 
+   * value) will be executed before an outstanding request with lower 
+   * priority. Default priority is Glib::PRIORITY_DEFAULT.
+   * 
+   * For the synchronous, blocking version of this function, see write_bytes().
+   *
+   * @param bytes The bytes to 
+   * @param slot Callback slot to call when the request is satisfied.
+   * @param io_priority The io priority of the request.
+   *
    * @newin{2,34}
    */
   void write_bytes_async(const Glib::RefPtr<const Glib::Bytes>& bytes, const SlotAsyncReady& slot, int io_priority = Glib::PRIORITY_DEFAULT);
@@ -179,7 +237,7 @@ public:
    * and will result in Gio::Error with PENDING being thrown. 
    *
    * A value of @a count larger than MAXSSIZE will cause a Gio::Error with  
-   * NVALID_ARGUMENT to be thrown.
+   * INVALID_ARGUMENT to be thrown.
    *
    * On success, the number of bytes written will be passed to the
    * callback @a slot. It is not an error if this is not the same as the 
diff --git a/glib/src/threads.hg b/glib/src/threads.hg
index 89b8131d..10ef5ddf 100644
--- a/glib/src/threads.hg
+++ b/glib/src/threads.hg
@@ -234,7 +234,12 @@ private:
  */
 Mutex* wrap(GMutex* gobject);
 
-//TODO: Documentation
+/** This represents a recursive mutex.
+ * It is similar to a Mutex with the difference
+ * that it is possible to lock a RecMutex multiple times in the same
+ * thread without deadlock. When doing so, care has to be taken to
+ * unlock the recursive mutex as often as it has been locked.
+ */
 class RecMutex
 {
 public:
@@ -296,7 +301,17 @@ private:
  */
 RecMutex* wrap(GRecMutex* gobject);
 
-//TODO: Documentation
+/** This represents a reader-writer lock.
+ * It is similar to a Mutex in that it allows
+ * multiple threads to coordinate access to a shared resource.
+ *
+ * The difference to a mutex is that a reader-writer lock discriminates
+ * between read-only ('reader') and full ('writer') access. While only
+ * one thread at a time is allowed write access (by holding the 'writer'
+ * lock via writer_lock()), multiple threads can gain
+ * simultaneous read-only access (by holding the 'reader' lock via
+ * reader_lock()).
+ */
 class RWLock
 {
 public: