Dealt with several TODOs.

* gio/src/*.[hg|ccg]: Mostly just adding hand-coded documentation,
and changing some new methods to use std::vector.

31 files changed, 391 insertions, 93 deletions

diff --git a/ChangeLog b/ChangeLog
index 4f146ec3..e2243aea 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,12 @@
 2011-02-15  Murray Cumming  <murrayc@murrayc.com>
 
+	Dealt with several TODOs.
+
+	* gio/src/*.[hg|ccg]: Mostly just adding hand-coded documentation,
+	and changing some new methods to use std::vector.
+
+2011-02-15  Murray Cumming  <murrayc@murrayc.com>
+
 	Update the .defs for signals and properties.
 
 	* tools/extra_defs_gen/generate_defs_gio.cc: Mention more GDbus types.
diff --git a/gio/src/actiongroup.hg b/gio/src/actiongroup.hg
index 33756288..8ff29e91 100644
--- a/gio/src/actiongroup.hg
+++ b/gio/src/actiongroup.hg
@@ -53,9 +53,8 @@ class ActionGroup : public Glib::Interface
 public:
   _WRAP_METHOD(bool has_action(const Glib::ustring& action_name) const, g_action_group_has_action)
 
-  //TODO: Use a vector instead, for this new API, before we free glibmm 2.28.
-#m4 _CONVERSION(`gchar**', `Glib::StringArrayHandle', `Glib::StringArrayHandle($3, Glib::OWNERSHIP_DEEP)')
-  _WRAP_METHOD(Glib::StringArrayHandle list_actions() const, g_action_group_list_actions)
+#m4 _CONVERSION(`gchar**',`std::vector<Glib::ustring>',`Glib::ArrayHandler<Glib::ustring>::array_to_vector($3, Glib::OWNERSHIP_DEEP)')
+  _WRAP_METHOD(std::vector<Glib::ustring> list_actions() const, g_action_group_list_actions)
 
   _WRAP_METHOD(bool get_action_enabled(const Glib::ustring& action_name) const, g_action_group_get_action_enabled)
 
diff --git a/gio/src/application.ccg b/gio/src/application.ccg
index 3b72e429..9f0a4100 100644
--- a/gio/src/application.ccg
+++ b/gio/src/application.ccg
@@ -179,34 +179,19 @@ void Gio::Application::on_open(const Application::type_vec_files& files, const G
   );
 
   if(base && base->open) {
-    typedef GFile* cpointer;
-    cpointer* files_array = new cpointer[files.size()];
-    guint i = 0;
-    for(Application::type_vec_files::const_iterator iter = files.begin(); iter != files.end(); iter++)
-      {
-        Application::type_vec_files::const_reference refPtr = *iter;
-        files_array[i] = refPtr->gobj();
-      }
-
-    (*base->open)(gobj(), files_array, files.size(), hint.c_str());
+    (*base->open)(gobj(), 
+      Glib::ArrayHandler<type_vec_files::value_type>::vector_to_array(files).data(),
+      files.size(),
+      hint.c_str());
   }
 }
 
 void Application::open(const type_vec_files& files, const Glib::ustring& hint)
 {
-  //TODO: Create a templated helper function for this:
-  typedef GFile* cpointer;
-  cpointer* files_array = new cpointer[files.size()];
-  guint i = 0;
-  for(type_vec_files::const_iterator iter = files.begin(); iter != files.end(); iter++)
-  {
-    type_vec_files::const_reference refPtr = *iter;
-    files_array[i] = refPtr->gobj();
-  }
-
-  g_application_open(gobj(), files_array, files.size(), hint.c_str());
-
-  delete[] files_array ;
+  g_application_open(gobj(), 
+    Glib::ArrayHandler<type_vec_files::value_type>::vector_to_array(files).data(),
+    files.size(),
+    hint.c_str());
 }
 
 bool Application::register_application()
diff --git a/gio/src/application.hg b/gio/src/application.hg
index abd4b767..bcbd1dad 100644
--- a/gio/src/application.hg
+++ b/gio/src/application.hg
@@ -135,6 +135,7 @@ public:
    * @newin{2,28}
    */
   void open(const type_vec_files& files, const Glib::ustring& hint = Glib::ustring());
+  _IGNORE(g_application_open)
 
   _WRAP_METHOD(int run(int argc, char** argv), g_application_run)
   //TODO: g_application_run_with_arguments)
diff --git a/gio/src/applicationcommandline.hg b/gio/src/applicationcommandline.hg
index f840536b..8d67ab58 100644
--- a/gio/src/applicationcommandline.hg
+++ b/gio/src/applicationcommandline.hg
@@ -43,11 +43,21 @@ public:
   _WRAP_METHOD(void set_exit_status(int exit_status), g_application_command_line_set_exit_status)
   _WRAP_METHOD(int get_exit_status() const, g_application_command_line_get_exit_status)
   
-  //TODO: Documentation
+  /** Formats a message and prints it using the stdout print handler in the invoking process.
+   * If this is a local invocation then this is exactly equivalent to g_print().
+   *  If this is remote then this is equivalent to calling g_print() in the invoking process.
+   *
+   * @param message The text to print.
+   */
   void print(const Glib::ustring& message);
   _IGNORE(g_application_command_line_print)
   
-  //TODO: Documentation
+  /** Formats a message and prints it using the stderr print handler in the invoking process.
+   * If this is a local invocation then this is exactly equivalent to g_printerr().
+   *  If this is remote then this is equivalent to calling g_printerr() in the invoking process.
+   *
+   * @param message The text to print.
+   */
   void printerr(const Glib::ustring& message);
   _IGNORE(g_application_command_line_printerr)
 };
diff --git a/gio/src/bufferedinputstream.hg b/gio/src/bufferedinputstream.hg
index f8b07b83..598053c4 100644
--- a/gio/src/bufferedinputstream.hg
+++ b/gio/src/bufferedinputstream.hg
@@ -52,9 +52,19 @@ protected:
   _WRAP_CTOR(BufferedInputStream(const Glib::RefPtr<InputStream>& base_stream, gsize buffer_size), g_buffered_input_stream_new_sized)
 
 public:
+  /** Creates a new InputStream from the given base_stream, with a buffer set to the default size (4 kilobytes). 
+   *
+   * @param base_stream An InputStream.
+   * @result an InputStream for the given base_stream.
+	 */
   _WRAP_CREATE(const Glib::RefPtr<InputStream>& base_stream)
   
-  //TODO: Documentation
+  /** Creates a new InputStream from the given base_stream, with a buffer set to size.
+   *
+   * @param base_stream An InputStream.
+   * @param size A size.
+   * @result an InputStream for the given base_stream.
+	 */
   static Glib::RefPtr<BufferedInputStream> create_sized(const Glib::RefPtr<InputStream>& base_stream, gsize buffer_size);
 
   _WRAP_METHOD(gsize get_buffer_size() const, g_buffered_input_stream_get_buffer_size)
diff --git a/gio/src/bufferedoutputstream.hg b/gio/src/bufferedoutputstream.hg
index f561c82a..3a1ecca7 100644
--- a/gio/src/bufferedoutputstream.hg
+++ b/gio/src/bufferedoutputstream.hg
@@ -48,9 +48,19 @@ protected:
   _WRAP_CTOR(BufferedOutputStream(const Glib::RefPtr<OutputStream>& base_stream, gsize buffer_size), g_buffered_output_stream_new_sized)
 
 public:
+  /** Creates a new buffered output stream for a base stream.
+   *
+   * @param base_stream An InputStream.
+   * @result an OutputStream for the given base stream.
+	 */
   _WRAP_CREATE(const Glib::RefPtr<OutputStream>& base_stream)
   
-  //TODO: Documentation
+  /** Creates a new buffered output stream with a given buffer size. 
+   *
+   * @param base_stream An InputStream.
+   * @param size A size.
+   * @result an OutputStream with an internal buffer set to size. 
+	 */
   static Glib::RefPtr<BufferedOutputStream> create_sized(const Glib::RefPtr<OutputStream>& base_stream, gsize buffer_size);
 
   _WRAP_METHOD(gsize get_buffer_size() const, g_buffered_output_stream_get_buffer_size)
diff --git a/gio/src/datainputstream.hg b/gio/src/datainputstream.hg
index a2e966f0..023e4967 100644
--- a/gio/src/datainputstream.hg
+++ b/gio/src/datainputstream.hg
@@ -172,7 +172,7 @@ public:
    */
   bool read_until(std::string& data, const std::string& stop_chars);
 
-  //TODO: This will be really deprecated sometime, maybe even before glib 2.28.0.
+  //TODO: This will be really deprecated sometime after glib 2.28.0.
   /** The asynchronous version of read_until(). It is
    * an error to have two outstanding calls to this function.
    *
@@ -195,7 +195,7 @@ public:
   void read_until_async(const std::string& stop_chars, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable, int io_priority = Glib::PRIORITY_DEFAULT);
   _IGNORE(g_data_input_stream_read_until_async)
 
-  //TODO: This will be really deprecated sometime, maybe even before glib 2.28.0.
+  //TODO: This will be really deprecated sometime after glib 2.28.0.
   /** Finish an asynchronous call started by read_until_async().
    *
    * @param result The AsyncResult that was provided to the callback slot.
diff --git a/gio/src/dbusmessage.hg b/gio/src/dbusmessage.hg
index 25afc3b1..ba114280 100644
--- a/gio/src/dbusmessage.hg
+++ b/gio/src/dbusmessage.hg
@@ -53,9 +53,9 @@ public:
   _WRAP_METHOD_DOCS_ONLY(g_dbus_message_new)
   _WRAP_CREATE()
 
-  // TODO: We can't use _WRAP_CTOR() and _WRAP_CREATE() because the C functions do more than just call g_object_new():
-  // http://bugzilla.gnome.org/show_bug.cgi?id=624977
-  // TODO: Should these paramters be ustring or std::string?
+  // Note that we can't use _WRAP_CTOR() and _WRAP_CREATE() because the C functions do more than just call g_object_new():
+  // See http://bugzilla.gnome.org/show_bug.cgi?id=624977
+  // TODO: Should these parameters be ustring or std::string?
   _WRAP_METHOD(static Glib::RefPtr<DBusMessage> create_signal(const Glib::ustring& path, const Glib::ustring& interface, const Glib::ustring& signal), g_dbus_message_new_signal)
   _WRAP_METHOD(static Glib::RefPtr<DBusMessage> create_method_call(const Glib::ustring& name, const Glib::ustring& path, const Glib::ustring& interface, const Glib::ustring& method), g_dbus_message_new_method_call)
   _WRAP_METHOD(static Glib::RefPtr<DBusMessage> create_method_reply(const Glib::RefPtr<DBusMessage>& method_call_message), g_dbus_message_new_method_reply)
diff --git a/gio/src/dbusserver.hg b/gio/src/dbusserver.hg
index 813e0209..d9e1e9c9 100644
--- a/gio/src/dbusserver.hg
+++ b/gio/src/dbusserver.hg
@@ -47,7 +47,7 @@ class DBusServer : public Glib::Object, public Initable
 
 protected:
 
-//TODO: Uncomment when bug #639478 is resolved.
+//TODO: Uncomment when this bug is resolved: https://bugzilla.gnome.org/show_bug.cgi?id=639478
 /*
   DBusServer(const std::string& address,
     const std::string& guid,
diff --git a/gio/src/desktopappinfo.hg b/gio/src/desktopappinfo.hg
index ed0ec90c..c57c03f5 100644
--- a/gio/src/desktopappinfo.hg
+++ b/gio/src/desktopappinfo.hg
@@ -41,7 +41,7 @@ class DesktopAppInfo
 
 public:
   // TODO: should use _WRAP_CREATE(), but these functions do more than just call
-  // g_object_new() because there's quite a bit of error-handling to do
+  // g_object_new() because there's quite a bit of error-handling to do.
   _WRAP_METHOD(static Glib::RefPtr<DesktopAppInfo> create(const std::string& desktop_id), g_desktop_app_info_new)
   _WRAP_METHOD(static Glib::RefPtr<DesktopAppInfo> create_from_keyfile(Glib::KeyFile& key_file), g_desktop_app_info_new_from_keyfile)
   _WRAP_METHOD(static Glib::RefPtr<DesktopAppInfo> create_from_filename(const std::string& filename), g_desktop_app_info_new_from_filename)
diff --git a/gio/src/emblem.hg b/gio/src/emblem.hg
index 3b093b62..3b0fa37f 100644
--- a/gio/src/emblem.hg
+++ b/gio/src/emblem.hg
@@ -47,12 +47,27 @@ class Emblem
   _IMPLEMENTS_INTERFACE(Icon)
 
 protected:
-  //TODO: Documentation:
+  /** Creates a new emblem for @a icon.
+   * @param icon A Gio::Icon containing the icon.
+   */
  _WRAP_CTOR(Emblem(const Glib::RefPtr<Icon>& icon), g_emblem_new)
+
+  /** Creates a new emblem for @a icon.
+   * @param icon A Gio::Icon containing the icon.
+   * @param origin An EmblemOrigin value defining the emblem's origin
+   */
  _WRAP_CTOR(Emblem(const Glib::RefPtr<Icon>& icon, EmblemOrigin origin), g_emblem_new_with_origin)
 
 public:
+  /** Creates a new emblem for @a icon.
+   * @param icon A Gio::Icon containing the icon.
+   */
   _WRAP_CREATE(const Glib::RefPtr<Icon>& icon)
+
+  /** Creates a new emblem for @a icon.
+   * @param icon A Gio::Icon containing the icon.
+   * @param origin An EmblemOrigin value defining the emblem's origin
+   */
   _WRAP_CREATE(const Glib::RefPtr<Icon>& icon, EmblemOrigin origin)
 
   _WRAP_METHOD(Glib::RefPtr<Icon> get_icon(), g_emblem_get_icon)
diff --git a/gio/src/emblemedicon.ccg b/gio/src/emblemedicon.ccg
index c146baae..695e1d50 100644
--- a/gio/src/emblemedicon.ccg
+++ b/gio/src/emblemedicon.ccg
@@ -22,4 +22,10 @@
 namespace Gio
 {
 
+EmblemedIcon::EmblemedIcon(const Glib::RefPtr<Icon>& icon)
+:
+  _CONSTRUCT("icon", Glib::unwrap(icon))
+{
+}
+
 } //namespace Gio
diff --git a/gio/src/emblemedicon.hg b/gio/src/emblemedicon.hg
index 86a732c7..de0033bf 100644
--- a/gio/src/emblemedicon.hg
+++ b/gio/src/emblemedicon.hg
@@ -45,12 +45,39 @@ class EmblemedIcon
   _IMPLEMENTS_INTERFACE(Icon)
 
 protected:
-  //TODO: Documentation:
+  //We have this constructor because g_emblemed_icon_new() may take a NULL emblem parameter.
+ /** Creates a new emblemed icon for @a icon with the emblem @a emblem.
+   * @param icon An Icon.
+   * @param emblem An Emblem.
+   *
+   * @newin{2,28}
+   */
+  explicit EmblemedIcon(const Glib::RefPtr<Icon>& icon);
+
+  /** Creates a new emblemed icon for @a icon with the emblem @a emblem.
+   * @param icon An Icon.
+   * @param emblem An Emblem.
+   */
  _WRAP_CTOR(EmblemedIcon(const Glib::RefPtr<Icon>& icon, const Glib::RefPtr<Emblem>& emblem), g_emblemed_icon_new)
 
 public:
+
+  /** Creates a new emblemed icon for @a icon with the emblem @a emblem.
+   * @param icon An Icon.
+   * @param emblem An Emblem.
+   * @result An Icon.
+   */
   _WRAP_CREATE(const Glib::RefPtr<Icon>& icon, const Glib::RefPtr<Emblem>& emblem)
 
+  /** Creates a new emblemed icon for @a icon with no emblem.
+   * @param icon An Icon.
+   * @result An Icon.
+   *
+   * @newin{2,28}
+   */
+  _WRAP_CREATE(const Glib::RefPtr<Icon>& icon)
+
+
   _WRAP_METHOD(Glib::RefPtr<Icon> get_icon(), g_emblemed_icon_get_icon)
   _WRAP_METHOD(Glib::RefPtr<const Icon> get_icon() const, g_emblemed_icon_get_icon, constversion)
 #m4 _CONVERSION(`GList*',`Glib::ListHandle<Glib::RefPtr<Emblem> >',`$2($3, Glib::OWNERSHIP_NONE)')
diff --git a/gio/src/file.hg b/gio/src/file.hg
index b6131b1e..0000e4ae 100644
--- a/gio/src/file.hg
+++ b/gio/src/file.hg
@@ -1122,12 +1122,20 @@ public:
                g_file_set_display_name_finish,
                errthrow)
 
-  //TODO: remember to add the docs manually, as we name the method differently.
+  /** Deletes a file. 
+   * If the file is a directory, it will only be deleted if it is empty.
+   * The operation can be cancelled by triggering the cancellable object from another thread. 
+   * If the operation was cancelled, a Glib::FileError with ERROR_CANCELLED will be thrown.
+   *
+   * @param cancellable A Cancellable object which can be used to cancel the operation.
+   * @return <tt>true</tt> if the file was deleted. <tt>false</tt> otherwise.
+   */
    _WRAP_METHOD(bool remove(const Glib::RefPtr<Cancellable>& cancellable),
                 g_file_delete,
                 errthrow)
 
   /** Deletes a file.
+   * If the file is a directory, it will only be deleted if it is empty.
    * 
    * @return <tt>true</tt> if the file was deleted. <tt>false</tt> otherwise.
    */
@@ -1174,9 +1182,42 @@ public:
    */
   bool copy(const Glib::RefPtr<File>& destination, const SlotFileProgress& slot, const Glib::RefPtr<Cancellable>& cancellable, FileCopyFlags flags = FILE_COPY_NONE);
 
-  //TODO: Documentation.
+  /** Copies the file source to the location specified by destination. Can not handle recursive copies of directories.
+   * If the flag FILE_COPY_OVERWRITE is specified an already existing destination file is overwritten.
+   * If the flag FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks will be copied as symlinks, otherwise the target of the source symlink will be copied.
+   *
+   * The operation can be monitored via the @a slot callback.
+   *
+   * If the source file does not exist then a Gio::Error with NOT_FOUND will be thrown, independent on the status of the destination.
+   *
+   * If FILE_COPY_OVERWRITE is not specified and the target exists, then a Gio::Error with EXISTS will be thrown.
+   *
+   * If trying to overwrite a file over a directory a Gio::Error with IS_DIRECTORY will be thrown. 
+   * If trying to overwrite a directory with a directory a Gio::Error with WOULD_MERGE will be thrown.
+   *
+   * If the source is a directory and the target does not exist, or FILE_COPY_OVERWRITE is specified and the target is a file, 
+   * then a Gio::Error with WOULD_RECURSE will be thrown.
+   *
+   * If you are interested in copying the Gio::File object itself (not the on-disk file), see File::dup().
+   */
   bool copy(const Glib::RefPtr<File>& destination, const SlotFileProgress& slot, FileCopyFlags flags = FILE_COPY_NONE);
 
+  /** Copies the file source to the location specified by destination. Can not handle recursive copies of directories.
+   * If the flag FILE_COPY_OVERWRITE is specified an already existing destination file is overwritten.
+   * If the flag FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks will be copied as symlinks, otherwise the target of the source symlink will be copied.
+   *
+   * If the source file does not exist then a Gio::Error with NOT_FOUND will be thrown, independent on the status of the destination.
+   *
+   * If FILE_COPY_OVERWRITE is not specified and the target exists, then a Gio::Error with EXISTS will be thrown.
+   *
+   * If trying to overwrite a file over a directory a Gio::Error with IS_DIRECTORY will be thrown. 
+   * If trying to overwrite a directory with a directory a Gio::Error with WOULD_MERGE will be thrown.
+   *
+   * If the source is a directory and the target does not exist, or FILE_COPY_OVERWRITE is specified and the target is a file, 
+   * then a Gio::Error with WOULD_RECURSE will be thrown.
+   *
+   * If you are interested in copying the Gio::File object itself (not the on-disk file), see File::dup().
+   */
   bool copy(const Glib::RefPtr<File>& destination, FileCopyFlags flags = FILE_COPY_NONE);
   _IGNORE(g_file_copy)
 
@@ -1997,6 +2038,7 @@ public:
    * @param etag_out A location to place the current entity tag for the file.
    */
   bool load_contents(const Glib::RefPtr<Cancellable>& cancellable, char*& contents, gsize& length, std::string& etag_out);
+
   /** Loads the content of the file into memory, returning the size of the data. 
    * The data is always zero terminated, but this is not included in the resultant @a length.
    * 
@@ -2009,6 +2051,7 @@ public:
    * @newin{2,22}
    */
   bool load_contents(const Glib::RefPtr<Cancellable>& cancellable, char*& contents, gsize& length);
+
   //TODO: Something better than char*& for contents?
   /** Loads the content of the file into memory, returning the size of the data. 
    * The data is always zero terminated, but this is not included in the resultant @a length.
@@ -2018,6 +2061,7 @@ public:
    * @param etag_out A location to place the current entity tag for the file.
    */
   bool load_contents(char*& contents, gsize& length, std::string& etag_out);
+
   /** Loads the content of the file into memory, returning the size of the data. 
    * The data is always zero terminated, but this is not included in the resultant @a length.
    *
diff --git a/gio/src/filterinputstream.hg b/gio/src/filterinputstream.hg
index c975c642..db2050b4 100644
--- a/gio/src/filterinputstream.hg
+++ b/gio/src/filterinputstream.hg
@@ -26,9 +26,9 @@ _PINCLUDE(giomm/private/inputstream_p.h)
 namespace Gio
 {
 
-//TODO: Proper documentation.
-
 /** Filter Input Stream.
+ * This is a base class for input stream implementations that perform some kind of filtering operation on a base stream. 
+ & Typical examples of filtering operations are character set conversion, compression and byte order flipping. 
  *
  * @ingroup Streams
  *
diff --git a/gio/src/filteroutputstream.hg b/gio/src/filteroutputstream.hg
index d6137f9c..bb8d3cbf 100644
--- a/gio/src/filteroutputstream.hg
+++ b/gio/src/filteroutputstream.hg
@@ -26,10 +26,11 @@ _PINCLUDE(giomm/private/outputstream_p.h)
 namespace Gio
 {
 
-//TODO: Proper documentation:
-
 /** Filter Output Stream.
  *
+ * This is a base class for output stream implementations that perform some kind of filtering operation on a base stream. 
+ * Typical examples of filtering operations are character set conversion, compression and byte order flipping. 
+ *
  * @ingroup Streams
  *
  * @newin{2,16}
diff --git a/gio/src/memoryoutputstream.hg b/gio/src/memoryoutputstream.hg
index dda03766..d44aa463 100644
--- a/gio/src/memoryoutputstream.hg
+++ b/gio/src/memoryoutputstream.hg
@@ -29,10 +29,10 @@ _PINCLUDE(giomm/private/outputstream_p.h)
 namespace Gio
 {
 
-//TODO: Proper documentation:
-
 /** Streaming output operations on memory chunks
  *
+ * This class uses arbitrary memory chunks as output for GIO streaming output operations. 
+ *
  * @ingroup Streams
  *
  * @newin{2,20}
diff --git a/gio/src/proxy.hg b/gio/src/proxy.hg
index 12ac8a87..d31d9556 100644
--- a/gio/src/proxy.hg
+++ b/gio/src/proxy.hg
@@ -56,10 +56,12 @@ public:
   _WRAP_METHOD(Glib::RefPtr<IOStream> connect(const Glib::RefPtr<IOStream>& connection,
     const Glib::RefPtr<const ProxyAddress>& proxy_adress, const Glib::RefPtr<Cancellable>& cancellable), g_proxy_connect, errthrow)
 
-  //TODO: Documentation
+  /** An Asynchronous version of connect().
+   */
   void connect_async(const Glib::RefPtr<IOStream>& connection, const Glib::RefPtr<const ProxyAddress>& proxy_address, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
  
-  //TODO: Documentation 
+  /** An Asynchronous version of connect().
+   */
   void connect_async(const Glib::RefPtr<IOStream>& connection, const Glib::RefPtr<const ProxyAddress>& proxy_address, const SlotAsyncReady& slot);
   _IGNORE(g_proxy_connect_async)
 
diff --git a/gio/src/proxyresolver.ccg b/gio/src/proxyresolver.ccg
index d34fdcd3..ae517467 100644
--- a/gio/src/proxyresolver.ccg
+++ b/gio/src/proxyresolver.ccg
@@ -26,10 +26,11 @@
 namespace Gio
 {
 
-Glib::StringArrayHandle ProxyResolver::lookup(const Glib::ustring& uri)
+std::vector<Glib::ustring> ProxyResolver::lookup(const Glib::ustring& uri)
 {
   GError* gerror = 0;
-  Glib::StringArrayHandle retvalue = Glib::StringArrayHandle(g_proxy_resolver_lookup(gobj(), uri.c_str(), 0, &(gerror)), Glib::OWNERSHIP_DEEP);
+  std::vector<Glib::ustring> retvalue =
+    Glib::ArrayHandler<Glib::ustring>::array_to_vector(g_proxy_resolver_lookup(gobj(), uri.c_str(), 0, &(gerror)), Glib::OWNERSHIP_DEEP);
   if(gerror)
     ::Glib::Error::throw_exception(gerror);
 
diff --git a/gio/src/proxyresolver.hg b/gio/src/proxyresolver.hg
index 387e8137..df90c019 100644
--- a/gio/src/proxyresolver.hg
+++ b/gio/src/proxyresolver.hg
@@ -52,22 +52,38 @@ public:
   _WRAP_METHOD(bool is_supported() const, g_proxy_resolver_is_supported)
 
   //TODO: Use std::string instead of ustring (StringArrayHandle uses ustring)?:
-#m4 _CONVERSION(`gchar**',`Glib::StringArrayHandle',`Glib::StringArrayHandle($3, Glib::OWNERSHIP_DEEP)')
-  _WRAP_METHOD(Glib::StringArrayHandle lookup(const Glib::ustring& uri,
+#m4 _CONVERSION(`gchar**',`std::vector<Glib::ustring>',`Glib::ArrayHandler<Glib::ustring>::array_to_vector($3, Glib::OWNERSHIP_DEEP)')
+  _WRAP_METHOD(std::vector<Glib::ustring> lookup(const Glib::ustring& uri,
 						 const Glib::RefPtr<Cancellable>& cancellable), g_proxy_resolver_lookup, errthrow)
 	
-	//TODO: Documentation
-	Glib::StringArrayHandle lookup(const Glib::ustring& uri);
+  /** Looks into the system proxy configuration to determine what proxy, if any, to use to connect to uri. 
+   * The returned proxy URIs are of the form <protocol>://[user[:password]@]host:port or direct://, where <protocol> could be http, rtsp, socks or other proxying protocol.
+   *
+   * If you don't know what network protocol is being used on the socket, you should use none as the URI protocol. 
+   * In this case, the resolver might still return a generic proxy type (such as SOCKS), but would not return protocol-specific proxy types (such as http).
+   *
+   * direct:// is used when no proxy is needed. Direct connection should not be attempted unless it is part of the returned array of proxies.
+   *
+   * @param uri a URI representing the destination to connect to. 
+   */
+  std::vector<Glib::ustring> lookup(const Glib::ustring& uri);
 						 
-  //TODO: Documentation
+  /** Asynchronous lookup of proxy. See lookup() for more details. 
+   * @param uri a URI representing the destination to connect to. 
+   * @param slot A callback slot to call after the resolution completes.
+   * @param cancellable A Cancellable object which can be used to cancel the operation.
+   */
   void lookup_async(const Glib::ustring& uri, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
  
-  //TODO: Documentation 
+  /** Asynchronous lookup of proxy. See lookup() for more details.
+   * @param uri a URI representing the destination to connect to. 
+   * @param slot A callback slot to call after the resolution completes.
+   */
   void lookup_async(const Glib::ustring& uri, const SlotAsyncReady& slot);
 
   _IGNORE(g_proxy_resolver_lookup_async)
 
-  _WRAP_METHOD(Glib::StringArrayHandle lookup_finish(const Glib::RefPtr<AsyncResult>& result), g_proxy_resolver_lookup_finish, errthrow)
+  _WRAP_METHOD(std::vector<Glib::ustring> lookup_finish(const Glib::RefPtr<AsyncResult>& result), g_proxy_resolver_lookup_finish, errthrow)
 
 };
 
diff --git a/gio/src/resolver.hg b/gio/src/resolver.hg
index 589c7a21..61cc6428 100644
--- a/gio/src/resolver.hg
+++ b/gio/src/resolver.hg
@@ -61,13 +61,34 @@ public:
 #m4 _CONVERSION(`GList*',`Glib::ListHandle< Glib::RefPtr<InetAddress> >',`$2($3, Glib::OWNERSHIP_DEEP)')
   _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<InetAddress> > lookup_by_name(const Glib::ustring& hostname, const Glib::RefPtr<Cancellable>& cancellable), g_resolver_lookup_by_name, errthrow)
   
-  //TODO: Documentation
+  /** Synchronously resolves hostname to determine its associated IP address(es). 
+   * @a hostname may be an ASCII-only or UTF-8 hostname, or the textual form of an IP address (in which case this just becomes a wrapper around InetAddress:create_from_string()).
+   *
+   * On success, this will return a list of InetAddress, sorted in order of preference. (That is, you should attempt to connect to the first address first, then the second if the first fails, etc.)
+   *
+   * If the DNS resolution fails, a ResolverError exception will be thrown.
+   *
+   * If you are planning to connect to a socket on the resolved IP address, it may be easier to create a NetworkAddress and use its SocketConnectable base class.
+   *
+   * @param hostname hostname The hostname to look up.
+   */
   Glib::ListHandle< Glib::RefPtr<InetAddress> > lookup_by_name(const Glib::ustring& hostname);
   
-  //TODO: Documentation
+  /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call 
+   * lookup_by_name_finish() to get the result. See lookup_by_name() for more details.
+   *
+   * @param hostname hostname The hostname to look up.
+   * @param slot A callback slot to call after the resolution completes.
+   * @param cancellable A Cancellable object which can be used to cancel the operation.
+   */
   void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
   
-  //TODO: Documentation
+  /** Begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls @a slot, which must call 
+   * lookup_by_name_finish() to get the result. See lookup_by_name() for more details.
+   *
+   * @param hostname hostname The hostname to look up.
+   * @param slot A callback slot to call after the resolution completes.
+   */
   void lookup_by_name_async(const Glib::ustring& hostname, const SlotAsyncReady& slot);
   _IGNORE(g_resolver_lookup_by_name_async)
   
@@ -75,11 +96,32 @@ public:
 
   _WRAP_METHOD(Glib::ustring lookup_by_address(const Glib::RefPtr<InetAddress>& address, const Glib::RefPtr<Cancellable>& cancellable), g_resolver_lookup_by_address, errthrow)
   
-  //TODO: Documentation
+  /** Synchronously reverse-resolves an address to determine its associated hostname.
+   *
+   * If the DNS resolution fails then a ResolverError exception will be thrown.
+   *
+   * @param address The address to reverse-resolve.
+   * @result A hostname (either ASCII-only, or in ASCII-encoded form), or an empty string on error. 
+   */
   Glib::ustring lookup_by_address(const Glib::RefPtr<InetAddress>& address);
+
+  /** Begins asynchronously reverse-resolving an address to determine its associated hostname, and eventually calls callback, which must call 
+   * lookup_by_address_finish() to get the final result.
+   *
+   * @param address The address to reverse-resolve.
+   * @param hostname hostname The hostname to look up.
+   * @param slot A callback slot to call after the resolution completes.
+   * @param cancellable A Cancellable object which can be used to cancel the operation.
+   */
   void lookup_by_address_async(const Glib::RefPtr<InetAddress>& address, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
   
-  //TODO: Documentation
+  /** Begins asynchronously reverse-resolving an address to determine its associated hostname, and eventually calls callback, which must call 
+   * lookup_by_address_finish() to get the final result.
+   *
+   * @param address The address to reverse-resolve.
+   * @param hostname hostname The hostname to look up.
+   * @param slot A callback slot to call after the resolution completes.
+   */
   void lookup_by_address_async(const Glib::RefPtr<InetAddress>& address, const SlotAsyncReady& slot);
   _IGNORE(g_resolver_lookup_by_address_async)
   
@@ -88,13 +130,41 @@ public:
 #m4 _CONVERSION(`GList*',`ListHandle_SrvTarget',`$2($3, Glib::OWNERSHIP_DEEP)')
   _WRAP_METHOD(ListHandle_SrvTarget lookup_service(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const Glib::RefPtr<Cancellable>& cancellable), g_resolver_lookup_service, errthrow)
 
-  //TODO: Documentation
+  /** Synchronously performs a DNS SRV lookup for the given service and protocol in the given domain and returns an list of SrvTargets.
+   * @a domain may be an ASCII-only or UTF-8 hostname. Note also that the service and protocol arguments do not include the leading underscore that appears in the actual DNS entry.
+   *
+   * On success, this will return a list of SrvTargets, sorted in order of preference. 
+   * (That is, you should attempt to connect to the first target first, then the second if the first fails, etc.)
+   *
+   * If the DNS resolution fails a ResolverError exception will be thrown.
+   *
+   * If you are planning to connect to the service, it is usually easier to create a NetworkService and use its SocketConnectable base class interface. \
+   *
+   * @param service The service type to look up (eg, "ldap").
+   * @param protocol The networking protocol to use for service (eg, "tcp") 
+   * @param domain The DNS domain to look up the service in.
+   */
   ListHandle_SrvTarget lookup_service(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain);
   
-  //TODO: Documentation
+  /** Begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback, 
+   * which must call lookup_service_finish() to get the final result. See glookup_service() for more details.
+   *
+   * @param service The service type to look up (eg, "ldap").
+   * @param protocol The networking protocol to use for service (eg, "tcp") 
+   * @param domain The DNS domain to look up the service in.
+   * @param slot A callback slot to call after the resolution completes.
+   * @param cancellable A Cancellable object which can be used to cancel the operation.
+   */
   void lookup_service_async(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const SlotAsyncReady& slot, const Glib::RefPtr<Cancellable>& cancellable);
   
-  //TODO: Documentation
+  /** Begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback, 
+   * which must call lookup_service_finish() to get the final result. See glookup_service() for more details.
+   *
+   * @param service The service type to look up (eg, "ldap").
+   * @param protocol The networking protocol to use for service (eg, "tcp") 
+   * @param domain The DNS domain to look up the service in.
+   * @param slot A callback slot to call after the resolution completes.
+   */
   void lookup_service_async(const Glib::ustring& service, const Glib::ustring& protocol, const Glib::ustring& domain, const SlotAsyncReady& slot);
   _IGNORE(g_resolver_lookup_service_async)
 
diff --git a/gio/src/seekable.hg b/gio/src/seekable.hg
index df8ae008..869f7373 100644
--- a/gio/src/seekable.hg
+++ b/gio/src/seekable.hg
@@ -53,7 +53,7 @@ public:
 
   _WRAP_METHOD(bool seek(goffset offset, Glib::SeekType type, const Glib::RefPtr<Cancellable>& cancellable), g_seekable_seek, errthrow)
 
-  //TODO: Document the exception: http://bugzilla.gnome.org/show_bug.cgi?id=509990
+  //TODO: Document the exception in the C API: https://bugzilla.gnome.org/show_bug.cgi?id=509990#c1
   /** Seeks in the stream by the given @a offset, modified by @a type .
    * 
    * @param offset A #goffset.
@@ -67,7 +67,7 @@ public:
 
   _WRAP_METHOD(bool truncate(goffset offset, const Glib::RefPtr<Cancellable>& cancellable), g_seekable_truncate, errthrow)
 
-  //TODO: Document the exception: http://bugzilla.gnome.org/show_bug.cgi?id=509990
+  //TODO: Document the exception in the C API: https://bugzilla.gnome.org/show_bug.cgi?id=509990#c1
   /** Truncates a stream with a given #offset. 
    * 
    * @param offset A #goffset.
diff --git a/gio/src/settings.hg b/gio/src/settings.hg
index 231e0f8e..1d85bbaa 100644
--- a/gio/src/settings.hg
+++ b/gio/src/settings.hg
@@ -52,7 +52,7 @@ public:
 
   _WRAP_METHOD(bool set_value(const Glib::ustring& key, const Glib::VariantBase& value),  g_settings_set_value)
 
-  /** TODO: Gets the value that is stored in the settings for a @key.
+  /** Gets the value that is stored in the settings for a @key.
    *
    * It is a programmer error to give a @a key that isn't contained in the
    * schema for the settings.
@@ -98,10 +98,13 @@ public:
 
   _WRAP_METHOD(void reset(const Glib::ustring& key), g_settings_reset)
 
-  //TODO: _WRAP_METHOD(Glib::StringArrayHandle list_schemas() const, g_settings_list_schemas)
+#m4 _CONVERSION(`gchar**',`std::vector<Glib::ustring>',`Glib::ArrayHandler<Glib::ustring>::array_to_vector($3, Glib::OWNERSHIP_NONE)')
+  _WRAP_METHOD(std::vector<Glib::ustring> list_schemas() const, g_settings_list_schemas)
+
+#m4 _CONVERSION(`gchar**',`std::vector<Glib::ustring>',`Glib::ArrayHandler<Glib::ustring>::array_to_vector($3, Glib::OWNERSHIP_DEEP)')
+  _WRAP_METHOD(std::vector<Glib::ustring> list_children() const, g_settings_list_children)
+  _WRAP_METHOD(std::vector<Glib::ustring> list_keys() const, g_settings_list_keys)
 
-  _WRAP_METHOD(Glib::StringArrayHandle list_children() const, g_settings_list_children)
-  _WRAP_METHOD(Glib::StringArrayHandle list_keys() const, g_settings_list_keys)
   //TODO: Choose an appropriate Variant template type: GVariant* g_settings_get_range(const gchar* key)
 
   _WRAP_METHOD(bool range_check(const Glib::ustring& key, const Glib::VariantBase& value) const, g_settings_range_check)
diff --git a/gio/src/socket.hg b/gio/src/socket.hg
index be19c693..78db2101 100644
--- a/gio/src/socket.hg
+++ b/gio/src/socket.hg
@@ -115,13 +115,13 @@ public:
   static Glib::RefPtr<Socket> create_from_fd(int fd, const Glib::RefPtr<Cancellable>&
                                              cancellable = Glib::RefPtr<Cancellable>());
 
-  //TODO: Writecusotm documetation, mentioning, for instance, the exception, instead of a bool return.
+  //TODO: Write custom documetation, mentioning, for instance, the exception, instead of a bool return.
   _WRAP_METHOD(void bind(const Glib::RefPtr<SocketAddress>& address, bool allow_reuse), g_socket_bind, errthrow)
   _WRAP_METHOD(void listen(), g_socket_listen, errthrow)
   _WRAP_METHOD(Glib::RefPtr<Socket> accept(const Glib::RefPtr<Cancellable>& cancellable), g_socket_accept, errthrow)
   Glib::RefPtr<Socket> accept();
 
-  //TODO: Writecusotm documetation, mentioning, for instance, the exception, instead of a bool return.
+  //TODO: Write custom documetation, mentioning, for instance, the exception, instead of a bool return.
   _WRAP_METHOD(void connect(const Glib::RefPtr<SocketAddress>& address, const Glib::RefPtr<Cancellable>& cancellable), g_socket_connect, errthrow)
   void connect(const Glib::RefPtr<SocketAddress>& address);
 
diff --git a/gio/src/socketaddressenumerator.hg b/gio/src/socketaddressenumerator.hg
index 6cdfd655..6056c7cb 100644
--- a/gio/src/socketaddressenumerator.hg
+++ b/gio/src/socketaddressenumerator.hg
@@ -41,14 +41,35 @@ class SocketAddressEnumerator : public Glib::Object
 public:
   _WRAP_METHOD(Glib::RefPtr<SocketAddress> next(const Glib::RefPtr<Cancellable>& cancellable), g_socket_address_enumerator_next, errthrow)
 
-  //TODO: Docs.
+  /** Retrieves the next SocketAddress from the enumerator. 
+   * Note that this may block for some amount of time. (Eg, a NetworkAddress may need to do a DNS lookup before it can return an address.)
+   * Use next_async() if you need to avoid blocking.
+   *
+   * If this enumerator is expected to yield addresses, but for some reason is unable to (eg, because of a DNS error), 
+   * then the first call to next() will throw an exception. However, if the first call to next() succeeds, then any further internal errors 
+   * will be ignored.
+   *
+   * When there are no further addresses, an exception will be thrown.
+   *
+   * @result A SocketAddress
+   */
   Glib::RefPtr<SocketAddress> next();
 
-  _IGNORE(g_socket_address_enumerator_next_async)
+  /** Asynchronously retrieves the next SocketAddress from the enumerator and then calls @a slot, 
+   * which must call next_finish() to get the result.
+   *
+   * @param cancellable A Cancellable object which can be used to cancel the operation.
+   * @param slot A callback slot to call after the resolution completes.
+   */
   void next_async(const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
 
-  //TODO: Docs.
+  /** Asynchronously retrieves the next SocketAddress from the enumerator and then calls @a slot, 
+   * which must call next_finish() to get the result.
+   *
+   * @param slot A callback slot to call after the resolution completes.
+   */
   void next_async(const SlotAsyncReady& slot);
+  _IGNORE(g_socket_address_enumerator_next_async)
 
   _WRAP_METHOD(Glib::RefPtr<SocketAddress> next_finish(const Glib::RefPtr<AsyncResult>& result), g_socket_address_enumerator_next_finish, errthrow)
 };
diff --git a/gio/src/socketclient.hg b/gio/src/socketclient.hg
index 6c7a862b..bb594005 100644
--- a/gio/src/socketclient.hg
+++ b/gio/src/socketclient.hg
@@ -73,7 +73,24 @@ Glib::RefPtr<SocketConnection> connect(const Glib::RefPtr<SocketConnectable>& co
 
   _WRAP_METHOD(Glib::RefPtr<SocketConnection> connect_to_host(const Glib::ustring& host_and_port, guint16 default_port, const Glib::RefPtr<Cancellable>& cancellable), g_socket_client_connect_to_host, errthrow)
 
-  //TODO: Documentation
+  /** This is a helper function for connect().
+   * This attempts to create a TCP connection to the named host.
+   *
+   * @a host_and_port may be in any of a number of recognised formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon. Ports may be given as decimal numbers or symbolic names (in which case an /etc/services lookup is performed).
+   *
+   * If no port override is given in @a host_and_port then default_port will be used as the port number to connect to.
+   * 
+   * In general, @a host_and_port is expected to be provided by the user (allowing them to give the hostname, and a port overide if necessary) and default_port is expected to be provided by the application.
+   *
+   * In the case that an IP address is given, a single connection attempt is made. In the case that a name is given, multiple connection attempts may be made, in turn and according to the number of address records in DNS, until a connection succeeds.
+   *
+   * Upon a successful connection, a new SocketConnection is constructed and returned. 
+   *
+   * In the event of any failure (DNS error, service not found, no hosts connectable) an exception is thrown.
+   *
+   * @param host_and_port The name and optionally port of the host to connect to.
+   * @param default_port The default port to connect to.
+   */
   Glib::RefPtr<SocketConnection> connect_to_host(const Glib::ustring& host_and_port, guint16 default_port);
 
   _WRAP_METHOD(Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, const Glib::ustring& service, const Glib::RefPtr<Cancellable>& cancellable), g_socket_client_connect_to_service, errthrow)
@@ -81,13 +98,31 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
 
   _WRAP_METHOD(Glib::RefPtr<SocketConnection> connect_to_uri(const Glib::ustring& uri, guint16 default_port, const Glib::RefPtr<Cancellable>& cancellable), g_socket_client_connect_to_uri, errthrow)
 
-  //TODO: Documentation
+  /** This is a helper function for connect().
+   * This attempts to create a TCP connection with a network URI.
+   *
+   * @a uri may be any valid URI containing an "authority" (hostname/port) component. If a port is not specified in the URI, default_port will be used. TLS will be negotiated if "tls" is true. (GSocketClient does not know to automatically assume TLS for certain URI schemes.)
+   *
+   * Using this rather than connect() or connect_to_host() allows SocketClient to determine when to use application-specific proxy protocols.
+   *
+   * Upon a successful connection, a new SocketConnection is constructed and returned.
+   *
+   * In the event of any failure (DNS error, service not found, no hosts connectable) an exception is thrown.
+   *
+   * @param uri A network URI
+   * @param default_port The default port to connect to.
+   */
   Glib::RefPtr<SocketConnection> connect_to_uri(const Glib::ustring& uri, guint16 default_port);
 
   _WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_async)
   void connect_async(const Glib::RefPtr<SocketConnectable>& connectable, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
 
-  //TODO: Documentation
+  /** This is the asynchronous version of connect().
+   * When the operation is finished @a slot will be called. You can then call finish() to get the result of the operation.
+   *
+   * @param connectable A SocketConnectable specifying the remote address.
+   * @param slot A callback slot to call after the operation completes.
+   */
   void connect_async(const Glib::RefPtr<SocketConnectable>& connectable, const SlotAsyncReady& slot);
  _IGNORE(g_socket_client_connect_async)
 
@@ -97,7 +132,13 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
   _WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_to_host_async)
   void connect_to_host_async(const Glib::ustring& host_and_port, guint16 default_port, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
 
-  //TODO: Documentation
+  /** This is the asynchronous version of connect_to_host().
+   * When the operation is finished @a slot will be called. You can then call connect_to_host_finish() to get the result of the operation.
+   *
+   * @param host_and_port The name and optionally the port of the host to connect to.
+   * @param default_port The default port to connect to.
+   * @param slot A callback slot to call after the opration completes.
+   */
   void connect_to_host_async(const Glib::ustring& host_and_port, guint16 default_port, const SlotAsyncReady& slot);
   _IGNORE(g_socket_client_connect_to_host_async)
 
@@ -107,7 +148,12 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
   _WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_to_service_async)
   void connect_to_service_async(const Glib::ustring& domain, const Glib::ustring& service, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
 
-  //TODO: Documentation
+  /** This is the asynchronous version of connect_to_service().
+   *
+   * @param domain A domain name.
+   * @param service The name of the service to connect to
+   * @param slot A callback slot to call after the opration completes.
+   */
   void connect_to_service_async(const Glib::ustring& domain, const Glib::ustring& service, const SlotAsyncReady& slot);
   _IGNORE(g_socket_client_connect_to_service_async)
 
@@ -117,7 +163,12 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
   _WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_to_uri_async)
   void connect_to_uri_async(const Glib::ustring& uri, guint16 default_port, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
 
-  //TODO: Documentation
+  /** This is the asynchronous version of connect_to_uri().
+   *
+   * @param uri A network URI.
+   * @param default_port The default port to connect to.
+   * @param slot A callback slot to call after the opration completes.
+   */
   void connect_to_uri_async(const Glib::ustring& uri, guint16 default_port, const SlotAsyncReady& slot);
   _IGNORE(g_socket_client_connect_to_uri_async)
 
@@ -133,11 +184,10 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
   _WRAP_METHOD(void add_application_proxy(const Glib::ustring& protocol), g_socket_client_add_application_proxy)
 
 
-_WRAP_PROPERTY("family", SocketFamily)
-_WRAP_PROPERTY("local-address", Glib::RefPtr<SocketAddress>)
-_WRAP_PROPERTY("protocol", SocketProtocol)
-_WRAP_PROPERTY("type", SocketType)
-
+  _WRAP_PROPERTY("family", SocketFamily)
+  _WRAP_PROPERTY("local-address", Glib::RefPtr<SocketAddress>)
+  _WRAP_PROPERTY("protocol", SocketProtocol)
+  _WRAP_PROPERTY("type", SocketType)
 };
 
 } // namespace Gio
diff --git a/gio/src/socketcontrolmessage.hg b/gio/src/socketcontrolmessage.hg
index fc290e9c..ddb5e691 100644
--- a/gio/src/socketcontrolmessage.hg
+++ b/gio/src/socketcontrolmessage.hg
@@ -55,7 +55,7 @@ protected:
   _CTOR_DEFAULT
 
 public:
-  //TODO?: _WRAP_METHOD(static Glib::RefPtr<SocketControlMessage> deserialize(int level, int type, gsize size, gpointer data), g_socket_control_message_deserialize)
+  _WRAP_METHOD(static Glib::RefPtr<SocketControlMessage> deserialize(int level, int type, gsize size, gpointer data), g_socket_control_message_deserialize)
   _WRAP_METHOD(int get_level() const, g_socket_control_message_get_level)
   _WRAP_METHOD(int get_msg_type() const, g_socket_control_message_get_msg_type)
   _WRAP_METHOD(gsize get_size() const, g_socket_control_message_get_size)
diff --git a/gio/src/themedicon.hg b/gio/src/themedicon.hg
index b7260a9c..42435582 100644
--- a/gio/src/themedicon.hg
+++ b/gio/src/themedicon.hg
@@ -47,11 +47,20 @@ class ThemedIcon
   _IMPLEMENTS_INTERFACE(Icon)
 
 protected:
-  //TODO: Documentation:
+  /** Creates a new themed icon for @ iconname, and optionally all the names that can be created by shortening @a iconname at '-' characters. 
+   *
+   * @param iconname A string containing an icon name.
+   * use_default_callbacks Whether to use all the names that can be created by shortening @a iconname at '-' characters. 
+   */
   explicit ThemedIcon(const std::string& iconname, bool use_default_callbacks = false);
   _IGNORE(g_themed_icon_new, g_themed_icon_new_with_default_fallbacks)
 
 public:
+  /** Creates a new themed icon for @ iconname, and optionally all the names that can be created by shortening @a iconname at '-' characters. 
+   *
+   * @param iconname A string containing an icon name.
+   * use_default_callbacks Whether to use all the names that can be created by shortening @a iconname at '-' characters. 
+   */
   _WRAP_CREATE(const std::string& iconname, bool use_default_callbacks = false)
 
   //TODO: GIcon *g_themed_icon_new_from_names (char **iconnames, int len);
@@ -59,7 +68,7 @@ public:
   _WRAP_METHOD(void prepend_name(const std::string& iconname), g_themed_icon_prepend_name)
   _WRAP_METHOD(void append_name(const std::string& iconname), g_themed_icon_append_name)
 
-  //TODO: USe _WRAP_METHOD() instead, but:
+  //TODO: Use _WRAP_METHOD() instead, but:
   //#m4 _CONVERSION(`const char*const*',`Glib::StringArrayHandle',`Glib::StringArrayHandle($3, Glib::OWNERSHIP_DEEP)')
   //TODO: gmmproc complains about the wrong number of arguments, but I can't see why. murrayc.
   //_WRAP_METHOD(Glib::StringArrayHandle get_names() const, g_themed_icon_get_names)
diff --git a/glib/src/optioncontext.hg b/glib/src/optioncontext.hg
index 9ec718cb..eda22380 100644
--- a/glib/src/optioncontext.hg
+++ b/glib/src/optioncontext.hg
@@ -91,7 +91,14 @@ public:
   #m4 _CONVERSION(`const OptionGroup&',`GOptionGroup*',`const_cast<GOptionGroup*>(($3).gobj())')
   _WRAP_METHOD(Glib::ustring get_help(bool main_help, const OptionGroup& group) const, g_option_context_get_help)
  
-  //TODO: Documentation.
+  /** Returns a formatted, translated help text for the given context. 
+   * To obtain the text produced by --help, call get_help (true). 
+   * To obtain the text produced by --help-all, call get_help(false).
+   * To obtain the help text for an option group, call get_help(false, group).
+   *
+   * @param main_help If true, only include the main group.
+   * @result string containing the help text.
+   */
   Glib::ustring get_help(bool main_help = true) const;
 
   GOptionContext*       gobj()       { return gobject_; }
diff --git a/glib/src/varianttype.hg b/glib/src/varianttype.hg
index fae804fd..9942ef7b 100644
--- a/glib/src/varianttype.hg
+++ b/glib/src/varianttype.hg
@@ -97,8 +97,12 @@ public:
    */
   explicit VariantType(const GVariantType* castitem);
 
-  //TODO: Docuementation
+  /** Creates a new VariantType corresponding to the type string given by @a type_string. 
+    * 
+    * It is a programmer error to call this function with an invalid type string. Use string_is_valid() if you are unsure.
+    */
   explicit VariantType(const std::string& type_string);
+  _IGNORE(g_variant_type_new)
 
   VariantType& operator=(const GVariantType* castitem);