Bumps documentation to 93% symbol coverage, touching most

	of the public files. Fixes broken function documentation prototypes. 
	Fixes GCancellable inaccuracies. Removes unnecessary incomplete 
	gtk-doc headers in private files.

svn path=/trunk/; revision=5953

88 files changed, 3708 insertions, 747 deletions

diff --git a/gio/ChangeLog b/gio/ChangeLog
index cdd4a761f..0bd45400b 100644
--- a/gio/ChangeLog
+++ b/gio/ChangeLog
@@ -1,3 +1,96 @@
+2007-11-27  Andrew Walton  <awalton@svn.gnome.org>
+	* gappinfo.c:
+	* gappinfo.h:
+	* gasynchelper.c:
+	* gasyncresult.c:
+	* gasyncresult.h:
+	* gbufferedinputstream.c:
+	* gbufferedinputstream.h:
+	* gbufferedoutputstream.c:
+	* gbufferedoutputstream.h:
+	* gcancellable.c: 
+	* gcancellable.h:
+	* gcontenttype.c:
+	* gdatainputstream.c:
+	* gdatainputstream.h:
+	* gdataoutputstream.c:
+	* gdataoutputstream.h:
+	* gdirectorymonitor.c:
+	* gdirectorymonitor.h:
+	* gdrive.c: 
+	* gdrive.h:
+	* gfile.c:
+	* gfile.h:
+	* gfileattribute.c:
+	* gfileattribute.h:
+	* gfileenumerator.c:
+	* gfileenumerator.h:
+	* gfileicon.c:
+	* gfileicon.h:
+	* gfileinfo.c:
+	* gfileinfo.h:
+	* gfileinputstream.c:
+	* gfileinputstream.h:
+	* gfilemonitor.c:
+	* gfilemonitor.h:
+	* gfilenamecompleter.c:
+	* gfilenamecompleter.h:
+	* gfileoutputstream.c:
+	* gfileoutputstream.h:
+	* gfilterinputstream.c:
+	* gfilterinputstream.h:
+	* gfilteroutputstream.c:
+	* gfilteroutputstream.h:
+	* gicon.c:
+	* gicon.h:
+	* ginputstream.c:
+	* ginputstream.h:
+	* gioerror.c:
+	* gioerror.h:
+	* giomodule.c:
+	* giomodule.h:
+	* gioscheduler.c:
+	* gioscheduler.h:
+	* gloadableicon.c:
+	* gloadableicon.h:
+	* glocalfileoutputstream.c:
+	* gmemoryinputstream.c:
+	* gmemoryinputstream.h:
+	* gmemoryoutputstream.c:
+	* gmemoryoutputstream.h:
+	* gmountoperation.c: 
+	* gmountoperation.h:
+	* goutputstream.c:
+	* goutputstream.h:
+	* gpollfilemonitor.c:
+	* gseekable.c:
+	* gseekable.h:
+	* gsimpleasyncresult.c:
+	* gsimpleasyncresult.h:
+	* gsocketinputstream.c:
+	* gsocketinputstream.h:
+	* gsocketoutputstream.c:
+	* gsocketoutputstream.h:
+	* gthemedicon.c:
+	* gthemedicon.h:
+	* gunixdrive.c:
+	* gunixmounts.c: 
+	* gunixmounts.h:
+	* gunixvolume.c:
+	* gunixvolumemonitor.c:
+	* gurifuncs.c:
+	* gurifuncs.h:
+	* gvfs.c:
+	* gvfs.h:
+	* gvolume.c:
+	* gvolume.h:
+	* gvolumemonitor.c: 
+	* gvolumemonitor.h:
+	Bumps documentation to 93% symbol coverage, touching most 
+	of the public files. Fixes broken function documentation prototypes. 
+	Fixes GCancellable inaccuracies. Removes unnecessary incomplete 
+	gtk-doc headers in private files.
+
 2007-11-27  Jürg Billeter  <j@bitron.ch>
 
 	* gbufferedinputstream.c: (g_buffered_input_stream_peek_buffer),
diff --git a/gio/gappinfo.c b/gio/gappinfo.c
index 922d70072..eb26f6bbc 100644
--- a/gio/gappinfo.c
+++ b/gio/gappinfo.c
@@ -25,6 +25,17 @@
 #include "glibintl.h"
 #include <gioerror.h>
 
+/**
+ * SECTION:gappinfo
+ * @short_description: Application information and launch contexts. 
+ * @stability: Unstable
+ * 
+ * #GAppInfo and #GAppLaunchContext are used for describing and launching 
+ * installed system applications. 
+ *
+ * @Note: These may/will be moved to Gtk+ in the future.
+ *
+ **/
 
 static void g_app_info_base_init (gpointer g_class);
 static void g_app_info_class_init (gpointer g_class,
@@ -76,6 +87,8 @@ g_app_info_base_init (gpointer g_class)
 /**
  * g_app_info_dup:
  * @appinfo: a #GAppInfo.
+ * 
+ * Creates a duplicate of a #GAppInfo.
  *
  * Returns: a duplicate of @appinfo.
  **/
@@ -95,9 +108,10 @@ g_app_info_dup (GAppInfo *appinfo)
  * g_app_info_equal:
  * @appinfo1: the first #GAppInfo.  
  * @appinfo2: the second #GAppInfo.
+ * 
+ * Checks if two #GAppInfos are equal.
  *
  * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
- *  
  **/
 gboolean
 g_app_info_equal (GAppInfo    *appinfo1,
@@ -119,8 +133,10 @@ g_app_info_equal (GAppInfo    *appinfo1,
 /**
  * g_app_info_get_id:
  * @appinfo: a #GAppInfo.
+ * 
+ * Gets the ID of an application.
  *
- * Returns: 
+ * Returns: a string containing the application's ID.
  **/
 const char *
 g_app_info_get_id (GAppInfo *appinfo)
@@ -137,6 +153,8 @@ g_app_info_get_id (GAppInfo *appinfo)
 /**
  * g_app_info_get_name:
  * @appinfo: a #GAppInfo.
+ * 
+ * Gets the installed name of the application. 
  *
  * Returns: the name of the application for @appinfo.
  **/
@@ -155,10 +173,12 @@ g_app_info_get_name (GAppInfo *appinfo)
 /**
  * g_app_info_get_description:
  * @appinfo: a #GAppInfo.
+ * 
+ * Gets a human-readable description of an installed application.
  *
  * Returns: a string containing a description of the 
- * application @appinfo.  
- * The returned string should be not freed when no longer needed.
+ * application @appinfo. The returned string should be not freed 
+ * when no longer needed.
  **/
 const char *
 g_app_info_get_description (GAppInfo *appinfo)
@@ -175,6 +195,8 @@ g_app_info_get_description (GAppInfo *appinfo)
 /**
  * g_app_info_get_executable:
  * @appinfo: a #GAppInfo.
+ * 
+ * Gets the executable's name for the installed application.
  *
  * Returns: a string containing the @appinfo's application 
  * binary's name.
@@ -197,6 +219,8 @@ g_app_info_get_executable (GAppInfo *appinfo)
  * @appinfo: a #GAppInfo.
  * @content_type: the content type.
  * @error: a #GError.
+ * 
+ * Sets an application as the default handler for a given type.
  *
  * Returns: %TRUE if the given @appinfo is the default 
  * for the given @content_type. %FALSE if not, 
@@ -223,6 +247,8 @@ g_app_info_set_as_default_for_type (GAppInfo    *appinfo,
  * @appinfo: a #GAppInfo.
  * @extension: a string containing the file extension.
  * @error: a #GError.
+ * 
+ * Sets an application as the default handler for the given file extention.
  *
  * Returns: %TRUE if the given @appinfo is the default 
  * for the given @extension. %FALSE if not, 
@@ -253,6 +279,9 @@ g_app_info_set_as_default_for_extension (GAppInfo  *appinfo,
  * @appinfo: a #GAppInfo.
  * @content_type: a string.
  * @error: a #GError.
+ * 
+ * Adds a content type to the application information to indicate the 
+ * application is capable of opening files with the given content type.
  *
  * Returns: %TRUE if @appinfo supports @content_type.
  * %FALSE if not, or in case of an error.
@@ -280,6 +309,8 @@ g_app_info_add_supports_type (GAppInfo             *appinfo,
 /**
  * g_app_info_can_remove_support_type:
  * @appinfo: a #GAppInfo.
+ * 
+ * Checks if a supported content type can be removed from an application.
  *
  * Returns: %TRUE if it is possible to remove supported 
  * content types from a given @appinfo, %FALSE if not.
@@ -306,6 +337,8 @@ g_app_info_can_remove_supports_type (GAppInfo *appinfo)
  * @content_type: a string.
  * @error: a #GError.
  *
+ * Removes a supported type from an application, if possible.
+ * 
  * Returns: %TRUE if @content_type support was removed
  * from @appinfo. %FALSE if not.
  **/
@@ -332,6 +365,8 @@ g_app_info_remove_supports_type (GAppInfo *appinfo,
 /**
  * g_app_info_get_icon:
  * @appinfo: a #GAppInfo.
+ * 
+ * Gets the default icon for the application.
  *
  * Returns: the default #GIcon for @appinfo.
  **/
@@ -354,8 +389,12 @@ g_app_info_get_icon (GAppInfo *appinfo)
  * @files: a #GList of #GFile objects.
  * @launch_context: a #GAppLaunchContext.
  * @error: a #GError.
+ * 
+ * Launches the application. Passes @files to the launched application 
+ * as arguments, and loads the @launch_context for managing the application
+ * once it has been launched. On error, @error will be set accordingly.
  *
- * Returns: %TRUE on successful launch.
+ * Returns: %TRUE on successful launch, %FALSE otherwise.
  **/
 gboolean
 g_app_info_launch (GAppInfo    *appinfo,
@@ -376,6 +415,8 @@ g_app_info_launch (GAppInfo    *appinfo,
 /**
  * g_app_info_supports_uris:
  * @appinfo: a #GAppInfo.
+ * 
+ * Checks if the application supports reading files and directories from URIs.
  *
  * Returns: %TRUE if the @appinfo supports URIs.
  **/
@@ -398,9 +439,12 @@ g_app_info_supports_uris (GAppInfo *appinfo)
  * @uris: a #GList containing URIs to launch. 
  * @launch_context: a #GAppLaunchContext.
  * @error: a #GError.
+ * 
+ * Launches the application. Passes @uris to the launched application 
+ * as arguments, and loads the @launch_context for managing the application
+ * once it has been launched. On error, @error will be set accordingly.
  *
- * Returns: %TRUE if the @appinfo was launched 
- * with the given @uris.
+ * Returns: %TRUE if the @appinfo was launched successfully, %FALSE otherwise.
  **/
 gboolean
 g_app_info_launch_uris (GAppInfo    *appinfo,
@@ -423,8 +467,10 @@ g_app_info_launch_uris (GAppInfo    *appinfo,
  * @appinfo: a #GAppInfo.
  * @desktop_env: a string.
  *
- * Returns: %TRUE if the @GAppInfo should be shown,
- * %FALSE otherwise.
+ * Checks if the application info should be shown when listing
+ * applications available.
+ * 
+ * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
  **/
 gboolean
 g_app_info_should_show (GAppInfo    *appinfo,
@@ -443,8 +489,10 @@ G_DEFINE_TYPE (GAppLaunchContext, g_app_launch_context, G_TYPE_OBJECT);
 
 /**
  * g_app_launch_context_new:
+ * 
+ * Creates a new application launch context.
  *
- * Returns: A new #GAppLaunchContext.
+ * Returns: a #GAppLaunchContext.
  **/
 GAppLaunchContext *
 g_app_launch_context_new (void)
@@ -468,6 +516,11 @@ g_app_launch_context_init (GAppLaunchContext *launch_context)
  * @info: a #GAppInfo. 
  * @files: a #GList of files.
  *
+ * Gets the DISPLAY for a launched application.
+ * TODO: can't find an implementation. DISPLAY as in X atom "DISPLAY"?
+ * Environmental variable "DISPLAY"?
+ * 
+ * Returns: a display string.
  **/
 char *
 g_app_launch_context_get_display (GAppLaunchContext *context,
@@ -487,12 +540,18 @@ g_app_launch_context_get_display (GAppLaunchContext *context,
   return class->get_display (context, info, files);
 }
 
+/* should this be moved to the g_desktop_app_ implementation? */
 /**
  * g_app_launch_context_get_startup_notify_id:
  * @context: a #GAppLaunchContext.
  * @info: a #GAppInfo.
  * @files: a #GList of files.
+ * 
+ * Gets the DESKTOP_STARTUP_ID for the launched application, if supported. 
+ * Startup notification IDs are defined in the FreeDesktop.Org Startup Notifications standard, 
+ * at <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"/>.
  *
+ * Returns: a startup notifaction ID for the application, or %NULL if not supported.
  **/
 char *
 g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context,
@@ -514,10 +573,12 @@ g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context,
 
 
 /**
- * g_app_launch_context_get_startup_notify_id:
+ * g_app_launch_context_launch_failed:
  * @context: a #GAppLaunchContext.
- * @startup_notify_id: a string containing the startup ID of the application.
+ * @startup_notify_id: a string containing the DESKTOP_STARTUP_ID of the launched application.
  *
+ * TODO: what does this do? Can't find it implemented anywhere.
+ * 
  **/
 void
 g_app_launch_context_launch_failed (GAppLaunchContext *context,
diff --git a/gio/gappinfo.h b/gio/gappinfo.h
index 0a88349d4..4e42685f9 100644
--- a/gio/gappinfo.h
+++ b/gio/gappinfo.h
@@ -40,6 +40,13 @@ G_BEGIN_DECLS
 #define G_IS_APP_LAUNCH_CONTEXT_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_APP_LAUNCH_CONTEXT))
 #define G_APP_LAUNCH_CONTEXT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_APP_LAUNCH_CONTEXT, GAppLaunchContextClass))
 
+/**
+ * GAppInfoCreateFlags:
+ * @G_APP_INFO_CREATE_FLAGS_NONE: No flags.
+ * @G_APP_INFO_CREATE_NEEDS_TERMINAL: Application opens with a terminal window.
+ * 
+ * Flags used when creating a #GAppInfo.
+ */
 typedef enum {
   G_APP_INFO_CREATE_FLAGS_NONE = 0,
   G_APP_INFO_CREATE_NEEDS_TERMINAL = (1<<0)
@@ -49,7 +56,38 @@ typedef struct _GAppLaunchContext        GAppLaunchContext;
 typedef struct _GAppLaunchContextClass   GAppLaunchContextClass;
 typedef struct _GAppLaunchContextPrivate GAppLaunchContextPrivate;
 
+/**
+ * GAppInfo:
+ * 
+ * Information about an installed application.
+ */
 typedef struct _GAppInfo         GAppInfo; /* Dummy typedef */
+
+/**
+ * GAppInfoIface:
+ * @g_iface: The parent interface.
+ * @dup: Copies a #GAppInfo.
+ * @equal: Checks two #GAppInfo<!-- -->s for equality.
+ * @get_id: Gets a string identifier for a #GAppInfo.
+ * @get_name: Gets the name of the application for a #GAppInfo.
+ * @get_description: Gets a short description for the application described by the #GAppInfo.
+ * @get_executable: Gets the execuable name for the #GAppInfo.
+ * @get_icon: Gets the #GIcon for the #GAppInfo.
+ * @launch: Launches an application specified by the #GAppInfo.
+ * @supports_uris: Indicates whether the application specified supports launching URIs.
+ * @launch_uris: Launches an application with a list of URIs.
+ * @should_show: Returns whether an application should be shown (e.g. when getting a list of installed applications).
+ * @supports_xdg_startup_notify: Indicates whether the application supports the 
+ * <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
+ * <citetitle>FreeDesktop.Org Startup Notification Specification</citetitle></ulink>.
+ * @set_as_default_for_type: Sets an application as default for a given content type.
+ * @set_as_default_for_extension: Sets an application as default for a given file extention.
+ * @add_supports_type: Adds to the #GAppInfo information about supported file types.
+ * @can_remove_supports_type: Checks for support for removing supported file types from a #GAppInfo.
+ * @remove_supports_type: Removes a supported application type from a #GAppInfo.
+ * 
+ * Application Information interface, for operating system portability.
+ */
 typedef struct _GAppInfoIface    GAppInfoIface;
 
 struct _GAppInfoIface
@@ -94,7 +132,7 @@ struct _GAppInfoIface
   gboolean  (*remove_supports_type)         (GAppInfo           *appinfo,
 					     const char         *content_type,
 					     GError            **error);
-
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
@@ -162,11 +200,17 @@ GAppInfo *g_app_info_get_default_for_uri_scheme  (const char  *uri_scheme);
    can_remove, remove (as in, don't support a specific mimetype)
 */
 
-
+/**
+ * GAppLaunchContext:
+ * @parent_instance: The parent instance.
+ * 
+ * Gets feedback from the system when launching an application.
+ */
 struct _GAppLaunchContext
 {
   GObject parent_instance;
 
+  /*< private >*/
   GAppLaunchContextPrivate *priv;
 };
 
diff --git a/gio/gasynchelper.c b/gio/gasynchelper.c
index b6a9352c7..98bce1b48 100644
--- a/gio/gasynchelper.c
+++ b/gio/gasynchelper.c
@@ -24,6 +24,15 @@
 
 #include "gasynchelper.h"
 
+/**
+ * SECTION:gasynchelper
+ * @short_description: Asynchronous Helper Functions
+ * @see_also: #GAsyncReady.
+ * 
+ * Provides helper functions for asynchronous operations.
+ *
+ **/
+
 static void
 async_result_free (gpointer data)
 {
diff --git a/gio/gasyncresult.c b/gio/gasyncresult.c
index 840931976..9d698a599 100644
--- a/gio/gasyncresult.c
+++ b/gio/gasyncresult.c
@@ -24,6 +24,65 @@
 #include "gasyncresult.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gasyncresult
+ * @short_description: Asynchronous Function Results
+ * @see_also: #GSimpleAsyncResult
+ * 
+ * Provides a base class for implementing asynchronous function results.
+ * 
+ * Asynchronous operations are broken up into two separate operations
+ * which are chained together by a #GAsyncReadyCallback. To begin
+ * an asynchronous operation, provide a #GAsyncReadyCallback to the asynchronous
+ * function. This callback will be triggered when the operation has completed, 
+ * and will be passed a #GAsyncReady instance filled with the details of the operation's
+ * success or failure, the object the asynchronous function was 
+ * started for and any error codes returned. The asynchronous callback function
+ * is then expected to call the corresponding "_finish()" operation with the
+ * object the function was called for, and the #GAsyncReady instance, and optionally, 
+ * an @error to grab any error conditions that may have occurred.
+ * 
+ * Example of a typical asynchronous operation flow:
+ * <informalexample>
+ * <programlisting>
+ * void _theoretical_frobnitz_async (Theoretical *t, 
+ *                                   GCancellable *c, 
+ *                                   GAsyncReadyCallback *cb,
+ *                                   gpointer u);
+ *
+ * gboolean _theoretical_frobnitz_finish (Theoretical *t,
+ *                                        GAsyncResult *res,
+ *                                        GError **e);
+ *
+ * static void 
+ * frobnitz_result_func (GObject *source_object, 
+ *			 GAsyncResult *res, 
+ *			 gpointer user_data)
+ * {
+ *   gboolean success = FALSE;
+ *   success = _theoretical_frobnitz_finish( source_object, res, NULL );
+ *   if (success)
+ *     g_printf("Hurray!/n");
+ *   else 
+ *     g_printf("Uh oh!/n");
+ *   /<!-- -->* ... *<!-- -->/
+ *   g_free(res);
+ * }
+ *
+ * int main (int argc, void *argv[])
+ * {
+ *    /<!-- -->* ... *<!-- -->/
+ *    _theoretical_frobnitz_async (theoretical_data, NULL, frobnitz_result_func, NULL);
+ *
+ *    /<!-- -->* ... *<!-- -->/
+ * </programlisting>
+ * </informalexample> 
+ * 
+ * Asynchronous jobs are threaded if #GThread is available, but also may
+ * be sent to the Main Event Loop and processed in an idle function.
+ *
+ **/
+
 static void g_async_result_base_init (gpointer g_class);
 static void g_async_result_class_init (gpointer g_class,
 				       gpointer class_data);
@@ -73,8 +132,9 @@ g_async_result_base_init (gpointer g_class)
  * g_async_result_get_user_data:
  * @res: a #GAsyncResult.
  * 
- * Returns: the user data for the given @res, or
- * %NULL on failure. 
+ * Gets the user data from a #GAsyncResult.
+ * 
+ * Returns: the user data for @res. 
  **/
 gpointer
 g_async_result_get_user_data (GAsyncResult *res)
@@ -92,6 +152,8 @@ g_async_result_get_user_data (GAsyncResult *res)
  * g_async_result_get_source_object:
  * @res: a #GAsyncResult.
  * 
+ * Gets the source object from a #GAsyncResult.
+ * 
  * Returns: the source object for the @res.
  **/
 GObject *
diff --git a/gio/gasyncresult.h b/gio/gasyncresult.h
index 26f867e02..123c20a7b 100644
--- a/gio/gasyncresult.h
+++ b/gio/gasyncresult.h
@@ -32,13 +32,36 @@ G_BEGIN_DECLS
 #define G_IS_ASYNC_RESULT(obj)	       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_ASYNC_RESULT))
 #define G_ASYNC_RESULT_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ASYNC_RESULT, GAsyncResultIface))
 
+/**
+ * GAsyncResult:
+ *
+ * Holds results information for an asynchronous operation, 
+ * usually passed directly to a asynchronous _finish() operation.
+ **/
 typedef struct _GAsyncResult         GAsyncResult; /* Dummy typedef */
 typedef struct _GAsyncResultIface    GAsyncResultIface;
 
+/**
+ * GAsyncReadyCallback:
+ * @source_object: the object the asynchronous operation was started with.
+ * @res: a #GAsyncResult.
+ * @user_data: user data passed to the callback.
+ *
+ * Type definition for a function that will be called back when an asynchronous 
+ * operation within GIO has been completed. 
+ **/
 typedef void (*GAsyncReadyCallback) (GObject *source_object,
 				     GAsyncResult *res,
 				     gpointer user_data);
 
+/**
+ * GAsyncResultIface:
+ * @g_iface: The parent interface. 
+ * @get_user_data: Gets the user data passed to the callback.
+ * @get_source_object: Gets the source object that issued the asynchronous operation.
+ *
+ * Interface definition for #GAsyncResult.
+ **/
 struct _GAsyncResultIface
 {
   GTypeInterface g_iface;
diff --git a/gio/gbufferedinputstream.c b/gio/gbufferedinputstream.c
index dfd6c2ea5..1c7d377ef 100644
--- a/gio/gbufferedinputstream.c
+++ b/gio/gbufferedinputstream.c
@@ -22,14 +22,35 @@
  */
 
 #include <config.h>
-
 #include "gbufferedinputstream.h"
 #include "ginputstream.h"
 #include "gsimpleasyncresult.h"
 #include <string.h>
-
 #include "glibintl.h"
 
+/**
+ * SECTION:gbufferedinputstream
+ * @short_description: Buffered Input Stream
+ * @see_also: #GFilterInputStream, #GInputStream.
+ * 
+ * Buffered input stream implements #GFilterInputStream and provides 
+ * for buffered reads. 
+ * 
+ * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes.
+ * 
+ * To create a buffered input stream, use g_buffered_input_stream_new(), or 
+ * g_buffered_input_stream_new_sized() to specify the buffer's size at construction.
+ * 
+ * To get the size of a buffer within a buffered input stream, use 
+ * g_buffered_input_stream_get_buffer_size(). To change the size of a 
+ * buffered input stream's buffer, use g_buffered_input_stream_set_buffer_size(). 
+ * Note: the buffer's size cannot be reduced below the size of the data within the
+ * buffer.
+ *
+ **/
+
+
+
 #define DEFAULT_BUFFER_SIZE 4096
 
 struct _GBufferedInputStreamPrivate {
@@ -151,7 +172,9 @@ g_buffered_input_stream_class_init (GBufferedInputStreamClass *klass)
  * g_buffered_input_stream_get_buffer_size:
  * @stream: #GBufferedInputStream.
  * 
- * Returns: the current buffer size, or -1 on error.
+ * Gets the size of the input buffer.
+ * 
+ * Returns: the current buffer size, or %-1 on error.
  **/
 gsize
 g_buffered_input_stream_get_buffer_size (GBufferedInputStream  *stream)
@@ -496,14 +519,14 @@ g_buffered_input_stream_fill_async (GBufferedInputStream  *stream,
 }
 
 /**
- * g_buffered_input_stream_fill_finished:
+ * g_buffered_input_stream_fill_finish:
  * @stream: a #GBufferedInputStream.
  * @result: a #GAsyncResult.
  * @error: a #GError.
  *
  * Finishes an asynchronous read.
  * 
- * Returns: a #gssize of the read stream, or -1 on an error. 
+ * Returns: a #gssize of the read stream, or %-1 on an error. 
  **/
 gssize
 g_buffered_input_stream_fill_finish (GBufferedInputStream  *stream,
@@ -535,6 +558,8 @@ g_buffered_input_stream_fill_finish (GBufferedInputStream  *stream,
  * g_buffered_input_stream_get_available:
  * @stream: #GBufferedInputStream.
  * 
+ * Gets the size of the available data within the stream.
+ * 
  * Returns: size of the available stream. 
  **/
 gsize
@@ -552,7 +577,10 @@ g_buffered_input_stream_get_available (GBufferedInputStream  *stream)
  * @offset: a #gsize.
  * @count: a #gsize.
  * 
- * Returns: 
+ * Peeks in the buffer, copying data of size @count into @buffer, offset
+ * @offset bytes.
+ * 
+ * Returns: a #gsize of the number of bytes peeked, or %-1 on error.
  **/
 gsize
 g_buffered_input_stream_peek (GBufferedInputStream  *stream,
diff --git a/gio/gbufferedinputstream.h b/gio/gbufferedinputstream.h
index fcf9cb405..cac5d186c 100644
--- a/gio/gbufferedinputstream.h
+++ b/gio/gbufferedinputstream.h
@@ -35,6 +35,11 @@ G_BEGIN_DECLS
 #define G_IS_BUFFERED_INPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_BUFFERED_INPUT_STREAM))
 #define G_BUFFERED_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_BUFFERED_INPUT_STREAM, GBufferedInputStreamClass))
 
+/**
+ * GBufferedInputStream:
+ * 
+ * Implements #GFilterInputStream with a sized input buffer.
+ **/
 typedef struct _GBufferedInputStream         GBufferedInputStream;
 typedef struct _GBufferedInputStreamClass    GBufferedInputStreamClass;
 typedef struct _GBufferedInputStreamPrivate  GBufferedInputStreamPrivate;
@@ -67,6 +72,7 @@ struct _GBufferedInputStreamClass
 			    GAsyncResult         *result,
 			    GError              **error);
 
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gbufferedoutputstream.c b/gio/gbufferedoutputstream.c
index 210ccfb0d..c924425cb 100644
--- a/gio/gbufferedoutputstream.c
+++ b/gio/gbufferedoutputstream.c
@@ -21,14 +21,35 @@
  */
 
 #include <config.h>
-
 #include "gbufferedoutputstream.h"
 #include "goutputstream.h"
 #include "gsimpleasyncresult.h"
 #include "string.h"
-
 #include "glibintl.h"
 
+/**
+ * SECTION:gbufferedoutputstream
+ * @short_description: Buffered Output Stream
+ * @see_also: #GFilterOutputStream, #GOutputStream.
+ * 
+ * Buffered output stream implements #GFilterOutputStream and provides 
+ * for buffered writes. 
+ * 
+ * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes.
+ * 
+ * To create a buffered output stream, use g_buffered_output_stream_new(), or 
+ * g_buffered_output_stream_new_sized() to specify the buffer's size at construction.
+ * 
+ * To get the size of a buffer within a buffered input stream, use 
+ * g_buffered_output_stream_get_buffer_size(). To change the size of a 
+ * buffered output stream's buffer, use g_buffered_output_stream_set_buffer_size(). 
+ * Note: the buffer's size cannot be reduced below the size of the data within the
+ * buffer.
+ *
+ **/
+
+
+
 #define DEFAULT_BUFFER_SIZE 4096
 
 struct _GBufferedOutputStreamPrivate {
@@ -140,6 +161,8 @@ g_buffered_output_stream_class_init (GBufferedOutputStreamClass *klass)
  * g_buffered_output_stream_get_buffer_size:
  * @stream: a #GBufferedOutputStream.
  * 
+ * Gets the size of the buffer in the @stream.
+ * 
  * Returns: the current size of the buffer.
  **/
 gsize
@@ -156,7 +179,6 @@ g_buffered_output_stream_get_buffer_size (GBufferedOutputStream *stream)
  * @size: a #gsize.
  *
  * Sets the size of the internal buffer to @size.
- * 
  **/    
 void
 g_buffered_output_stream_set_buffer_size (GBufferedOutputStream *stream,
@@ -192,6 +214,8 @@ g_buffered_output_stream_set_buffer_size (GBufferedOutputStream *stream,
  * g_buffered_output_stream_get_auto_grow:
  * @stream: a #GBufferedOutputStream.
  * 
+ * Checks if the buffer automatically grows as data is added.
+ * 
  * Returns: %TRUE if the @stream's buffer automatically grows,
  * %FALSE otherwise.
  **/  
@@ -206,10 +230,9 @@ g_buffered_output_stream_get_auto_grow (GBufferedOutputStream *stream)
 /**
  * g_buffered_output_stream_set_auto_grow:
  * @stream: a #GBufferedOutputStream.
- * @auto_grow: a boolean.
+ * @auto_grow: a #gboolean.
  *
  * Sets whether or not the @stream's buffer should automatically grow.
- * 
  **/
 void
 g_buffered_output_stream_set_auto_grow (GBufferedOutputStream *stream,
@@ -300,6 +323,8 @@ g_buffered_output_stream_init (GBufferedOutputStream *stream)
  * g_buffered_output_stream_new:
  * @base_stream: a #GOutputStream.
  * 
+ * Creates a new buffered output stream for a base stream.
+ * 
  * Returns: a #GOutputStream for the given @base_stream.
  **/  
 GOutputStream *
@@ -321,6 +346,8 @@ g_buffered_output_stream_new (GOutputStream *base_stream)
  * @base_stream: a #GOutputStream.
  * @size: a #gsize.
  * 
+ * Creates a new buffered output stream with a given buffer size.
+ * 
  * Returns: a #GOutputStream with an internal buffer set to @size.
  **/  
 GOutputStream *
diff --git a/gio/gbufferedoutputstream.h b/gio/gbufferedoutputstream.h
index 54086448c..816f07e87 100644
--- a/gio/gbufferedoutputstream.h
+++ b/gio/gbufferedoutputstream.h
@@ -35,6 +35,12 @@ G_BEGIN_DECLS
 #define G_IS_BUFFERED_OUTPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_BUFFERED_OUTPUT_STREAM))
 #define G_BUFFERED_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_BUFFERED_OUTPUT_STREAM, GBufferedOutputStreamClass))
 
+/**
+ * GBufferedOutputStream:
+ * @parent_class: The parent class.
+ * 
+ * An implementation of #GFilterOutputStream with a sized buffer.
+ **/
 typedef struct _GBufferedOutputStream         GBufferedOutputStream;
 typedef struct _GBufferedOutputStreamClass    GBufferedOutputStreamClass;
 typedef struct _GBufferedOutputStreamPrivate  GBufferedOutputStreamPrivate;
@@ -51,6 +57,7 @@ struct _GBufferedOutputStreamClass
 {
  GOutputStreamClass parent_class;
 
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gcancellable.c b/gio/gcancellable.c
index c55737a32..a31420bb2 100644
--- a/gio/gcancellable.c
+++ b/gio/gcancellable.c
@@ -25,11 +25,14 @@
 #include <fcntl.h>
 #include <gioerror.h>
 #include "gcancellable.h"
-
 #include "glibintl.h"
 
 
-/*
+/**
+ * SECTION:gcancellable
+ * @short_description: Thread-safe Operation Cancellation Stack
+ * @include: gio/gcancellable.h
+ *
  * GCancellable is a thread-safe operation cancellation stack used 
  * throughout GIO to allow for cancellation of asynchronous operations.
  */
@@ -77,6 +80,12 @@ g_cancellable_class_init (GCancellableClass *klass)
   
   gobject_class->finalize = g_cancellable_finalize;
 
+  /**
+   * GCancellable::cancelled:
+   * @cancellable: a #GCancellable.
+   * 
+   * Emitted when the operation has been cancelled from another thread.
+   */
   signals[CANCELLED] =
     g_signal_new (I_("cancelled"),
 		  G_TYPE_FROM_CLASS (gobject_class),
@@ -129,8 +138,10 @@ g_cancellable_init (GCancellable *cancellable)
 
 /**
  * g_cancellable_new:
+ * 
+ * Creates a new #GCancellable object.
  *  
- * Returns: a new #GCancellable object.
+ * Returns: a #GCancellable.
  **/
 GCancellable *
 g_cancellable_new (void)
@@ -180,6 +191,8 @@ g_pop_current_cancellable (GCancellable *cancellable)
 /**
  * g_cancellable_get_current:
  * 
+ * Gets the top cancellable from the stack.
+ * 
  * Returns: a #GCancellable from the top of the stack, or %NULL
  * if the stack is empty. 
  **/
@@ -200,7 +213,6 @@ g_cancellable_get_current  (void)
  * @cancellable: a #GCancellable object.
  * 
  * Resets @cancellable to its uncancelled state. 
- *
  **/
 void 
 g_cancellable_reset (GCancellable *cancellable)
@@ -223,6 +235,8 @@ g_cancellable_reset (GCancellable *cancellable)
  * g_cancellable_is_cancelled:
  * @cancellable: a #GCancellable or NULL.
  * 
+ * Checks if a cancellable job has been cancelled.
+ * 
  * Returns: %TRUE if @cancellable is is cancelled, 
  * FALSE if called with %NULL or if item is not cancelled. 
  **/
@@ -261,7 +275,9 @@ g_cancellable_set_error_if_cancelled (GCancellable  *cancellable,
  * g_cancellable_get_fd:
  * @cancellable: a #GCancellable.
  * 
- * Returns: A valid file descriptor. -1 if the file descriptor 
+ * Gets the file descriptor for a cancellable job.
+ * 
+ * Returns: A valid file descriptor. %-1 if the file descriptor 
  * is not supported, or on errors. 
  **/
 int
@@ -290,7 +306,6 @@ g_cancellable_get_fd (GCancellable *cancellable)
  * 
  * Will set @cancellable to cancelled, and will emit the CANCELLED
  * signal. This function is thread-safe.
- *  
  **/
 void
 g_cancellable_cancel (GCancellable *cancellable)
diff --git a/gio/gcancellable.h b/gio/gcancellable.h
index a6229da4f..be8495f6c 100644
--- a/gio/gcancellable.h
+++ b/gio/gcancellable.h
@@ -34,6 +34,11 @@ G_BEGIN_DECLS
 #define G_IS_CANCELLABLE_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_CANCELLABLE))
 #define G_CANCELLABLE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_CANCELLABLE, GCancellableClass))
 
+/**
+ * GCancellable:
+ * 
+ * Allows actions to be cancelled.
+ */
 typedef struct _GCancellable        GCancellable;
 typedef struct _GCancellableClass   GCancellableClass;
 
@@ -42,7 +47,8 @@ struct _GCancellableClass
   GObjectClass parent_class;
 
   void (* cancelled) (GCancellable *cancellable);
-
+  
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gcontenttype.c b/gio/gcontenttype.c
index 5952cacdb..c3f2079a5 100644
--- a/gio/gcontenttype.c
+++ b/gio/gcontenttype.c
@@ -21,20 +21,27 @@
  */
 
 #include <config.h>
-
 #include <sys/types.h>
 #include <dirent.h>
 #include <string.h>
 #include <stdio.h>
-
 #include "gcontenttypeprivate.h"
 #include "glibintl.h"
 
-/* A content type is a platform specific string that defines the type
-   of a file. On unix it is a mime type, on win32 it is an extension string
-   like ".doc", ".txt" or a percieved string like "audio". Such strings
-   can be looked up in the registry at HKEY_CLASSES_ROOT.
-*/
+/* This really sucks. GTK-Doc isn't smart enough to realize there are two
+ * different versions of the functions within this file, based on the platform. 
+ * I can move the definitions out of this file, but that's ugly. 
+ */
+
+/**
+ * SECTION:gcontenttype
+ * @short_description: platform specific content typing
+ *
+ * A content type is a platform specific string that defines the type
+ * of a file. On unix it is a mime type, on win32 it is an extension string
+ * like ".doc", ".txt" or a percieved string like "audio". Such strings
+ * can be looked up in the registry at HKEY_CLASSES_ROOT.
+ **/
 
 #ifdef G_OS_WIN32
 
@@ -112,7 +119,7 @@ g_content_type_equals (const char *type1,
 
 /**
  * g_content_type_is_a:
- * @type: a content type string. a content type string.
+ * @type: a content type string. 
  * @supertype: a string.
  *
  * Determines if @type is a subset of @supertype.  
@@ -144,9 +151,11 @@ g_content_type_is_a (const char   *type,
 
 /**
  * g_content_type_is_unknown:
- * @type: a content type string. a content type string.
+ * @type: a content type string. 
+ * 
+ * Checks if the content type is known by GIO.
  * 
- * Returns:
+ * Returns: %TRUE if the type is unknown.
  **/  
 gboolean
 g_content_type_is_unknown (const char *type)
@@ -158,7 +167,9 @@ g_content_type_is_unknown (const char *type)
 
 /**
  * g_content_type_get_description:
- * @type: a content type string. a content type string.
+ * @type: a content type string. 
+ * 
+ * Gets the human readable description of the content type.
  * 
  * Returns: a short description of the content type @type. 
  **/  
@@ -187,7 +198,9 @@ g_content_type_get_description (const char *type)
 
 /**
  * g_content_type_get_mime_type:
- * @type: a content type string. a content type string.
+ * @type: a content type string. 
+ * 
+ * Gets the mime-type for the content type.
  * 
  * Returns: the registered mime-type for the given @type.
  **/  
@@ -212,7 +225,9 @@ g_content_type_get_mime_type (const char   *type)
 
 /**
  * g_content_type_get_icon:
- * @type: a content type string. a content type string.
+ * @type: a content type string.
+ * 
+ * Gets the icon for a content type.
  * 
  * Returns: #GIcon corresponding to the content type.
  **/  
@@ -235,9 +250,11 @@ g_content_type_get_icon (const char   *type)
  * g_content_type_can_be_executable:
  * @type: a content type string.
  * 
- * Returns: %TRUE if the file type corresponds to something that
- * can be executable, %FALSE otherwise. Note that for instance
- * things like textfiles can be executables (i.e. scripts)
+ * Checks if a content type can be executable. Note that for instance
+ * things like text files can be executables (i.e. scripts and batch files).
+ * 
+ * Returns: %TRUE if the file type corresponds to a type that
+ * can be executable, %FALSE otherwise. 
  **/  
 gboolean
 g_content_type_can_be_executable (const char   *type)
@@ -273,9 +290,11 @@ looks_like_text (const guchar *data, gsize data_size)
  * @result_uncertain: a flag indicating the certainty of the 
  * result.
  * 
+ * Guesses the content type based on example data. If the function is 
+ * uncertain, @result_uncertain will be set to %TRUE.
+ * 
  * Returns: a string indicating a guessed content type for the 
- * given data. If the function is uncertain, @result_uncertain 
- * will be set to %TRUE.
+ * given data. 
  **/  
 char *
 g_content_type_guess (const char   *filename,
@@ -310,6 +329,9 @@ g_content_type_guess (const char   *filename,
 /**
  * g_content_types_get_registered:
  * 
+ * Gets a list of strings containing the registered content types on 
+ * the system.
+ * 
  * Returns: #GList of the registered content types.
  **/  
 GList *
diff --git a/gio/gdatainputstream.c b/gio/gdatainputstream.c
index a55e53132..06796ec02 100644
--- a/gio/gdatainputstream.c
+++ b/gio/gdatainputstream.c
@@ -25,6 +25,16 @@
 #include "gdatainputstream.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gdatainputstream
+ * @short_description: Data Input Stream.
+ * @see_also: #GInputStream.
+ * 
+ * Data input stream implements #GInputStream and includes functions for 
+ * reading data directly from an input stream.
+ *
+ **/
+
 struct _GDataInputStreamPrivate {
   GDataStreamByteOrder byte_order;
   GDataStreamNewlineType newline_type;
@@ -116,7 +126,9 @@ g_data_input_stream_init (GDataInputStream *stream)
 
 /**
  * g_data_input_stream_new:
- * @base_stream: a given #GInputStream.
+ * @base_stream: a #GInputStream.
+ * 
+ * Creates a new data input stream for the @base_stream.
  * 
  * Returns: a new #GDataInputStream.
  **/
@@ -156,6 +168,8 @@ g_data_input_stream_set_byte_order (GDataInputStream *stream,
  * g_data_input_stream_get_byte_order:
  * @stream: a given #GDataInputStream.
  * 
+ * Gets the byte order for the data input stream.
+ * 
  * Returns the @stream's current #GDataStreamByteOrder. 
  **/
 GDataStreamByteOrder
@@ -168,7 +182,7 @@ g_data_input_stream_get_byte_order (GDataInputStream *stream)
 
 /**
  * g_data_input_stream_set_newline_type:
- * @stream: a given #GDataInputStream.
+ * @stream: a #GDataInputStream.
  * @type: the type of new line return as #GDataStreamNewlineType.
  * 
  * Sets the newline type for the @stream.
@@ -248,7 +262,6 @@ read_data (GDataInputStream *stream,
  * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 
  * if an error occured.
  **/
-
 guchar
 g_data_input_stream_read_byte (GDataInputStream        *stream,
 			      GCancellable            *cancellable,
@@ -357,6 +370,10 @@ g_data_input_stream_read_uint16 (GDataInputStream        *stream,
  * 
  * In order to get the correct byte order for this read operation, 
  * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order().
+ *
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  *   
  * Returns a signed 32-bit/4-byte value read from the @stream or %0 if 
  * an error occured. 
@@ -399,6 +416,10 @@ g_data_input_stream_read_int32 (GDataInputStream        *stream,
  * 
  * In order to get the correct byte order for this read operation, 
  * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order().
+ *
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * Returns an unsigned 32-bit/4-byte value read from the @stream or %0 if 
  * an error occured. 
@@ -441,6 +462,10 @@ g_data_input_stream_read_uint32 (GDataInputStream        *stream,
  * 
  * In order to get the correct byte order for this read operation, 
  * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order().
+ *
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * Returns a signed 64-bit/8-byte value read from @stream or %0 if 
  * an error occured.  
@@ -483,6 +508,10 @@ g_data_input_stream_read_int64 (GDataInputStream        *stream,
  * 
  * In order to get the correct byte order for this read operation, 
  * see g_data_stream_get_byte_order().
+ *
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * Returns an unsigned 64-bit/8-byte read from @stream or %0 if 
  * an error occured. 
@@ -621,10 +650,15 @@ scan_for_newline (GDataInputStream *stream,
  * @length: a #gsize to get the length of the data read in.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
+ *
+ * Reads a line from the data input stream.
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * Returns a string with the line that was read in. Set @length to 
- * a #gsize to get the length of the read line. This function will 
- * return %NULL on an error.
+ * a #gsize to get the length of the read line. Returns %NULL on an error.
  **/
 char *
 g_data_input_stream_read_line (GDataInputStream        *stream,
diff --git a/gio/gdatainputstream.h b/gio/gdatainputstream.h
index d68be6c45..a096b1b6f 100644
--- a/gio/gdatainputstream.h
+++ b/gio/gdatainputstream.h
@@ -35,6 +35,13 @@ G_BEGIN_DECLS
 #define G_IS_DATA_INPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DATA_INPUT_STREAM))
 #define G_DATA_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DATA_INPUT_STREAM, GDataInputStreamClass))
 
+/**
+ * GDataInputStream:
+ * @parent: a #GBufferedInputStream.
+ *
+ * An implementation of #GBufferedInputStream that allows for high-level 
+ * data manipulation of arbitrary data (including binary operations).
+ **/
 typedef struct _GDataInputStream         GDataInputStream;
 typedef struct _GDataInputStreamClass    GDataInputStreamClass;
 typedef struct _GDataInputStreamPrivate  GDataInputStreamPrivate;
@@ -50,7 +57,7 @@ struct _GDataInputStream
 struct _GDataInputStreamClass
 {
  GBufferedInputStreamClass parent_class;
-
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
@@ -59,12 +66,31 @@ struct _GDataInputStreamClass
   void (*_g_reserved5) (void);
 };
 
+/**
+ * GDataStreamByteOrder:
+ * @G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN: Selects Big Endian byte order. 
+ * @G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN: Selects Little Endian byte order.
+ * @G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN: Selects endianness based on host machine's architecture.
+ *
+ * #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources
+ * across various machine architectures.
+ *
+ **/
 typedef enum  {
   G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN,
   G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN,
   G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN
 } GDataStreamByteOrder;
 
+/** 
+ * GDataStreamNewlineType:
+ * @G_DATA_STREAM_NEWLINE_TYPE_LF: Selects "LF" line endings, common on most modern UNIX platforms.
+ * @G_DATA_STREAM_NEWLINE_TYPE_CR: Selects "CR" line endings.
+ * @G_DATA_STREAM_NEWLINE_TYPE_CR_LF: Selects "CR, LF" line ending, common on Microsoft Windows.
+ * @G_DATA_STREAM_NEWLINE_TYPE_ANY: Selects any line ending type.
+ *
+ * #GDataStreamNewlineType is used when checking for or setting the line endings for a given file.
+ **/
 typedef enum  {
   G_DATA_STREAM_NEWLINE_TYPE_LF,
   G_DATA_STREAM_NEWLINE_TYPE_CR,
diff --git a/gio/gdataoutputstream.c b/gio/gdataoutputstream.c
index 6393d7c82..40f0e7290 100644
--- a/gio/gdataoutputstream.c
+++ b/gio/gdataoutputstream.c
@@ -25,6 +25,18 @@
 #include "gdataoutputstream.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gdataoutputstream
+ * @short_description: Data Output Stream.
+ * @see_also: #GOutputStream.
+ * 
+ * Data output stream implements #GOutputStream and includes functions for 
+ * writing data directly to an output stream.
+ *
+ **/
+
+
+
 struct _GDataOutputStreamPrivate {
   GDataStreamByteOrder byte_order;
 };
@@ -116,6 +128,8 @@ g_data_output_stream_init (GDataOutputStream *stream)
  * g_data_output_stream_new:
  * @base_stream: a #GOutputStream.
  * 
+ * Creates a new data output stream for @base_stream.
+ * 
  * Returns: #GDataOutputStream.
  **/
 GDataOutputStream *
@@ -134,9 +148,11 @@ g_data_output_stream_new (GOutputStream *base_stream)
 
 /**
  * g_data_output_stream_set_byte_order:
- * @stream: a #GDataOutputStream. a #GDataOutputStream.
+ * @stream: a #GDataOutputStream.
  * @order: a %GDataStreamByteOrder.
  * 
+ * Sets the byte order of the data output stream to @order.
+ * 
  **/
 void
 g_data_output_stream_set_byte_order (GDataOutputStream *stream,
@@ -149,9 +165,11 @@ g_data_output_stream_set_byte_order (GDataOutputStream *stream,
 
 /**
  * g_data_output_stream_get_byte_order:
- * @stream: a #GDataOutputStream. a #GDataOutputStream.
+ * @stream: a #GDataOutputStream.
  * 
- * Returns: the %GDataStreamByteOrder for the @stream.
+ * Gets the byte order for the stream.
+ * 
+ * Returns: the #GDataStreamByteOrder for the @stream.
  **/
 GDataStreamByteOrder
 g_data_output_stream_get_byte_order (GDataOutputStream *stream)
@@ -166,7 +184,9 @@ g_data_output_stream_get_byte_order (GDataOutputStream *stream)
  * @data_stream: a #GDataOutputStream.
  * @data: a #guchar.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
+ * @error: a #GError, %NULL to ignore.
+ * 
+ * Puts a byte into the output stream.
  * 
  * Returns: %TRUE if @data was successfully added to the @stream.
  **/
@@ -188,10 +208,12 @@ g_data_output_stream_put_byte (GDataOutputStream     *data_stream,
 
 /**
  * g_data_output_stream_put_int16:
- * @stream: a #GDataOutputStream. a #GDataOutputStream.
+ * @stream: a #GDataOutputStream.
  * @data: a #gint16.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
+ * @error: a #GError, %NULL to ignore.
+ * 
+ * Puts a signed 16-bit integer into the output stream.
  * 
  * Returns: %TRUE if @data was successfully added to the @stream.
  **/
@@ -226,10 +248,12 @@ g_data_output_stream_put_int16 (GDataOutputStream     *stream,
 
 /**
  * g_data_output_stream_put_uint16:
- * @stream: a #GDataOutputStream. a #GDataOutputStream.
+ * @stream: a #GDataOutputStream.
  * @data: a #guint16.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
+ * @error: a #GError, %NULL to ignore.
+ * 
+ * Puts an unsigned 16-bit integer into the output stream.
  * 
  * Returns: %TRUE if @data was successfully added to the @stream.
  **/
@@ -264,10 +288,12 @@ g_data_output_stream_put_uint16 (GDataOutputStream     *stream,
 
 /**
  * g_data_output_stream_put_int32:
- * @stream: a #GDataOutputStream. a #GDataOutputStream.
+ * @stream: a #GDataOutputStream.
  * @data: a #gint32.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
+ * @error: a #GError, %NULL to ignore.
+ * 
+ * Puts a signed 32-bit integer into the output stream.
  * 
  * Returns: %TRUE if @data was successfully added to the @stream.
  **/
@@ -302,10 +328,12 @@ g_data_output_stream_put_int32 (GDataOutputStream     *stream,
 
 /**
  * g_data_output_stream_put_uint32:
- * @stream: a #GDataOutputStream. a #GDataOutputStream.
+ * @stream: a #GDataOutputStream.
  * @data: a #guint32.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
+ * @error: a #GError, %NULL to ignore.
+ * 
+ * Puts an unsigned 32-bit integer into the stream.
  * 
  * Returns: %TRUE if @data was successfully added to the @stream.
  **/
@@ -340,10 +368,12 @@ g_data_output_stream_put_uint32 (GDataOutputStream     *stream,
 
 /**
  * g_data_output_stream_put_int64:
- * @stream: a #GDataOutputStream. a #GDataOutputStream.
+ * @stream: a #GDataOutputStream.
  * @data: a #gint64.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
+ * @error: a #GError, %NULL to ignore.
+ * 
+ * Puts a signed 64-bit integer into the stream.
  * 
  * Returns: %TRUE if @data was successfully added to the @stream.
  **/
@@ -378,10 +408,12 @@ g_data_output_stream_put_int64 (GDataOutputStream     *stream,
 
 /**
  * g_data_output_stream_put_uint64:
- * @stream: a #GDataOutputStream. a #GDataOutputStream.
+ * @stream: a #GDataOutputStream.
  * @data: a #guint64.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
+ * @error: a #GError, %NULL to ignore.
+ * 
+ * Puts an unsigned 64-bit integer into the stream.
  * 
  * Returns: %TRUE if @data was successfully added to the @stream.
  **/
@@ -419,9 +451,11 @@ g_data_output_stream_put_uint64 (GDataOutputStream     *stream,
  * @stream: a #GDataOutputStream.
  * @str: a string.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: a #GError.
+ * @error: a #GError, %NULL to ignore.
  * 
- * Returns: %TRUE if @data was successfully added to the @stream.
+ * Puts a string into the output stream. 
+ * 
+ * Returns: %TRUE if @string was successfully added to the @stream.
  **/
 gboolean
 g_data_output_stream_put_string (GDataOutputStream     *stream,
diff --git a/gio/gdataoutputstream.h b/gio/gdataoutputstream.h
index 94bdfa5c2..00b8cf2a4 100644
--- a/gio/gdataoutputstream.h
+++ b/gio/gdataoutputstream.h
@@ -36,6 +36,13 @@ G_BEGIN_DECLS
 #define G_IS_DATA_OUTPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DATA_OUTPUT_STREAM))
 #define G_DATA_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DATA_OUTPUT_STREAM, GDataOutputStreamClass))
 
+/**
+ * GDataOutputStream:
+ * @parent: a #GBufferedOutputStream.
+ *
+ * An implementation of #GBufferedOutputStream that allows for high-level 
+ * data manipulation of arbitrary data (including binary operations).
+ **/
 typedef struct _GDataOutputStream         GDataOutputStream;
 typedef struct _GDataOutputStreamClass    GDataOutputStreamClass;
 typedef struct _GDataOutputStreamPrivate  GDataOutputStreamPrivate;
@@ -51,7 +58,7 @@ struct _GDataOutputStream
 struct _GDataOutputStreamClass
 {
  GFilterOutputStreamClass parent_class;
-
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gdirectorymonitor.c b/gio/gdirectorymonitor.c
index eb50a958c..c0517c68e 100644
--- a/gio/gdirectorymonitor.c
+++ b/gio/gdirectorymonitor.c
@@ -29,6 +29,15 @@
 #include "gvfs.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gdirectorymonitor
+ * @short_description: Directory Monitor
+ * @see_also: #GFileMonitor.
+ * 
+ * Monitors a directory for changes.
+ *
+ **/
+
 enum {
   CHANGED,
   LAST_SIGNAL
@@ -146,9 +155,11 @@ g_directory_monitor_init (GDirectoryMonitor *monitor)
 
 /**
  * g_directory_monitor_cancel:
- * @monitor:
+ * @monitor: a #GDirectoryMonitor.
+ *
+ * Cancels the monitoring activity on @monitor.
  * 
- * Returns: 
+ * Returns: %TRUE if the monitor was cancelled successfully. %FALSE otherwise.
  **/
 gboolean
 g_directory_monitor_cancel (GDirectoryMonitor* monitor)
@@ -168,8 +179,10 @@ g_directory_monitor_cancel (GDirectoryMonitor* monitor)
 
 /**
  * g_directory_monitor_set_rate_limit:
- * @monitor:
- * @limit_msecs:
+ * @monitor: a #GDirectoryMonitor.
+ * @limit_msecs: an integer to set the limit of the directory monitor in milliseconds.
+ *
+ * Sets the limit of the directory monitor to watch for changes every @limit_msecs milliseconds.
  * 
  **/
 void
@@ -183,9 +196,11 @@ g_directory_monitor_set_rate_limit (GDirectoryMonitor *monitor,
 
 /**
  * g_directory_monitor_is_cancelled:
- * @monitor:
+ * @monitor: a #GDirectoryMonitor.
  * 
- * Returns: 
+ * Checks whether @monitor is cancelled.
+ *
+ * Returns: %TRUE if the monitor on the directory was cancelled. %FALSE otherwise.
  **/
 gboolean
 g_directory_monitor_is_cancelled (GDirectoryMonitor *monitor)
@@ -394,10 +409,14 @@ update_rate_limiter_timeout (GDirectoryMonitor *monitor, guint new_time)
 
 /**
  * g_directory_monitor_emit_event:
- * @monitor:
- * @child:
- * @other_file:
- * @event_type:
+ * @monitor: a #GDirectoryMonitor.
+ * @child: a #GFile.
+ * @other_file: a #GFile.
+ * @event_type: a set of #GFileMonitorEvent flags.
+ * 
+ * Emits the GDirectoryMonitor::changed signal if a change
+ * has taken place. Should be called from directory monitor 
+ * implementations only.
  * 
  **/
 void
diff --git a/gio/gdirectorymonitor.h b/gio/gdirectorymonitor.h
index d4e357307..709c006a8 100644
--- a/gio/gdirectorymonitor.h
+++ b/gio/gdirectorymonitor.h
@@ -39,6 +39,12 @@ G_BEGIN_DECLS
 typedef struct _GDirectoryMonitorClass	 GDirectoryMonitorClass;
 typedef struct _GDirectoryMonitorPrivate GDirectoryMonitorPrivate;
 
+/**
+ * GDirectoryMonitor:
+ * @parent: The parent class. 
+ * 
+ * Implements a monitor on the given #GFile that points to a directory.
+ **/
 struct _GDirectoryMonitor
 {
   GObject parent;
@@ -60,6 +66,7 @@ struct _GDirectoryMonitorClass
   /* Virtual Table */
   gboolean	(*cancel)(GDirectoryMonitor* monitor);
 
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gdrive.c b/gio/gdrive.c
index b953c2c88..26ec192c5 100644
--- a/gio/gdrive.c
+++ b/gio/gdrive.c
@@ -25,6 +25,16 @@
 #include "gsimpleasyncresult.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gdrive
+ * @short_description: Virtual File System drive management.
+ * @include: gio/gdrive.h
+ * 
+ * #GDrive manages drive operations from GVFS, including volume mounting
+ * and ejecting, and getting the drive's name and icon. 
+ * 
+ **/
+
 static void g_drive_base_init (gpointer g_class);
 static void g_drive_class_init (gpointer g_class,
 				 gpointer class_data);
@@ -72,6 +82,13 @@ g_drive_base_init (gpointer g_class)
 
   if (! initialized)
     {
+      /**
+      * GDrive::changed:
+      * @volume: a #GVolume.
+      * 
+      * Emitted when the drive's state has changed.
+      * 
+      **/
       g_signal_new (I_("changed"),
                     G_TYPE_DRIVE,
                     G_SIGNAL_RUN_LAST,
@@ -90,7 +107,7 @@ g_drive_base_init (gpointer g_class)
  * 
  * Returns: string containing @drive's name.
  *
- * The returned string should be freed when no longer needed
+ * The returned string should be freed when no longer needed.
  **/
 char *
 g_drive_get_name (GDrive *drive)
@@ -128,6 +145,8 @@ g_drive_get_icon (GDrive *drive)
  * g_drive_has_volumes:
  * @drive: a #GDrive.
  * 
+ * Checks if a drive has any volumes.
+ * 
  * Returns: %TRUE if @drive contains volumes, %FALSE otherwise.
  **/
 gboolean
@@ -146,7 +165,9 @@ g_drive_has_volumes (GDrive *drive)
  * g_drive_get_volumes:
  * @drive: a #GDrive.
  * 
- * Returns: #GList containing any #GVolume s on the given @drive.
+ * Gets a list of volumes for a drive.
+ * 
+ * Returns: #GList containing any #GVolume<!---->s on the given @drive.
  * NOTE: Fact-check this.
  **/
 GList *
@@ -165,6 +186,8 @@ g_drive_get_volumes (GDrive *drive)
  * g_drive_is_automounted:
  * @drive: a #GDrive.
  * 
+ * Checks if a drive was automatically mounted, e.g. by HAL.
+ * 
  * Returns: %TRUE if the drive was automounted. %FALSE otherwise.
  **/
 gboolean
@@ -183,6 +206,8 @@ g_drive_is_automounted (GDrive *drive)
  * g_drive_can_mount:
  * @drive: a #GDrive.
  * 
+ * Checks if a drive can be mounted.
+ * 
  * Returns: %TRUE if the @drive can be mounted. %FALSE otherwise.
  **/
 gboolean
@@ -204,6 +229,8 @@ g_drive_can_mount (GDrive *drive)
  * g_drive_can_eject:
  * @drive: pointer to a #GDrive.
  * 
+ * Checks if a drive can be ejected.
+ * 
  * Returns: %TRUE if the @drive can be ejected. %FALSE otherwise.
  **/
 gboolean
@@ -225,9 +252,11 @@ g_drive_can_eject (GDrive *drive)
  * g_drive_mount:
  * @drive: a #GDrive.
  * @mount_operation: a #GMountOperation.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback.
  * @user_data: a #gpointer.
  * 
+ * Mounts a drive.
  * 
  **/
 void
@@ -262,6 +291,8 @@ g_drive_mount (GDrive         *drive,
  * @result: a #GAsyncResult.
  * @error: a #GError.
  * 
+ * Finishes mounting a drive.
+ * 
  * Returns: %TRUE, %FALSE if operation failed.
  **/
 gboolean
@@ -288,9 +319,12 @@ g_drive_mount_finish (GDrive               *drive,
 /**
  * g_drive_eject:
  * @drive: a #GDrive.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback.
  * @user_data: a #gpointer.
  * 
+ * Ejects a drive.
+ * 
  **/
 void
 g_drive_eject (GDrive         *drive,
@@ -322,6 +356,8 @@ g_drive_eject (GDrive         *drive,
  * @result: a #GAsyncResult.
  * @error: a #GError.
  * 
+ * Finishes ejecting a drive.
+ * 
  * Returns: %TRUE if the drive has been ejected successfully,
  * %FALSE otherwise.
  **/
diff --git a/gio/gdrive.h b/gio/gdrive.h
index 7a0413ea9..4770b132a 100644
--- a/gio/gdrive.h
+++ b/gio/gdrive.h
@@ -34,6 +34,24 @@ G_BEGIN_DECLS
 #define G_IS_DRIVE(obj)	       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_DRIVE))
 #define G_DRIVE_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_DRIVE, GDriveIface))
 
+/**
+ * GDriveIface:
+ * @g_iface: The parent interface.
+ * @changed: Signal emitted when the drive is changed.
+ * @get_name: Returns the name for the given #GDrive.
+ * @get_icon: Returns a #GIcon for the given #GDrive.
+ * @has_volumes: Returns %TRUE if the #GDrive has mountable volumes.
+ * @get_volumes: Returns a #GList of volumes for the #GDrive.
+ * @is_automounted: returns %TRUE if the #GDrive was automounted.
+ * @can_mount: Returns %TRUE if the #GDrive can be mounted.
+ * @can_eject: Returns %TRUE if the #GDrive can be ejected.
+ * @mount: Mounts a given #GDrive.
+ * @mount_finish: Finishes a mount operation.
+ * @eject: Ejects a #GDrive.
+ * @eject_finish: Finishes an eject operation.
+ * 
+ * Interface for creating #GDrive implementations.
+ */ 
 typedef struct _GDriveIface    GDriveIface;
 
 struct _GDriveIface
diff --git a/gio/gfile.c b/gio/gfile.c
index 617422f17..f833b589d 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -34,6 +34,39 @@
 #include "gpollfilemonitor.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gfile
+ * @short_description: File and Directory Handling
+ * @see_also: #GFileInfo, #GFileEnumerator
+ * @include: gio/gfile.h
+ * 
+ * #GFile is a high level abstraction for manipulating files on a 
+ * virtual file system. #GFile<!-- -->s are lightweight, immutable 
+ * objects that do no I/O upon creation. It is necessary to understand that
+ * #GFile objects do not represent files, merely a handle to a file. All
+ * file I/O is implemented as streams (see #GInputStream and #GOutputStream).
+ * 
+ * To construct a #GFile, you can use: 
+ * g_file_new_for_path() if you have a path.
+ * g_file_new_for_uri() if you have a URI.
+ * 
+ * You can move through the filesystem with #GFile handles with
+ * g_file_get_parent() to get a handle to the parent directory.
+ * g_file_get_child() to get a handle to a child within a directory.
+ * g_file_resolve_relative_path() to resolve a relative path between
+ * two #GFile<!-- -->s.
+ * 
+ * Many #GFile operations have both synchronous (or blocking) and 
+ * asynchronous (non-blocking) versions to suit your application. 
+ * Asynchronous versions of synchronous functions simply have _async()
+ * appended to their function names. The asynchronous I/O functions 
+ * call a #GAsyncReadyCallback which is then used to finalize the operation, 
+ * which is then passed to the function's matching _finish() operation.
+ * 
+ * 
+ *
+ **/
+
 static void g_file_base_init (gpointer g_class);
 static void g_file_class_init (gpointer g_class,
 			       gpointer class_data);
@@ -186,8 +219,10 @@ g_file_base_init (gpointer g_class)
  * g_file_is_native:
  * @file: input #GFile.
  *
- * Returns: %TRUE if file is native.
- * TODO: Explain what "native" means.
+ * Checks to see if a file is native to the system.
+ *
+ * Returns: %TRUE if file is native. (If the file is native
+ * to the system, e.g. located in file:///).
  **/
 gboolean
 g_file_is_native (GFile *file)
@@ -207,6 +242,8 @@ g_file_is_native (GFile *file)
  * @file: input #GFile.
  * @uri_scheme: a string containing a URI scheme.
  *
+ * Checks to see if a #GFile has a given URI scheme.
+ *
  * Returns: %TRUE if #GFile's backend supports the
  * given URI scheme, FALSE if URI scheme is %NULL,
  * not supported, or #GFile is invalid.
@@ -230,12 +267,13 @@ g_file_has_uri_scheme (GFile *file,
  * g_file_get_uri_scheme:
  * @file: input #GFile.
  *
+ * Gets the URI scheme for a #GFile.
+ *
  * Returns: string to the URI scheme for the given #GFile.  
  * RFC 3986 decodes the scheme as:
  * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] 
- * Popular schemes include "file", "http", "svn", etc.
- *
- * The returned string should be freed when no longer needed.
+ * Common schemes include "file", "http", "svn", etc. The returned 
+ * string should be freed when no longer needed.
  **/
 char *
 g_file_get_uri_scheme (GFile *file)
@@ -254,10 +292,11 @@ g_file_get_uri_scheme (GFile *file)
  * g_file_get_basename:
  * @file: input #GFile.
  *
- * Returns: string containing the #GFile's base name, or %NULL if given
- * #GFile is invalid. 
+ * Gets the basename for a given #GFile.
  *
- * The returned string should be freed when no longer needed
+ * Returns: string containing the #GFile's base name, or %NULL if given
+ * #GFile is invalid. The returned string should be freed when no longer 
+ * needed.
  **/
 char *
 g_file_get_basename (GFile *file)
@@ -275,10 +314,10 @@ g_file_get_basename (GFile *file)
  * g_file_get_path:
  * @file: input #GFile.
  *
- * Returns: string containing the #GFile's path, or %NULL if given
- * #GFile is invalid. 
- * 
- * The returned string should be freed when no longer needed
+ * Gets the current path within a #GFile. 
+ *
+ * Returns: string containing the #GFile's path, or %NULL if given #GFile is
+ * invalid. The returned string should be freed when no longer needed.
  **/
 char *
 g_file_get_path (GFile *file)
@@ -296,10 +335,11 @@ g_file_get_path (GFile *file)
  * g_file_get_uri:
  * @file: input #GFile.
  *
+ * Gets a URI for the path within a #GFile.
+ *
  * Returns: string to the #GFile's Universal Resource Identifier (URI), 
- * or %NULL if given #GFile is invalid. 
- * 
- * The returned string should be freed when no longer needed
+ * or %NULL if given #GFile is invalid. The returned string should be freed 
+ * when no longer needed.
  **/
 char *
 g_file_get_uri (GFile *file)
@@ -317,10 +357,10 @@ g_file_get_uri (GFile *file)
  * g_file_parse_name:
  * @file: input #GFile.
  *
- * Returns: string to the GFile's parsed name, or %NULL if given
- * GFile is invalid. 
- * 
- * The returned string should be freed when no longer needed
+ * Gets the parsed name for the #GFile.
+ *
+ * Returns: string to the #GFile's parsed name, or %NULL if given
+ * #GFile is invalid. The returned string should be freed when no longer needed.
  **/
 char *
 g_file_get_parse_name (GFile *file)
@@ -338,6 +378,10 @@ g_file_get_parse_name (GFile *file)
  * g_file_dup:
  * @file: input #GFile.
  *
+ * Duplicates a #GFile handle. This operation does not duplicate 
+ * the actual file or directory represented by the #GFile; see g_file_copy()
+ * if attempting to copy a file. 
+ *
  * Returns: #GFile that is a duplicate of the given #GFile, 
  * or %NULL if given #GFile is invalid. 
  **/
@@ -357,7 +401,9 @@ g_file_dup (GFile *file)
  * g_file_hash:
  * @file: #gconstpointer to a #GFile.
  *
- * Returns: 0 if @file is not a #GFile, otherwise a 
+ * Creates a hash of a #GFile.
+ *
+ * Returns: 0 if @file is not a valid #GFile, otherwise a 
  * guint containing a hash of the #GFile. This function
  * is intended for easily hashing a #GFile to add to a 
  * #GHashTable or similar data structure.
@@ -380,6 +426,8 @@ g_file_hash (gconstpointer file)
  * @file1: the first #GFile.
  * @file2: the second #GFile.
  *
+ * Checks equality of two given #GFile<!-- -->s
+ *
  * Returns: %TRUE if @file1 and @file2 are equal.
  * %FALSE if either is not a #GFile.
  **/
@@ -405,12 +453,12 @@ g_file_equal (GFile *file1,
  * g_file_get_parent:
  * @file: input #GFile.
  *
- * Returns: a #GFile structure to the parent of the given
- * #GFile. 
- * 
- * This function should return the parent directory of the given
- * @file. If the @file represents the root directory of the 
+ * Gets the parent directory for the @file. 
+ * If the @file represents the root directory of the 
  * file system, then %NULL will be returned.
+ *
+ * Returns: a #GFile structure to the parent of the given
+ * #GFile or %NULL. 
  **/
 GFile *
 g_file_get_parent (GFile *file)
@@ -429,6 +477,9 @@ g_file_get_parent (GFile *file)
  * @file: input #GFile.
  * @name: string containing the child's name.
  *
+ * Gets a specific child of @file with name equal to @name if
+ * it exists.
+ *
  * Returns: a #GFile to a child specified by 
  * @name or %NULL if @name is %NULL, or the specified
  * child doesn't exist.
@@ -448,9 +499,13 @@ g_file_get_child (GFile *file,
  * @file: input #GFile.
  * @display_name: string to a possible child.
  * @error: #GError.
+ *
+ * Gets the child of @file for a given @display_name. If
+ * this function fails, it returns %NULL and @error will be 
+ * set with %G_IO_ERROR_INVALID_FILENAME.
  * 
- * Returns: %NULL if @display_name is %NULL, #GFile to 
- * the specified child.
+ * Returns: a #GFile to the specified child, or 
+ * %NULL if @display_name is %NULL.  
  **/
 GFile *
 g_file_get_child_for_display_name (GFile *file,
@@ -472,8 +527,9 @@ g_file_get_child_for_display_name (GFile *file,
  * @parent: input #GFile.
  * @descendant: input #GFile.
  * 
- * Returns: %FALSE if either the @parent or @descendant 
- * is invalid. %TRUE if the @descendent's parent is @parent.
+ * Checks whether @parent contains the specified @descendent.
+ * 
+ * Returns:  %TRUE if the @descendent's parent is @parent. %FALSE otherwise.
  **/
 gboolean
 g_file_contains_file (GFile *parent,
@@ -497,10 +553,10 @@ g_file_contains_file (GFile *parent,
  * @parent: input #GFile.
  * @descendant: input #GFile.
  *
- * Returns: string with the relative path from 
- * @descendant to @parent. 
+ * Gets the path for @descendant relative to @parent. 
  *
- * The returned string should be freed when no longer needed
+ * Returns: string with the relative path from @descendant to @parent. 
+ * The returned string should be freed when no longer needed.
  **/
 char *
 g_file_get_relative_path (GFile *parent,
@@ -524,6 +580,8 @@ g_file_get_relative_path (GFile *parent,
  * @file: input #GFile.
  * @relative_path: a given relative path string.
  *
+ * Resolves a relative path for @file to an absolute path.
+ *
  * Returns: #GFile to the resolved path. %NULL if @relative_path is NULL.
  * or if @file is invalid.
  **/
@@ -544,19 +602,24 @@ g_file_resolve_relative_path (GFile *file,
 /**
  * g_file_enumerate_children:
  * @file: input #GFile.
- * @attributes: a string.
- * @flags: #GFileQueryInfoFlags field.
+ * @attributes: a string containing a #GFileAttributeInfo query.
+ * @flags: a set of #GFileQueryInfoFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
+ *
+ * Gets a #GFileEnumerator for the children of @file that match @attributes, 
+ * where attributes is a #GFileAttributeInfo query string (e.g. "std:type", "std:*").
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ *
+ * If the #GFileIface for the given @file does not support #GFileEnumerator,
+ * then %NULL will be returned and the error %G_IO_ERROR_NOT_SUPPORTED will 
+ * be set in @error.
  * 
- * Returns: %NULL if cancelled or if #GFile's backend doesn't
- * support #GFileEnumerator. Returns a #GFileEnumerator if successful.
+ * Returns: A #GFileEnumerator if successful. %NULL if cancelled or if #GFile's 
+ * backend doesn't support #GFileEnumerator. 
  **/
 GFileEnumerator *
 g_file_enumerate_children (GFile *file,
@@ -590,20 +653,18 @@ g_file_enumerate_children (GFile *file,
 /**
  * g_file_enumerate_children_async:
  * @file: input #GFile.
- * @attributes: a string.
+ * @attributes: a string containing a #GFileAttributeInfo query.
  * @flags: a set of #GFileQueryInfoFlags.
- * @io_priority: the io priority of the request. the io priority of the request.
+ * @io_priority: the io priority of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback.
  * @user_data: a #gpointer.
  *
- * Asynchronously enumerates the children of the given @file. 
+ * Asynchronously gets a #GFileEnumerator for the children of @file that match @attributes, 
+ * where attributes is a #GFileAttributeInfo query string (e.g. "std:type", "std:*"). For the 
+ * synchronous version of this function, see g_file_enumerate_children().
  * 
- * If @cancellable is not %NULL, then the operation can be cancelled by
- * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * To finish this asynchronous operation, see g_file_enumerate_children_finish().
  *
  **/
 void
@@ -635,6 +696,15 @@ g_file_enumerate_children_async (GFile                      *file,
  * @res: a #GAsyncResult.
  * @error: a #GError.
  * 
+ * If @cancellable was not %NULL when g_file_enumerate_children_async() was called, 
+ * then the operation could have been cancelled by triggering the cancellable object 
+ * from another thread. If the operation was cancelled, the @error will be set to 
+ * %G_IO_ERROR_CANCELLED and this function will return %NULL. 
+ *
+ * If the #GFileIface for the given @file does not support enumerating files,
+ * then %NULL will be returned and the error %G_IO_ERROR_NOT_SUPPORTED will 
+ * be set in @error.
+ * 
  * Returns: a #GFileEnumerator or %NULL if an error occurred.
  **/
 GFileEnumerator *
@@ -662,16 +732,18 @@ g_file_enumerate_children_finish  (GFile                      *file,
 /**
  * g_file_query_info:
  * @file: input #GFile.
- * @attributes: a string.
+ * @attributes: a string containing a #GFileAttributeInfo query.
  * @flags: a set of #GFileQueryInfoFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError.
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
+ * If the #GFileIface for the given @file does not support querying file information,
+ * then %NULL will be returned and the error %G_IO_ERROR_NOT_SUPPORTED will 
+ * be set in @error.
  * 
  * Returns: a #GFileInfo for the given @file, or %NULL on error.
  **/
@@ -705,7 +777,7 @@ g_file_query_info (GFile *file,
 /**
  * g_file_query_info_async:
  * @file: input #GFile.
- * @attributes: a string.
+ * @attributes: a string containing a #GFileAttributeInfo query.
  * @flags: a set of #GFileQueryInfoFlags.
  * @io_priority: the io priority of the request. the io priority of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
@@ -714,9 +786,9 @@ g_file_query_info (GFile *file,
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
+ * 
+ * To finish this asynchronous operation, see g_file_query_info_finish().
  * 
  **/
 void
@@ -745,13 +817,21 @@ g_file_query_info_async (GFile                      *file,
 /**
  * g_file_query_info_finish:
  * @file: input #GFile.
- * @error: a #GAsyncResult. 
+ * @res: a #GAsyncResult. 
  * @error: a #GError. 
  * 
- * Finishes an asynchronous file info query. If the operation failed, 
- * returns %NULL and set @error appropriately if present.
+ * Finishes an asynchronous file info query. 
+ *
+ * If @cancellable was not %NULL when g_file_query_info_async() was called, 
+ * then the operation could have been cancelled by triggering the cancellable object 
+ * from another thread. If the operation was cancelled, the @error will be set to 
+ * %G_IO_ERROR_CANCELLED and this function will return %NULL. 
+ * 
+ * If the #GFileIface for the given @file does not support querying file information,
+ * then %NULL will be returned and the error %G_IO_ERROR_NOT_SUPPORTED will 
+ * be set in @error.
  * 
- * Returns: #GFileInfo for given @file or %NULL.
+ * Returns: #GFileInfo for given @file or %NULL on error.
  **/
 GFileInfo *
 g_file_query_info_finish (GFile                      *file,
@@ -777,17 +857,19 @@ g_file_query_info_finish (GFile                      *file,
 /**
  * g_file_query_filesystem_info:
  * @file: input #GFile.
- * @attributes: a string. 
+ * @attributes: a string containing a #GFileAttributeInfo query.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @error: a #GError. 
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
- * Returns: a #GFileInfo or %NULl if there was an error.
+ * If the #GFileIface for the given @file does not support querying file system 
+ * information, then %NULL will be returned and the error 
+ * %G_IO_ERROR_NOT_SUPPORTED will be set in @error.
+ * 
+ * Returns: a #GFileInfo or %NULL if there was an error.
  **/
 GFileInfo *
 g_file_query_filesystem_info (GFile *file,
@@ -820,14 +902,18 @@ g_file_query_filesystem_info (GFile *file,
  * @file: input #GFile.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @error: a #GError. 
+ *
+ * Gets a #GVolume for the #GFile. 
+ *
+ * If the #GFileIface for @file does not have a volume (e.g. possibly a 
+ * remote share), @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL
+ * will be returned.
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
- * Returns: a #GVolume where the @file is located.
+ * Returns: a #GVolume where the @file is located or %NULL on error.
  **/
 GVolume *
 g_file_find_enclosing_volume (GFile *file,
@@ -860,15 +946,16 @@ g_file_find_enclosing_volume (GFile *file,
  * @error: a #GError.
  *
  * Reads a whole file into a #GFileInputStream. Fails returning %NULL if 
- * given #GFile points to a directory.
+ * given #GFile points to a directory. 
+ *
+ * If the #GFileIface for @file does not support reading files, then
+ * @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will be returned. 
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
- * Returns: #GFileInputStream or %NULL.
+ * Returns: #GFileInputStream or %NULL on error.
  **/
 GFileInputStream *
 g_file_read (GFile *file,
@@ -900,12 +987,13 @@ g_file_read (GFile *file,
  * @file: input #GFile.
  * @flags: a set of #GFileCreateFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
+ *
+ * If the #GFileIface for @file does not support appending to files, then
+ * @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will be returned. 
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * Returns: a #GFileOutputStream.
  **/
@@ -941,12 +1029,13 @@ g_file_append_to (GFile *file,
  * @flags: a set of #GFileCreateFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
- * 
+ *
+ * If the #GFileIface for @file does not support creating files, then
+ * @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will be returned. 
+ *
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * Returns: a #GFileOutputStream for the newly created file, or 
  * %NULL on error.
@@ -984,12 +1073,15 @@ g_file_create (GFile *file,
  * @make_backup: a #gboolean.
  * @flags: a set of #GFileCreateFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
+ *
+ * If the #GFileIface for @file does not support streaming operations, then
+ * @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will be returned. 
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
+ * @etag will replace the entity tag for the current file.
  * 
  * Returns: a #GFileOutputStream or %NULL on error. If @make_backup is %TRUE, 
  * this function will attempt to make a backup of the current file.
@@ -1030,19 +1122,14 @@ g_file_replace (GFile *file,
 /**
  * g_file_read_async:
  * @file: input #GFile.
- * @io_priority: the io priority of the request. the io priority of the request. 
+ * @io_priority: the io priority of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback.
  * @user_data: a #gpointer. 
- * 
- * If @cancellable is not %NULL, then the operation can be cancelled by
- * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
  *
  * Asynchronously reads @file. For the synchronous version of this function, 
  * see g_file_read().
+ *
  **/
 void
 g_file_read_async (GFile                  *file,
@@ -1066,10 +1153,20 @@ g_file_read_async (GFile                  *file,
 /**
  * g_file_read_finish:
  * @file: input #GFile.
- * @error: a #GAsyncResult. 
+ * @res: a #GAsyncResult. 
  * @error: a #GError. 
+ *
+ * Finishes an asynchronous file read operation started with 
+ * g_file_read_async(). 
+ *  
+ * If the #GFileIface for @file does not support streaming operations, then
+ * @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will be returned. 
+ *
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.  
  * 
- * Returns: a #GFileInputStream or %NULL if there was an error.
+ * Returns: a #GFileInputStream or %NULL on error.
  **/
 GFileInputStream *
 g_file_read_finish (GFile                  *file,
@@ -1107,9 +1204,7 @@ g_file_read_finish (GFile                  *file,
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  **/
 void
@@ -1139,7 +1234,9 @@ g_file_append_to_async (GFile                      *file,
  * @res: #GAsyncResult
  * @error: a #GError. 
  * 
- * Returns: a valid #GFileOutputStream or %NULL upon error.
+ * Finishes appending to a file started with g_file_append_to_async().
+ * 
+ * Returns: a valid #GFileOutputStream or %NULL on error.
  **/
 GFileOutputStream *
 g_file_append_to_finish (GFile                      *file,
@@ -1176,9 +1273,7 @@ g_file_append_to_finish (GFile                      *file,
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  *
  **/
 void
@@ -1205,9 +1300,11 @@ g_file_create_async (GFile                      *file,
 /**
  * g_file_create_finish:
  * @file: input #GFile.
- * @error: a #GAsyncResult. 
+ * @res: a #GAsyncResult. 
  * @error: a #GError. 
  * 
+ * Finishes creating a file started with g_file_create_async().
+ * 
  * Returns: a #GFileOutputStream.
  **/
 GFileOutputStream *
@@ -1248,9 +1345,7 @@ g_file_create_finish (GFile                      *file,
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  **/
 void
@@ -1281,11 +1376,12 @@ g_file_replace_async (GFile                      *file,
 /**
  * g_file_replace_finish:
  * @file: input #GFile.
- * @error: a #GAsyncResult. 
+ * @res: a #GAsyncResult. 
  * @error: a #GError. 
  * 
  * Finishes replacing the contents of the file started by 
- * g_file_replace_async().
+ * g_file_replace_async(). This is typically called within 
+ * a #GAsyncReadyCallback.
  * 
  * Returns: a #GFileOutputStream, or %NULL if an error has occured.
  **/
@@ -1717,6 +1813,7 @@ file_copy_fallback (GFile                  *source,
  * @progress_callback_data: userdata to pass to @progress_callback
  * @error: #GError to set on error
  * 
+ * <!-- Source Friendly Version
  * List of possible errors resulting from g_file_copy():
  * source    dest    flags   res
  *  -        *       *       G_IO_ERROR_NOT_FOUND
@@ -1729,6 +1826,38 @@ file_copy_fallback (GFile                  *source,
  *  dir      *       0       G_IO_ERROR_EXISTS
  *  dir      dir     overwr  G_IO_ERROR_WOULD_MERGE
  *  dir      file    overwr  G_IO_ERROR_WOULD_RECURSE
+ * Docbook version below -->
+ * 
+ * Copies a file or directory from @source to @destination, with the given @flags. 
+ * @flags should be set to %0 if not used. This operation may fail, and @error will 
+ * be set appropriately with the given error result (see the following table). 
+ * File copies are always asynchronous. 
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
+ * If @progress_callback is not %NULL, then the operation can be monitored by
+ * setting this to a #GFileProgressCallback function. @progress_callback_data
+ * will be passed to this function.
+ * 
+ * <table>
+ * <title>g_file_copy() Error Conditions</title>
+ * <tgroup cols='4' align='left'><thead>
+ * <row><entry>Source</entry><entry>Destination</entry><entry>Flags</entry><entry>Results in</entry></row>
+ * </thead><tbody>
+ * <row><entry>%NULL</entry><entry>Anything</entry><entry>Anything</entry><entry>%G_IO_ERROR_NOT_FOUND</entry></row>
+ * <row><entry>File</entry><entry>%NULL</entry><entry>Anything</entry><entry>No Error</entry></row>
+ * <row><entry>File</entry><entry>Anything</entry><entry>0</entry><entry>%G_IO_ERROR_EXISTS</entry></row>
+ * <row><entry>File</entry><entry>File</entry><entry>%G_FILE_COPY_OVERWRITE</entry><entry>No Error</entry></row>
+ * <row><entry>File</entry><entry>Directory</entry><entry>%G_FILE_COPY_OVERWRITE</entry><entry>%G_IO_ERROR_IS_DIRECTORY</entry></row>
+ * <row><entry>Directory</entry><entry>%NULL</entry><entry>Anything</entry><entry>%G_IO_ERROR_WOULD_RECURSE</entry></row>
+ * <row><entry>Directory</entry><entry>Anything</entry><entry>0</entry><entry>%G_IO_ERROR_EXISTS</entry></row>
+ * <row><entry>Directory</entry><entry>Directory</entry><entry>%G_FILE_COPY_OVERWRITE</entry><entry>%G_IO_ERROR_IS_DIRECTORY</entry></row>
+ * <row><entry>Directory</entry><entry>File</entry><entry>%G_FILE_COPY_OVERWRITE</entry><entry>%G_IO_ERROR_WOULD_RECURSE</entry></row>
+ * </tbody>
+ * </tgroup>
+ * </table>
  * 
  * Returns: %TRUE on success, %FALSE otherwise.
  **/
@@ -1779,17 +1908,17 @@ g_file_copy (GFile                  *source,
 
 /**
  * g_file_move:
- * @source: GFile* pointing to the source location.
- * @destination: GFile* pointing to the destination location.
- * @flags: GFileCopyFlags enum.
+ * @source: #GFile pointing to the source location.
+ * @destination: #GFile pointing to the destination location.
+ * @flags: #GFileCopyFlags enum.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @progress_callback: GFileProgressCallback function for updates.
  * @progress_callback_data: gpointer to user data for the callback function.
- * @error: GError for returning error conditions.
+ * @error: #GError for returning error conditions.
  *
  * List of possible returns from g_file_move() with given source,
  * destination, and flags:
- *
+ * <!-- Source version
  * source   dest    flags   results in
  * -        *       *       G_IO_ERROR_NOT_FOUND
  * file     -       *       ok
@@ -1801,7 +1930,34 @@ g_file_copy (GFile                  *source,
  * dir      *       0       G_IO_ERROR_EXISTS
  * dir      dir     overwr  G_IO_ERROR_WOULD_MERGE
  * dir      file    overwr  ok || G_IO_ERROR_WOULD_RECURSE
- *
+ * Pretty Docbook version -->
+ * <table>
+ * <title>g_file_move() Error Conditions</title>
+ * <tgroup cols='4' align='left'><thead>
+ * <row><entry>Source</entry><entry>Destination</entry>
+ * <entry>Flags</entry><entry>Results in</entry></row>
+ * </thead><tbody>
+ * <row><entry> %NULL </entry><entry> Anything </entry>
+ * <entry> Anything </entry><entry> %G_IO_ERROR_NOT_FOUND </entry></row>
+ * <row><entry> File </entry><entry> %NULL </entry>
+ * <entry> Anything </entry><entry> No Error </entry></row>
+ * <row><entry> File </entry><entry> Anything </entry>
+ * <entry> 0 </entry><entry> %G_IO_ERROR_EXISTS </entry></row>
+ * <row><entry> File </entry><entry> File </entry>
+ * <entry> %G_FILE_COPY_OVERWRITE </entry><entry> No Error </entry></row>
+ * <row><entry> File </entry><entry> Directory </entry>
+ * <entry> %G_FILE_COPY_OVERWRITE </entry><entry> %G_IO_ERROR_IS_DIRECTORY </entry></row>
+ * <row><entry> Directory </entry><entry> %NULL </entry>
+ * <entry> Anything </entry><entry> No Error or %G_IO_ERROR_WOULD_RECURSE </entry></row>
+ * <row><entry> Directory </entry><entry> Anything </entry>
+ * <entry> 0 </entry><entry> %G_IO_ERROR_EXISTS </entry></row>
+ * <row><entry> Directory </entry><entry> Directory </entry>
+ * <entry> %G_FILE_COPY_OVERWRITE </entry><entry> %G_IO_ERROR_IS_DIRECTORY </entry></row>
+ * <row><entry> Directory </entry><entry> File </entry>
+ * <entry> %G_FILE_COPY_OVERWRITE </entry><entry> No Error or %G_IO_ERROR_WOULD_RECURSE </entry></row>
+ * </tbody>
+ * </tgroup>
+ * </table>
  * Returns: %TRUE on successful move, %FALSE otherwise.
  **/
 gboolean
@@ -1858,6 +2014,10 @@ g_file_move (GFile                  *source,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: %TRUE on successful creation, %FALSE otherwise.
  **/
 gboolean
@@ -1892,6 +2052,10 @@ g_file_make_directory (GFile *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise.
  **/
 gboolean
@@ -1935,6 +2099,12 @@ g_file_make_symbolic_link (GFile *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
+ * Deletes a file.
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: %TRUE if the file was deleted. %FALSE otherwise.
  **/
 gboolean
@@ -1964,14 +2134,18 @@ g_file_delete (GFile *file,
 
 /**
  * g_file_trash:
- * @file: GFile to location to send to trash.
+ * @file: #GFile to send to trash.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @error: GError for possible failures.
+ * @error: a #GError.
  *
- * This function sends the object to the virtual "Trash" location. If the
- * GFile interface does not have a corresponding "Trash" location, this function 
- * returns %FALSE, and will set @error appropriately. 
+ * Sends @file to the virtual file system "Trash" location. If the
+ * virtual file system does not have support having a "Trash" location, 
+ * %FALSE will be returned, and @error will be set to %G_IO_ERROR_NOT_SUPPORTED. 
  *
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: %TRUE on successful trash, %FALSE otherwise.
  **/
 gboolean
@@ -2006,9 +2180,15 @@ g_file_trash (GFile *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
+ * Sets the display name for @file. If the display name contains invalid
+ * characters, @error will be set to %G_IO_ERROR_INVALID_ARGUMENT. For the 
+ * asynchronous version of this function, see g_file_set_display_name_async().
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: a #GFile, or %NULL if there was an error.
- * For the asynchronous version of this function, see 
- * g_file_set_display_name_async().
  **/
 GFile *
 g_file_set_display_name (GFile                  *file,
@@ -2053,9 +2233,7 @@ g_file_set_display_name (GFile                  *file,
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  **/
 void
@@ -2083,9 +2261,11 @@ g_file_set_display_name_async (GFile                      *file,
 /**
  * g_file_set_display_name_finish:
  * @file: input #GFile.
- * @error: a #GAsyncResult. 
+ * @res: a #GAsyncResult. 
  * @error: a #GError. 
  * 
+ * Finishes setting a display name started with g_file_set_display_name_async().
+ * 
  * Returns: a #GFile or %NULL on error.
  **/
 GFile *
@@ -2115,6 +2295,10 @@ g_file_set_display_name_finish (GFile                      *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: the type and full attribute name of all the attributes that
  * the file can set. This doesn't mean setting it will always succeed though,
  * you might get an access failure, or some specific file may not support a
@@ -2162,6 +2346,10 @@ g_file_query_settable_attributes (GFile                      *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: a #GFileAttributeInfoList of attribute namespaces 
  * where the user can create their own attribute names, such 
  * as extended attributes.
@@ -2206,13 +2394,20 @@ g_file_query_writable_namespaces (GFile                      *file,
  * g_file_set_attribute:
  * @file: input #GFile.
  * @attribute: a string containing the attribute's name.
- * @value: #GFileAttributeValue
- * @flags: #GFileQueryInfoFlags
+ * @value: a set of #GFileAttributeValue.
+ * @flags: a set of #GFileQueryInfoFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
- * Returns: %TRUE if the attribute was correctly set, %FALSE
- * otherwise.
+ * Sets an attribute in the file with attribute name @attribute to @value.
+ * If setting attributes is not suppored by the #GFileIface for @file, 
+ * then @error will be set to %G_IO_ERROR_NOT_SUPPORTED.
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
+ * Returns: %TRUE if the attribute was set, %FALSE otherwise.
  **/
 gboolean
 g_file_set_attribute (GFile                  *file,
@@ -2251,9 +2446,13 @@ g_file_set_attribute (GFile                  *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
- * Tries to set all attributes in the GFileInfo on the target values, not stopping
+ * Tries to set all attributes in the #GFileInfo on the target values, not stopping
  * on the first error.
  * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: %TRUE if there was any error, and @error will be set to
  * the first error. Error on particular fields are flagged by setting the
  * "status" field in the attribute value to %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING.
@@ -2330,14 +2529,12 @@ g_file_real_set_attributes_from_info (GFile                      *file,
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: a #gpointer.
  *
- * Asynchronously sets the attributes of @file with @info and @flags.
+ * Asynchronously sets the attributes of @file with @info.
  * For the synchronous version of this function, see g_file_set_attributes(). 
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  **/
 void
@@ -2366,6 +2563,8 @@ g_file_set_attributes_async (GFile                      *file,
  * @info: a #GFileInfo.
  * @error: a #GError. 
  * 
+ * Finishes setting an attribute started in g_file_set_attributes_async().
+ * 
  * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise.
  **/
 gboolean
@@ -2395,8 +2594,14 @@ g_file_set_attributes_finish (GFile                      *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
- * Returns: %TRUE if the @attribute was successfully set to @value 
- * in the @file, %FALSE otherwise.
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. If
+ * @attribute is of a different type, this operation will fail.
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
+ * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
  **/
 gboolean
 g_file_set_attribute_string (GFile                  *file,
@@ -2414,7 +2619,7 @@ g_file_set_attribute_string (GFile                  *file,
 }
 
 /**
- * g_file_attribute_byte_string:
+ * g_file_set_attribute_byte_string:
  * @file: input #GFile.
  * @attribute: a string containing the attribute's name.
  * @value: a string containing the attribute's new value.
@@ -2422,6 +2627,13 @@ g_file_set_attribute_string (GFile                  *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. If
+ * @attribute is of a different type, this operation will fail, returning %FALSE. 
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: %TRUE if the @attribute was successfully set to @value 
  * in the @file, %FALSE otherwise.
  **/
@@ -2449,6 +2661,13 @@ g_file_set_attribute_byte_string  (GFile                  *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. If
+ * @attribute is of a different type, this operation will fail.
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: %TRUE if the @attribute was successfully set to @value 
  * in the @file, %FALSE otherwise.
  **/
@@ -2476,6 +2695,13 @@ g_file_set_attribute_uint32 (GFile                  *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. If
+ * @attribute is of a different type, this operation will fail.
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: %TRUE if the @attribute was successfully set to @value 
  * in the @file, %FALSE otherwise. 
  **/
@@ -2503,6 +2729,13 @@ g_file_set_attribute_int32 (GFile                  *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. If
+ * @attribute is of a different type, this operation will fail.
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: %TRUE if the @attribute was successfully set to @value 
  * in the @file, %FALSE otherwise.
  **/
@@ -2530,8 +2763,14 @@ g_file_set_attribute_uint64 (GFile                  *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  * 
- * Returns: %TRUE if the @attribute was successfully set to @value 
- * in the @file, %FALSE otherwise.
+ * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. If
+ * @attribute is of a different type, this operation will fail.
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
+ * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise.
  **/
 gboolean
 g_file_set_attribute_int64 (GFile                  *file,
@@ -2556,6 +2795,10 @@ g_file_set_attribute_int64 (GFile                  *file,
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: a #gpointer. 
  * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Mounts a mountable file using @mount_operation, if possible. 
  *
  **/
@@ -2627,6 +2870,10 @@ g_file_mount_mountable_finish (GFile                  *file,
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: a #gpointer. 
  * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  **/
 void
 g_file_unmount_mountable (GFile                  *file,
@@ -2693,6 +2940,15 @@ g_file_unmount_mountable_finish   (GFile                  *file,
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: a #gpointer. 
  * 
+ * Starts an asynchronous eject on a mountable.  
+ * When this operation has completed, @callback will be called with
+ * @user_user data, and the operation can be finalized with 
+ * g_file_eject_mountable_finish().
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  **/
 void
 g_file_eject_mountable (GFile                  *file,
@@ -2728,6 +2984,9 @@ g_file_eject_mountable (GFile                  *file,
  * @result: a #GAsyncResult.
  * @error: a #GError. 
  * 
+ * Finishes an asynchronous eject operation started by 
+ * g_file_eject_mountable().
+ * 
  * Returns: %TRUE if the @file was ejected successfully. %FALSE 
  * otherwise.
  **/
@@ -2758,6 +3017,10 @@ g_file_eject_mountable_finish (GFile                  *file,
  * @flags: a set of #GFileMonitorFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: a #GDirectoryMonitor for the given @file, 
  * or %NULL on error.
  **/
@@ -2784,6 +3047,10 @@ g_file_monitor_directory (GFile *file,
  * @flags: a set of #GFileMonitorFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: a #GFileMonitor for the given @file, 
  * or %NULL on error.
  **/
@@ -3518,11 +3785,15 @@ g_file_new_for_commandline_arg (const char *arg)
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: a #gpointer. 
  * 
- * Starts the @mount_operation, mounting the volume at @location. This
- * operation is cancellable with @cancellable. When the operation has 
- * completed, @callback will be called with user data. To finish 
- * the operation, call g_mount_for_location_finish() with the 
- * #GAsyncResult returned by the @callback.
+ * Starts the @mount_operation, mounting the volume at @location. 
+ * 
+ * When this operation has completed, @callback will be called with
+ * @user_user data, and the operation can be finalized with 
+ * g_mount_for_location_finish().
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  **/
 void
@@ -3559,10 +3830,11 @@ g_mount_for_location (GFile                  *location,
  * @result: a #GAsyncResult.
  * @error: a #GError. 
  * 
- * Finishes an Asynchronous mount operation. 
+ * Finishes a mount operation started by g_mount_for_location().
  * 
- * Returns: %TRUE if the mount was finished successfully. If %FALSE and 
- * @error is present, it will be set appropriately. 
+ * Returns: %TRUE if successful. If an error
+ * has occured, this function will return %FALSE and set @error
+ * appropriately if present.
  **/
 gboolean
 g_mount_for_location_finish (GFile                  *location,
@@ -3596,11 +3868,15 @@ g_mount_for_location_finish (GFile                  *location,
  * g_file_load_contents:
  * @file: input #GFile.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @contents: 
- * @length:
- * @etag_out: a pointer to the current entity tag for the document.
+ * @contents: a location to place the contents of the file.
+ * @length: a location to place the length of the contents of the file.
+ * @etag_out: a location to place the current entity tag for the file.
  * @error: a #GError. 
  * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
  * Returns: %TRUE if the @file's contents were successfully loaded.
  * %FALSE if there were errors. The length of the loaded data will be
  * put into @length, the contents in @contents.
@@ -3854,9 +4130,7 @@ load_contents_open_callback (GObject *obj,
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  **/
 void
@@ -3890,10 +4164,10 @@ g_file_load_partial_contents_async (GFile                *file,
 /**
  * g_file_load_partial_contents_finish:
  * @file: input #GFile.
- * @error: a #GAsyncResult. 
- * @contents: a pointer to where the contents of the file will be placed.
- * @length: a pointer to the location where the content's length will be placed.
- * @etag_out: a pointer to the current entity tag for the document.
+ * @res: a #GAsyncResult. 
+ * @contents: a location to place the contents of the file.
+ * @length: a location to place the length of the contents of the file.
+ * @etag_out: a location to place the current entity tag for the file.
  * @error: a #GError. 
  * 
  * Returns: %TRUE if the load was successful. If %FALSE and @error is 
@@ -3967,9 +4241,7 @@ g_file_load_partial_contents_finish (GFile                *file,
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  **/
 void
@@ -3988,10 +4260,10 @@ g_file_load_contents_async (GFile                *file,
 /**
  * g_file_load_contents_finish:
  * @file: input #GFile.
- * @error: a #GAsyncResult. 
- * @contents: an array of strings.
- * @length: a pointer to a #gsize.
- * @etag_out: a pointer to a string to get the new entity tag.
+ * @res: a #GAsyncResult. 
+ * @contents: a location to place the contents of the file.
+ * @length: a location to place the length of the contents of the file.
+ * @etag_out: a location to place the current entity tag for the file.
  * @error: a #GError. 
  * 
  * Finishes an asynchronous load of the @file's contents. The contents 
@@ -4022,23 +4294,22 @@ g_file_load_contents_finish (GFile                *file,
 /**
  * g_file_replace_contents:
  * @file: input #GFile.
- * @length: a #gsize.
+ * @contents: a string containing the new contents for @file.
+ * @length: the length of @contents in bytes.
  * @etag: the old entity tag for the document.
  * @make_backup: a #gboolean.
  * @flags: a set of #GFileCreateFlags.
- * @new_etag: a new entity tag for the document.
+ * @new_etag: a location to a new entity tag for the document.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError. 
  *
- * Replaces the contents of @file with @contents of @length. The old 
+ * Replaces the contents of @file with @contents of @length bytes. The old 
  * @etag will be replaced with the @new_etag. If @make_backup is %TRUE, 
  * this function will attempt to make a backup of @file.
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * Returns: %TRUE if successful. If an error
  * has occured, this function will return %FALSE and set @error
@@ -4231,7 +4502,7 @@ replace_contents_open_callback (GObject *obj,
  * g_file_replace_contents_async:
  * @file: input #GFile.
  * @contents: string of contents to replace the file with.
- * @length: length of the @contents string.
+ * @length: the length of @contents in bytes.
  * @etag: a new entity tag for the @file.
  * @make_backup: a #gboolean.
  * @flags: a set of #GFileCreateFlags.
@@ -4249,9 +4520,7 @@ replace_contents_open_callback (GObject *obj,
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
- * operation was partially finished when the operation was cancelled the
- * partial result will be returned, without an error.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
  * If @make_backup is %TRUE, this function will attempt to 
  * make a backup of @file.
@@ -4297,12 +4566,12 @@ g_file_replace_contents_async  (GFile                *file,
 /**
  * g_file_replace_contents_finish:
  * @file: input #GFile.
- * @error: a #GAsyncResult. 
- * @new_etag: a pointer to the new entity tag string for the contents of the file.
+ * @res: a #GAsyncResult. 
+ * @new_etag: a location of a new entity tag for the document.
  * @error: a #GError. 
  * 
- * Finishes an asynchronous replace of the given @file. 
- * This function will take ownership of the @new_etag, if present.
+ * Finishes an asynchronous replace of the given @file. Sets
+ * @new_etag to the new entity tag for the document, if present.
  * 
  * Returns: %TRUE on success, %FALSE on failure.
  **/
diff --git a/gio/gfile.h b/gio/gfile.h
index ac3f02f14..c2e437b69 100644
--- a/gio/gfile.h
+++ b/gio/gfile.h
@@ -37,15 +37,37 @@ G_BEGIN_DECLS
 #define G_IS_FILE(obj)	       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_FILE))
 #define G_FILE_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_FILE, GFileIface))
 
+/**
+ * GFileQueryInfoFlags:
+ * @G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS:
+ * 
+ * Flags used when querying a #GFileInfo.
+ */
 typedef enum {
   G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS = (1<<0)
 } GFileQueryInfoFlags;
 
+/**
+ * GFileCreateFlags:
+ * @G_FILE_CREATE_FLAGS_NONE:
+ * @G_FILE_CREATE_FLAGS_PRIVATE: 
+ * 
+ * Flags used when an operation may create a file.
+ */
 typedef enum  {
   G_FILE_CREATE_FLAGS_NONE = 0,
   G_FILE_CREATE_FLAGS_PRIVATE = (1<<0)
 } GFileCreateFlags;
 
+/**
+ * GFileCopyFlags:
+ * @G_FILE_COPY_OVERWRITE: Overwrite any existing files
+ * @G_FILE_COPY_BACKUP: Make a backup of any existing files.
+ * @G_FILE_COPY_NOFOLLOW_SYMLINKS: Don't follow symlinks.
+ * @G_FILE_COPY_ALL_METADATA: Copy all file metadata (see #GFileInfo).
+ *
+ * Flags used when copying or moving files. 
+ */
 typedef enum {
   G_FILE_COPY_OVERWRITE = (1<<0),
   G_FILE_COPY_BACKUP = (1<<1),
@@ -53,25 +75,149 @@ typedef enum {
   G_FILE_COPY_ALL_METADATA = (1<<3)
 } GFileCopyFlags;
 
+/**
+ * GFileMonitorFlags:
+ * @G_FILE_MONITOR_FLAGS_NONE: No flags set.
+ * @G_FILE_MONITOR_FLAGS_MONITOR_MOUNTS: Watch for mount events. 
+ *
+ * Flags used to set what a #GFileMonitor or #GDirectoryMonitor will watch for. 
+ */
 typedef enum  {
   G_FILE_MONITOR_FLAGS_NONE = 0,
   G_FILE_MONITOR_FLAGS_MONITOR_MOUNTS = (1<<0)
 } GFileMonitorFlags;
 
+/**
+ * GFile:
+ * 
+ * A handle to an object implementing the #GFileIface interface. 
+ * Generally stores a location within the file system. Handles do not 
+ * necessarily represent files or directories that currently exist.
+ **/
 typedef struct _GFile         		GFile; /* Dummy typedef */
 typedef struct _GFileIface    		GFileIface;
 typedef struct _GDirectoryMonitor       GDirectoryMonitor;
 typedef struct _GFileMonitor            GFileMonitor;
+
+/**
+ * GVolume:
+ * 
+ * A handle to an object implementing the #GVolumeIface interface.
+ **/
 typedef struct _GVolume         GVolume; /* Dummy typedef */
 
+/**
+ * GFileProgressCallback:
+ * @current_num_bytes: the current number of bytes in the operation.
+ * @total_num_bytes: the total number of bytes in the operation.
+ * @user_data: user data passed to the callback.
+ *
+ * When doing file operations that may take a while, such as moving 
+ * a file or copying a file, a progress callback is used to pass how 
+ * far along that operation is to the application. 
+ **/
 typedef void (*GFileProgressCallback) (goffset current_num_bytes,
 				       goffset total_num_bytes,
 				       gpointer user_data);
+
+/**
+ * GFileReadMoreCallback:
+ * @file_contents:
+ * @file_size:
+ * @callback_data:
+ *
+ * 
+ **/
 typedef gboolean (* GFileReadMoreCallback) (const char *file_contents,
 					    goffset file_size,
 					    gpointer callback_data);
 
-
+/**
+ * GFileIface:
+ * @g_iface: The parent interface.
+ * @dup: Duplicates a #GFile.
+ * @hash: Creates a hash of a #GFile.
+ * @equal: Checks equality of two given #GFile<!-- -->s.
+ * @is_native: Checks to see if a file is native to the system.
+ * @has_uri_scheme: Checks to see if a #GFile has a given URI scheme.
+ * @get_uri_scheme: Gets the URI scheme for a #GFile.
+ * @get_basename: Gets the basename for a given #GFile.
+ * @get_path: Gets the current path within a #GFile. 
+ * @get_uri: Gets a URI for the path within a #GFile.
+ * @get_parse_name: Gets the parsed name for the #GFile.
+ * @get_parent: Gets the parent directory for the #GFile.
+ * @contains_file: Checks whether a #GFile contains a specified file.
+ * @get_relative_path: Gets the path for a #GFile relative to a given path.
+ * @resolve_relative_path: Resolves a relative path for a #GFile to an absolute path.
+ * @get_child_for_display_name: Gets the child #GFile for a given display name.
+ * @enumerate_children: Gets a #GFileEnumerator with the children of a #GFile.
+ * @enumerate_children_async: Asynchronously gets a #GFileEnumerator with the children of a #GFile.
+ * @enumerate_children_finish: Finishes asynchronously enumerating the children.
+ * @query_info: Gets the #GFileInfo for a #GFile.
+ * @query_info_async: Asynchronously gets the #GFileInfo for a #GFile.
+ * @query_info_finish: Finishes an asynchronous query info operation.
+ * @query_filesystem_info: Gets a #GFileInfo for the file system #GFile is on.
+ * @_query_filesystem_info_async: Asynchronously gets a #GFileInfo for the file system #GFile is on.
+ * @_query_filesystem_info_finish: Finishes asynchronously getting the file system info.
+ * @find_enclosing_volume: Gets a #GVolume for the #GFile.
+ * @find_enclosing_volume_async: Asynchronously gets the #GVolume for a #GFile.
+ * @find_enclosing_volume_finish: Finishes asynchronously getting the volume.
+ * @set_display_name: Sets the display name for a #GFile.
+ * @set_display_name_async: Asynchronously sets a #GFile's display name.
+ * @set_display_name_finish: Finishes asynchronously setting a #GFile's display name.
+ * @query_settable_attributes: Returns a list of #GFileAttribute<!-- -->s that can be set.
+ * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttribute<!-- -->s that can be set.
+ * @_query_settable_attributes_finish: Finishes asynchronously querying settable attributes.
+ * @query_writable_namespaces: Returns a list of #GFileAttribute namespaces that are writable.
+ * @_query_writable_namespaces_async: Asynchronously gets a list of #GFileAttribute namespaces that are writable.
+ * @_query_writable_namespaces_finish: Finishes asynchronously querying the writable namespaces.
+ * @set_attribute: Sets a #GFileAttribute.
+ * @set_attributes_from_info: Sets a #GFileAttribute with information from a #GFileInfo.
+ * @set_attributes_async: Asynchronously sets a file's attributes.
+ * @set_attributes_finish: Finishes setting a file's attributes asynchronously.
+ * @read: Reads a file asynchronously.
+ * @read_async: Asynchronously reads a file.
+ * @read_finish: Finishes asynchronously reading a file.
+ * @append_to: Writes to the end of a file.
+ * @append_to_async: Asynchronously writes to the end of a file.
+ * @append_to_finish: Finishes an asynchronous file append operation.
+ * @create: Creates a new file.
+ * @create_async: Asynchronously creates a file.
+ * @create_finish: Finishes asynchronously creating a file.
+ * @replace: Replaces the contents of a file.
+ * @replace_async: Asynchronously replaces the contents of a file.
+ * @replace_finish: Finishes asynchronously replacing a file.
+ * @delete_file: Deletes a file.
+ * @_delete_file_async: Asynchronously deletes a file.
+ * @_delete_file_finish: Finishes an asynchronous delete.
+ * @trash: Sends a #GFile to the Trash location.
+ * @_trash_async: Asynchronously sends a #GFile to the Trash location.
+ * @_trash_finish: Finishes an asynchronous file trashing operation.
+ * @make_directory: Makes a directory.
+ * @_make_directory_async: Asynchronously makes a directory.
+ * @_make_directory_finish: Finishes making a directory asynchronously.
+ * @make_symbolic_link: Makes a symbolic link.
+ * @_make_symbolic_link_async: Asynchronously makes a symbolic link
+ * @_make_symbolic_link_finish: Finishes making a symbolic link asynchronously.
+ * @copy: Copies a file.
+ * @_copy_async: Asynchronously copies a file.
+ * @_copy_finish: Finishes an asynchronous copy operation.
+ * @move: Moves a file.
+ * @_move_async: Asynchronously moves a file. 
+ * @_move_finish: Finishes an asynchronous move operation.
+ * @mount_mountable: Mounts a mountable object.
+ * @mount_mountable_finish: Finishes a mounting operation.
+ * @unmount_mountable: Unmounts a mountable object.
+ * @unmount_mountable_finish: Finishes an unmount operation.
+ * @eject_mountable: Ejects a mountable.
+ * @eject_mountable_finish: Finishes an eject operation.
+ * @mount_for_location: Mounts a specified location. 
+ * @mount_for_location_finish: Finishes mounting a specified location.
+ * @monitor_dir: Creates a #GDirectoryMonitor for the location.
+ * @monitor_file: Creates a #GFileMonitor for the location.
+ * 
+ * An interface for writing VFS file handles.  
+ **/ 
 struct _GFileIface
 {
   GTypeInterface g_iface;
@@ -346,6 +492,7 @@ struct _GFileIface
   GFileMonitor*      (*monitor_file)        (GFile                  *file,
 					     GFileMonitorFlags       flags,
 					     GCancellable           *cancellable);
+
 };
 
 GType g_file_get_type (void) G_GNUC_CONST;
diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c
index ee93d6cce..eeb29a4b1 100644
--- a/gio/gfileattribute.c
+++ b/gio/gfileattribute.c
@@ -29,6 +29,160 @@
 #include "glibintl.h"
 
 /**
+ * SECTION:gfileattribute
+ * @short_description: Key-Value Paired File Attributes.
+ * @see_also: #GFile, #GFileInfo.
+ * 
+ * File attributes in GIO consist of a list of key-value pairs. 
+ * 
+ * Keys are strings that contain a key namespace and a key name, separated
+ * by a colon, e.g. "namespace:keyname". Namespaces are included to sort
+ * key-value pairs by namespaces for relevance. Keys can be searched 
+ * for using wildcards, e.g. "std:*" will return all of the keys in the 
+ * "std" namespace.
+ * 
+ * Values are stored within the list in #GFileAttributeValue structures.
+ * Values can store different types, listed in the enum #GFileAttributeType.
+ * Upon creation of a #GFileAttributeValue, the type will be set to 
+ * %G_FILE_ATTRIBUTE_TYPE_INVALID. 
+ * 
+ * The Key-value list is stored within the #GFile structure as a 
+ * #GFileAttributeInfoList. This list is queryable by key names 
+ * as indicated earlier.
+ * 
+ * Classes that implement #GFileIface will create a #GFileAttributeInfoList and 
+ * install default keys and values for their given file system, architecture, 
+ * and other possible implementation details (e.g., on a UNIX system, a file 
+ * attribute key will be registered for the user id for a given file). Other 
+ * attributes can be appended to a #GFileAttributeList later by 
+ * g_file_attribute_info_list_add(). 
+ * 
+ * <para>
+ * <table>
+ * <title>GFileAttributes Namespaces</title>
+ * <tgroup cols='2' align='left'><thead>
+ * <row><entry>Namspace</entry><entry>Description</entry></row>
+ * </thead>
+ * <tbody>
+ * <row><entry>"std"</entry><entry>The "Standard" namespace. General file
+ * information that any application may need should be put in this namespace. Examples
+ * include the file's name, type, and size.</entry></row> 
+ * <row><entry>"etag"</entry><entry>The "Entity Tag" namespace. Remotely shared
+ * files, like those on HTTP/1.1 file systems, use "entity tags" to quickly determine 
+ * if a file has been modified. Entity tags are globally unique, and should
+ * always be sent with the current revision of a file. An example of a key
+ * in this namespace is "value", which contains the value of the current
+ * entity tag.</entry></row>
+ * <row><entry>"id"</entry><entry>The "Identification" namespace. This 
+ * namespace is used by file managers and applications that list directories
+ * to check for loops and to uniquely identify files.</entry></row>
+ * <row><entry>"access"</entry><entry>The "Access" namespace. Used to check
+ * if a user has the proper privilidges to access files and perform
+ * file operations. Keys in this namespace are made to be generic 
+ * and easily understood, e.g. the "can_read" key is %TRUE if 
+ * the current user has permission to read the file. UNIX permissions and
+ * NTFS ACLs in Windows should be mapped to these values.</entry></row>
+ * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes 
+ * simple boolean keys for checking if a file or path supports mount operations, e.g.
+ * mount, unmount, eject.</entry></row>
+ * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file 
+ * access, changed, created times. </entry></row>
+ * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific
+ * information and may not be available for all files. Examples include 
+ * the UNIX "UID", "GID", etc.</entry></row>
+ * <row><entry>"dos"</entry><entry>The "DOS" namespace. Includes DOS-specific 
+ * information and may not be available for all files. Examples include
+ * "is_system" for checking if a file is marked as a system file, and "is_archive"
+ * for checking if a file is marked as an archive file.</entry></row>
+ * <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information
+ * about who owns a file. May not be available for all file systems. Examples include
+ * "user" for getting the user name of the file owner.</entry></row>
+ * <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes 
+ * information about file thumbnails and their location within the file system. Exaples of 
+ * keys in this namespace include "path" to get the location of a thumbnail, and "failed"
+ * to check if thumbnailing failed.</entry></row>
+ * <row><entry>"fs"</entry><entry>The "Filesystem" namespace. Gets information
+ * about the file system where a file is located, such as its type, how much
+ * space is left available, and the overall size of the file system.</entry></row>
+ * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace
+ * contain information about the current GVFS backend in use. </entry></row>
+ * </tbody>
+ * </tgroup>
+ * </table>
+ * </para>
+ * 
+ * More namespaces can be added from GIO modules or by individual applications. 
+ * For more information about writing GIO modules, see #GIOModule.
+ * 
+ * <para><table>
+ * <title>GFileAttributes Built-in Keys and Value Types</title>
+ * <tgroup cols='3' align='left'><thead>
+ * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row>
+ * </thead><tbody>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_TYPE</entry><entry>std:type</entry><entry>uint32 (#GFileType)</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_IS_HIDDEN</entry><entry>std:is_hidden</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_IS_BACKUP</entry><entry>std:is_backup</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_IS_SYMLINK</entry><entry>std:is_symlink</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_IS_VIRTUAL</entry><entry>std:is_virtual</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_NAME</entry><entry>std:name</entry><entry>byte string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_DISPLAY_NAME</entry><entry>std:display_name</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_EDIT_NAME</entry><entry>std:edit_name</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_ICON</entry><entry>std:icon</entry><entry>object (#GIcon)</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_CONTENT_TYPE</entry><entry>std:content_type</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_FAST_CONTENT_TYPE</entry><entry>std:fast_content_type</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_SIZE</entry><entry>std:size</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_SYMLINK_TARGET</entry><entry>std:symlink_target</entry><entry>byte string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_TARGET_URI</entry><entry>std:target_uri</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_SORT_ORDER</entry><entry>std:sort_order</entry><entry>int32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag:value</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id:file</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ID_FS</entry><entry>id:fs</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access:can_read</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access:can_write</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access:can_execute</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access:can_delete</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access:can_trash</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access:can_rename</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable:can_mount</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable:can_unmount</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable:can_eject</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable:unix_device</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable:hal_udi</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time:modified</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time:modified_usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time:access</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time:access_usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time:changed</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time:changed_usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time:created</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time:created_usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix:device</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix:inode</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix:mode</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix:nlink</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix:uid</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix:gid</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix:rdev</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix:block_size</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix:blocks</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix:is_mountpoint</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos:is_archive</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos:is_system</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner:user</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner:user_real</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner:group</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail:path</entry><entry>bytestring</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail:failed</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FS_SIZE</entry><entry>fs:size</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FS_FREE</entry><entry>fs:free</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FS_TYPE</entry><entry>fs:type</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FS_READONLY</entry><entry>fs:readonly</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs:backend</entry><entry>string</entry></row>
+ * </tbody></tgroup></table></para>
+ *  
+ **/ 
+
+/**
  * g_file_attribute_value_free:
  * @attr: a #GFileAttributeValue. 
  * 
@@ -70,9 +224,10 @@ g_file_attribute_value_clear (GFileAttributeValue *attr)
 
 /**
  * g_file_attribute_value_set:
- * @attr: a #GFileAttributeValue.
- * @new_value:
+ * @attr: a #GFileAttributeValue to set the value in.
+ * @new_value: a #GFileAttributeValue to get the value from.
  * 
+ * Sets an attribute's value from another attribute.
  **/
 void
 g_file_attribute_value_set (GFileAttributeValue *attr,
@@ -96,7 +251,9 @@ g_file_attribute_value_set (GFileAttributeValue *attr,
 /**
  * g_file_attribute_value_new:
  * 
- * Returns: a new #GFileAttributeValue.
+ * Creates a new file attribute.
+ * 
+ * Returns: a #GFileAttributeValue.
  **/
 GFileAttributeValue *
 g_file_attribute_value_new (void)
@@ -113,6 +270,8 @@ g_file_attribute_value_new (void)
  * g_file_attribute_value_dup:
  * @other: a #GFileAttributeValue to duplicate.
  * 
+ * Duplicates a file attribute.
+ * 
  * Returns: a duplicate of the @other.
  **/
 GFileAttributeValue *
@@ -182,10 +341,10 @@ escape_byte_string (const char *str)
  * @attr: a #GFileAttributeValue.
  *
  * Converts a #GFileAttributeValue to a string for display.
- * The returned string should be freed when no longer needed
+ * The returned string should be freed when no longer needed.
  * 
- * Returns: a string from the @attr, %NULL on error, or "&lt;invalid&gt;" if 
- * @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID.
+ * Returns: a string from the @attr, %NULL on error, or "&lt;invalid&gt;" 
+ * if @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID.
  **/
 char *
 g_file_attribute_value_as_string (const GFileAttributeValue *attr)
@@ -235,7 +394,10 @@ g_file_attribute_value_as_string (const GFileAttributeValue *attr)
  * g_file_attribute_value_get_string:
  * @attr: a #GFileAttributeValue.
  * 
- * Returns: 
+ * Gets the string from a file attribute value. If the value is not the
+ * right type then %NULL will be returned.
+ * 
+ * Returns: the string value contained within the attribute, or %NULL.
  **/
 const char *
 g_file_attribute_value_get_string (const GFileAttributeValue *attr)
@@ -252,7 +414,10 @@ g_file_attribute_value_get_string (const GFileAttributeValue *attr)
  * g_file_attribute_value_get_byte_string:
  * @attr: a #GFileAttributeValue.
  * 
- * Returns: 
+ * Gets the byte string from a file attribute value. If the value is not the
+ * right type then %NULL will be returned.
+ * 
+ * Returns: the byte string contained within the attribute or %NULL.
  **/
 const char *
 g_file_attribute_value_get_byte_string (const GFileAttributeValue *attr)
@@ -269,7 +434,10 @@ g_file_attribute_value_get_byte_string (const GFileAttributeValue *attr)
  * g_file_attribute_value_get_boolean:
  * @attr: a #GFileAttributeValue.
  * 
- * Returns: 
+ * Gets the boolean value from a file attribute value. If the value is not the
+ * right type then %FALSE will be returned.
+ * 
+ * Returns: the boolean value contained within the attribute, or %FALSE.
  **/
 gboolean
 g_file_attribute_value_get_boolean (const GFileAttributeValue *attr)
@@ -286,7 +454,10 @@ g_file_attribute_value_get_boolean (const GFileAttributeValue *attr)
  * g_file_attribute_value_get_uint32:
  * @attr: a #GFileAttributeValue.
  * 
- * Returns: 
+ * Gets the unsigned 32-bit integer from a file attribute value. If the value 
+ * is not the right type then %0 will be returned.
+ * 
+ * Returns: the unsigned 32-bit integer from the attribute, or %0.
  **/
 guint32
 g_file_attribute_value_get_uint32 (const GFileAttributeValue *attr)
@@ -303,7 +474,10 @@ g_file_attribute_value_get_uint32 (const GFileAttributeValue *attr)
  * g_file_attribute_value_get_int32:
  * @attr: a #GFileAttributeValue.
  * 
- * Returns: 
+ * Gets the signed 32-bit integer from a file attribute value. If the value 
+ * is not the right type then %0 will be returned.
+ * 
+ * Returns: the signed 32-bit integer from the attribute, or %0.
  **/
 gint32
 g_file_attribute_value_get_int32 (const GFileAttributeValue *attr)
@@ -320,7 +494,10 @@ g_file_attribute_value_get_int32 (const GFileAttributeValue *attr)
  * g_file_attribute_value_get_uint64:
  * @attr: a #GFileAttributeValue.
  * 
- * Returns: 
+ * Gets the unsigned 64-bit integer from a file attribute value. If the value 
+ * is not the right type then %0 will be returned.
+ * 
+ * Returns: the unsigned 64-bit integer from the attribute, or %0.
  **/  
 guint64
 g_file_attribute_value_get_uint64 (const GFileAttributeValue *attr)
@@ -337,7 +514,10 @@ g_file_attribute_value_get_uint64 (const GFileAttributeValue *attr)
  * g_file_attribute_value_get_int64:
  * @attr: a #GFileAttributeValue.
  * 
- * Returns: 
+ * Gets the signed 64-bit integer from a file attribute value. If the value 
+ * is not the right type then %0 will be returned.
+ * 
+ * Returns: the signed 64-bit integer from the attribute, or %0. 
  **/
 gint64
 g_file_attribute_value_get_int64 (const GFileAttributeValue *attr)
@@ -354,7 +534,10 @@ g_file_attribute_value_get_int64 (const GFileAttributeValue *attr)
  * g_file_attribute_value_get_object:
  * @attr: a #GFileAttributeValue.
  * 
- * Returns: 
+ * Gets the GObject from a file attribute value. If the value 
+ * is not the right type then %NULL will be returned.
+ * 
+ * Returns: the GObject from the attribute, or %0.
  **/
 GObject *
 g_file_attribute_value_get_object (const GFileAttributeValue *attr)
@@ -370,7 +553,9 @@ g_file_attribute_value_get_object (const GFileAttributeValue *attr)
 /**
  * g_file_attribute_value_set_string:
  * @attr: a #GFileAttributeValue.
- * @string:
+ * @string: a string to set within the type.
+ * 
+ * Sets the attribute value to a given string.
  * 
  **/
 void
@@ -388,7 +573,9 @@ g_file_attribute_value_set_string (GFileAttributeValue *attr,
 /**
  * g_file_attribute_value_set_byte_string:
  * @attr: a #GFileAttributeValue.
- * @string:
+ * @string: a byte string to set within the type.
+ * 
+ * Sets the attribute value to a given byte string.
  * 
  **/
 void
@@ -406,8 +593,10 @@ g_file_attribute_value_set_byte_string (GFileAttributeValue *attr,
 /**
  * g_file_attribute_value_set_boolean:
  * @attr: a #GFileAttributeValue.
- * @value:
- *  
+ * @value: a #gboolean to set within the type.
+ * 
+ * Sets the attribute value to the given boolean value. 
+ * 
  **/
 void
 g_file_attribute_value_set_boolean (GFileAttributeValue *attr,
@@ -423,7 +612,9 @@ g_file_attribute_value_set_boolean (GFileAttributeValue *attr,
 /**
  * g_file_attribute_value_set_uint32:
  * @attr: a #GFileAttributeValue.
- * @value:
+ * @value: a #guint32 to set within the type.
+ * 
+ * Sets the attribute value to the given unsigned 32-bit integer.
  * 
  **/ 
 void
@@ -440,7 +631,9 @@ g_file_attribute_value_set_uint32 (GFileAttributeValue *attr,
 /**
  * g_file_attribute_value_set_int32:
  * @attr: a #GFileAttributeValue.
- * @value:
+ * @value: a #gint32 to set within the type.
+ * 
+ * Sets the attribute value to the given signed 32-bit integer.
  *  
  **/
 void
@@ -457,7 +650,9 @@ g_file_attribute_value_set_int32 (GFileAttributeValue *attr,
 /**
  * g_file_attribute_value_set_uint64:
  * @attr: a #GFileAttributeValue.
- * @value:
+ * @value: a #guint64 to set within the type.
+ * 
+ * Sets the attribute value to a given unsigned 64-bit integer.
  * 
  **/
 void
@@ -474,8 +669,10 @@ g_file_attribute_value_set_uint64 (GFileAttributeValue *attr,
 /**
  * g_file_attribute_value_set_int64:
  * @attr: a #GFileAttributeValue.
- * @value: a #gint64 to set the value to.
- *  
+ * @value: a #gint64 to set within the type.
+ * 
+ * Sets the attribute value to a given signed 64-bit integer. 
+ * 
  **/
 void
 g_file_attribute_value_set_int64 (GFileAttributeValue *attr,
@@ -493,8 +690,8 @@ g_file_attribute_value_set_int64 (GFileAttributeValue *attr,
  * @attr: a #GFileAttributeValue.
  * @obj: a #GObject.
  *
- * Sets the file attribute @attr to contain the value @obj.
- * The @attr references the object internally.
+ * Sets the attribute to contain the value @obj.
+ * The @attr references the GObject internally.
  * 
  **/
 void
@@ -525,7 +722,9 @@ list_update_public (GFileAttributeInfoListPriv *priv)
 /**
  * g_file_attribute_info_list_new:
  * 
- * Returns a new #GFileAttributeInfoList.
+ * Creates a new file attribute info list.
+ * 
+ * Returns: a #GFileAttributeInfoList.
  **/
 GFileAttributeInfoList *
 g_file_attribute_info_list_new (void)
@@ -546,6 +745,8 @@ g_file_attribute_info_list_new (void)
  * g_file_attribute_info_list_dup:
  * @list: a #GFileAttributeInfoList to duplicate.
  * 
+ * Makes a duplicate of a file attribute info list.
+ * 
  * Returns a duplicate of the given @list. 
  **/
 GFileAttributeInfoList *
@@ -576,6 +777,8 @@ g_file_attribute_info_list_dup (GFileAttributeInfoList *list)
  * g_file_attribute_info_list_ref:
  * @list: a #GFileAttributeInfoList to reference.
  * 
+ * References a file attribute info list.
+ * 
  * Returns: #GFileAttributeInfoList or %NULL on error.
  **/
 GFileAttributeInfoList *
diff --git a/gio/gfileattribute.h b/gio/gfileattribute.h
index 125a46d45..23565b8e0 100644
--- a/gio/gfileattribute.h
+++ b/gio/gfileattribute.h
@@ -27,6 +27,20 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GFileAttributeType:
+ * @G_FILE_ATTRIBUTE_TYPE_INVALID: indicates an invalid or uninitalized type.
+ * @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated C string.
+ * @G_FILE_ATTRIBUTE_TYPE_BYTE_STRING: a zero terminated string of non-zero bytes.
+ * @G_FILE_ATTRIBUTE_TYPE_BOOLEAN: a boolean value.
+ * @G_FILE_ATTRIBUTE_TYPE_UINT32: an unsigned 4-byte/32-bit integer.
+ * @G_FILE_ATTRIBUTE_TYPE_INT32: a signed 4-byte/32-bit integer.
+ * @G_FILE_ATTRIBUTE_TYPE_UINT64: an unsigned 8-byte/64-bit integer.
+ * @G_FILE_ATTRIBUTE_TYPE_INT64: a signed 8-byte/64-bit integer.
+ * @G_FILE_ATTRIBUTE_TYPE_OBJECT: a #GObject.
+ * 
+ * The data type for #GFileAttributeValue<!-- -->s. 
+ **/ 
 typedef enum {
   G_FILE_ATTRIBUTE_TYPE_INVALID = 0,
   G_FILE_ATTRIBUTE_TYPE_STRING,
@@ -39,13 +53,28 @@ typedef enum {
   G_FILE_ATTRIBUTE_TYPE_OBJECT
 } GFileAttributeType;
 
+/**
+ * GFileAttributeFlags:
+ * @G_FILE_ATTRIBUTE_FLAGS_NONE: no flags set.
+ * @G_FILE_ATTRIBUTE_FLAGS_COPY_WITH_FILE: copy the attribute values when the file is copied.
+ * @G_FILE_ATTRIBUTE_FLAGS_COPY_WHEN_MOVED: copy the attribute values when the file is moved.
+ * 
+ * Indicates how to transfer file attributes to new #GFile structures when they are copied.
+ **/
 typedef enum {
   G_FILE_ATTRIBUTE_FLAGS_NONE = 0,
   G_FILE_ATTRIBUTE_FLAGS_COPY_WITH_FILE = 1 << 0,
   G_FILE_ATTRIBUTE_FLAGS_COPY_WHEN_MOVED = 1 << 1
 } GFileAttributeFlags;
 
-/* Used by g_file_set_attributes_from_info */
+/**
+ * GFileAttributeStatus:
+ * @G_FILE_ATTRIBUTE_STATUS_UNSET: Attribute value is unset (empty).
+ * @G_FILE_ATTRIBUTE_STATUS_SET: Attribute value is set.
+ * @G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING: Indicates an error in setting the value.
+ * 
+ * Used by g_file_set_attributes_from_info() when setting file attributes.
+ **/
 typedef enum {
   G_FILE_ATTRIBUTE_STATUS_UNSET = 0,
   G_FILE_ATTRIBUTE_STATUS_SET,
@@ -54,6 +83,13 @@ typedef enum {
 
 #define G_FILE_ATTRIBUTE_VALUE_INIT {0}
 
+/**
+ * GFileAttributeValue:
+ * @type: a #GFileAttributeType.
+ * @status: a #GFileAttributeStatus.
+ *
+ * Contains the value data for the Key-Value pair.
+ **/
 typedef struct  {
   GFileAttributeType type : 8;
   GFileAttributeStatus status : 8;
@@ -69,12 +105,28 @@ typedef struct  {
   } u;
 } GFileAttributeValue;
 
+/**
+ * GFileAttributeInfo:
+ * @name: a string containing the key's name.
+ * @type: a #GFileAttributeType for the key.
+ * @flags: a set of #GFileAttributeFlags.
+ * 
+ * A Key-Value pair definition. 
+ **/
 typedef struct {
   char *name;
   GFileAttributeType type;
   GFileAttributeFlags flags;
 } GFileAttributeInfo;
 
+/**
+ * GFileAttributeInfoList:
+ * @infos: an array of #GFileAttributeInfo<!-- -->s.
+ * @n_infos: the number of values in the array.
+ * 
+ * Acts as a lightweight registry for possible valid file attributes.
+ * The registry stores Key-Value pair formats as #GFileAttributeInfo<!-- -->s.
+ **/
 typedef struct {
   GFileAttributeInfo *infos;
   int n_infos;
diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c
index 300fff316..7422bb99b 100644
--- a/gio/gfileenumerator.c
+++ b/gio/gfileenumerator.c
@@ -27,6 +27,13 @@
 #include "gsimpleasyncresult.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gfileenumerator
+ * @short_description: Enumerated Files Routines.
+ * 
+ * 
+ **/ 
+
 G_DEFINE_TYPE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT);
 
 struct _GFileEnumeratorPrivate {
@@ -305,6 +312,9 @@ g_file_enumerator_next_files_async  (GFileEnumerator                *enumerator,
  * @result: a #GAsyncResult.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
+ * 
+ * 
+ * 
  * Returns: 
  **/
 GList *
@@ -402,6 +412,9 @@ g_file_enumerator_close_async (GFileEnumerator                *enumerator,
  * @result: a #GAsyncResult.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
+ * 
+ * 
+ * 
  * Returns: %TRUE if the close operation has finished successfully.
  **/
 gboolean
diff --git a/gio/gfileenumerator.h b/gio/gfileenumerator.h
index 1e83f8856..677311787 100644
--- a/gio/gfileenumerator.h
+++ b/gio/gfileenumerator.h
@@ -39,7 +39,12 @@ G_BEGIN_DECLS
 #define G_IS_FILE_ENUMERATOR_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_ENUMERATOR))
 #define G_FILE_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_ENUMERATOR, GFileEnumeratorClass))
 
-
+/**
+ * GFileEnumerator:
+ * @parent: The parent class.
+ * 
+ * A per matched file iterator.
+ **/
 typedef struct _GFileEnumerator         GFileEnumerator;
 typedef struct _GFileEnumeratorClass    GFileEnumeratorClass;
 typedef struct _GFileEnumeratorPrivate  GFileEnumeratorPrivate;
@@ -84,8 +89,8 @@ struct _GFileEnumeratorClass
 				   GAsyncResult                   *res,
 				   GError                        **error);
 
-
-    /* Padding for future expansion */
+  /*< private >*/
+  /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
   void (*_g_reserved3) (void);
diff --git a/gio/gfileicon.c b/gio/gfileicon.c
index 6e46e7f95..be3f3fe9e 100644
--- a/gio/gfileicon.c
+++ b/gio/gfileicon.c
@@ -25,6 +25,16 @@
 #include "gfileicon.h"
 #include "gsimpleasyncresult.h"
 
+/**
+ * SECTION:gfileicon
+ * @short_description: Icons for given files.
+ * @see_also: #GIcon, #GLoadableIcon.
+ * @include: gio/gfileicon.h
+ * 
+ * #GFileIcon gets the default icon for a #GFile.  
+ * 
+ **/
+
 static void g_file_icon_icon_iface_init          (GIconIface          *iface);
 static void g_file_icon_loadable_icon_iface_init (GLoadableIconIface  *iface);
 static void g_file_icon_load_async               (GLoadableIcon       *icon,
@@ -80,9 +90,11 @@ g_file_icon_init (GFileIcon *file)
 
 /**
  * g_file_icon_new:
- * @file:
+ * @file: a #GFile.
+ * 
+ * Creates a new icon for a file.
  * 
- * Returns: 
+ * Returns: a #GIcon for the given @file, or %NULL on error.
  **/
 GIcon *
 g_file_icon_new (GFile *file)
@@ -99,9 +111,11 @@ g_file_icon_new (GFile *file)
 
 /**
  * g_file_icon_get_file:
- * @icon:
+ * @icon: a #GIcon.
+ * 
+ * Gets the #GFile associated with the given @icon.
  * 
- * Returns: 
+ * Returns: a #GFile, or %NULL.
  **/
 GFile *
 g_file_icon_get_file (GFileIcon *icon)
diff --git a/gio/gfileicon.h b/gio/gfileicon.h
index 1745e5fba..1d43cce98 100644
--- a/gio/gfileicon.h
+++ b/gio/gfileicon.h
@@ -35,6 +35,11 @@ G_BEGIN_DECLS
 #define G_IS_FILE_ICON_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_ICON))
 #define G_FILE_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_ICON, GFileIconClass))
 
+/**
+ * GFileIcon:
+ * 
+ * Gets an icon for a #GFile. Implements #GLoadabeIcon.
+ **/
 typedef struct _GFileIcon        GFileIcon;
 typedef struct _GFileIconClass   GFileIconClass;
 
diff --git a/gio/gfileinfo.c b/gio/gfileinfo.c
index 07c8f4918..698661523 100644
--- a/gio/gfileinfo.c
+++ b/gio/gfileinfo.c
@@ -20,6 +20,21 @@
  * Author: Alexander Larsson <alexl@redhat.com>
  */
 
+/**
+ * SECTION:gfileinfo
+ * @short_description: File Information and Attributes.
+ * @see_also: #GFile.
+ * 
+ * Functionality for manipulating basic metadata for files. #GFileInfo
+ * implements methods for getting information that all files should 
+ * contain, and allows for manipulation of extended attributes. 
+ * #GFileAttributeMatcher allows for searching through a #GFileInfo for 
+ * attributes.
+ * 
+ * 
+ * 
+ **/
+
 #include <config.h>
 
 #include <string.h>
@@ -222,7 +237,9 @@ g_file_info_init (GFileInfo *info)
 /**
  * g_file_info_new:
  * 
- * Returns: a new #GFileInfo.
+ * Creates a new file info structure.
+ * 
+ * Returns: a #GFileInfo.
  **/
 GFileInfo *
 g_file_info_new (void)
@@ -235,7 +252,7 @@ g_file_info_new (void)
  * @src_info: source to copy attributes from.
  * @dest_info: destination to copy attributes to.
  * 
- * Copies all of the attributes from @src_info to @dest_info.
+ * Copies all of the #GFileAttribute<!-- -->s from @src_info to @dest_info.
  **/
 void
 g_file_info_copy_into (GFileInfo *src_info, GFileInfo *dest_info)
@@ -273,6 +290,8 @@ g_file_info_copy_into (GFileInfo *src_info, GFileInfo *dest_info)
  * g_file_info_dup:
  * @other: a #GFileInfo.
  * 
+ * Duplicates a file info structure.
+ * 
  * Returns: a duplicate #GFileInfo of @other.
  **/
 GFileInfo *
@@ -293,7 +312,6 @@ g_file_info_dup (GFileInfo  *other)
  * @mask: a #GFileAttributeMatcher.
  *
  * Sets @mask on @info to match specific attribute types.
- * 
  **/
 void
 g_file_info_set_attribute_mask (GFileInfo *info,
@@ -330,6 +348,8 @@ g_file_info_set_attribute_mask (GFileInfo *info,
  * g_file_info_unset_attribute_mask:
  * @info: #GFileInfo.
  * 
+ * Unsets a mask set by g_file_info_set_attribute_mask(), if one
+ * is set.
  **/
 void
 g_file_info_unset_attribute_mask (GFileInfo *info)
@@ -346,7 +366,6 @@ g_file_info_unset_attribute_mask (GFileInfo *info)
  * @info: a #GFileInfo.
  *
  * Clears the status information from @info.
- * 
  **/
 void
 g_file_info_clear_status (GFileInfo  *info)
@@ -421,7 +440,9 @@ g_file_info_find_value_by_name (GFileInfo *info,
 /**
  * g_file_info_has_attribute:
  * @info: a #GFileInfo.
- * @attribute: a string.
+ * @attribute: a file attribute key.
+ * 
+ * Checks if a file info structure has an attribute named @attribute.
  * 
  * Returns: %TRUE if @GFileInfo has an attribute named @attribute, 
  * %FALSE otherwise.
@@ -442,7 +463,9 @@ g_file_info_has_attribute (GFileInfo  *info,
 /**
  * g_file_info_list_attributes:
  * @info: a #GFileInfo.
- * @name_space: a string.
+ * @name_space: a file attribute key's namespace.
+ * 
+ * Lists the file info structure's attributes.
  * 
  * Returns: a null-terminated array of strings of all of the 
  * possible attribute types for the given @name_space, or 
@@ -478,10 +501,12 @@ g_file_info_list_attributes (GFileInfo  *info,
 /**
  * g_file_info_get_attribute_type:
  * @info: a #GFileInfo.
- * @attribute: a string.
+ * @attribute: a file attribute key.
+ * 
+ * Gets the attribute type for an attribute key.
  * 
  * Returns: a #GFileAttributeType for the given @attribute, or 
- * %G_FILE_ATTRIBUTE_TYPE_INVALID if one cannot be found.
+ * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is invalid.
  **/
 GFileAttributeType
 g_file_info_get_attribute_type (GFileInfo  *info,
@@ -502,9 +527,9 @@ g_file_info_get_attribute_type (GFileInfo  *info,
 /**
  * g_file_info_remove_attribute:
  * @info: a #GFileInfo.
- * @attribute: a string.
+ * @attribute: a file attribute key.
  * 
- * Removes @attribute from @info if it exists.
+ * Removes all cases of @attribute from @info if it exists.
  *
  **/
 void
@@ -533,7 +558,9 @@ g_file_info_remove_attribute (GFileInfo  *info,
 /**
  * g_file_info_get_attribute:
  * @info: a #GFileInfo.
- * @attribute: a string.
+ * @attribute: a file attribute key.
+ * 
+ * Gets an attribute value from a file info structure.
  * 
  * Returns: a #GFileAttributeValue for the given @attribute, or 
  * %NULL otherwise.
@@ -552,7 +579,10 @@ g_file_info_get_attribute (GFileInfo  *info,
 /**
  * g_file_info_get_attribute_object:
  * @info: a #GFileInfo.
- * @attribute: a string.
+ * @attribute: a file attribute key.
+ * 
+ * Gets the value of a #GObject attribute. If the attribute does 
+ * not contain a #GObject, %NULL will be returned.
  * 
  * Returns: a #GObject associated with the given @attribute, or
  * %NULL otherwise.
@@ -573,7 +603,10 @@ g_file_info_get_attribute_object (GFileInfo  *info,
 /**
  * g_file_info_get_attribute_string:
  * @info: a #GFileInfo.
- * @attribute: a string.
+ * @attribute: a file attribute key.
+ * 
+ * Gets the value of a string attribute. If the attribute does 
+ * not contain a string, %NULL will be returned.
  * 
  * Returns: the contents of the @attribute value as a string, or 
  * %NULL otherwise.
@@ -594,7 +627,10 @@ g_file_info_get_attribute_string (GFileInfo  *info,
 /**
  * g_file_info_get_attribute_byte_string:
  * @info: a #GFileInfo.
- * @attribute: a string.
+ * @attribute: a file attribute key.
+ * 
+ * Gets the value of a byte string attribute. If the attribute does 
+ * not contain a byte string, %NULL will be returned.
  * 
  * Returns: the contents of the @attribute value as a byte string, or 
  * %NULL otherwise.
@@ -615,9 +651,12 @@ g_file_info_get_attribute_byte_string (GFileInfo  *info,
 /**
  * g_file_info_get_attribute_boolean:
  * @info: a #GFileInfo.
- * @attribute: a string.
+ * @attribute: a file attribute key.
+ * 
+ * Gets the value of a boolean attribute. If the attribute does not
+ * contain a boolean value, %FALSE will be returned.
  * 
- * Returns: 
+ * Returns: the boolean value contained within the attribute. 
  **/
 gboolean
 g_file_info_get_attribute_boolean (GFileInfo  *info,
@@ -635,9 +674,13 @@ g_file_info_get_attribute_boolean (GFileInfo  *info,
 /**
  * g_file_info_get_attribute_uint32:
  * @info: a #GFileInfo.
- * @attribute: a string.
+ * @attribute: a file attribute key.
  * 
- * Returns: 
+ * Gets an unsigned 32-bit integer contained within the attribute. If the 
+ * attribute does not contain an unsigned 32-bit integer, or is invalid, 
+ * %0 will be returned.
+ * 
+ * Returns: an unsigned 32-bit integer from the attribute. 
  **/
 guint32
 g_file_info_get_attribute_uint32 (GFileInfo  *info,
@@ -654,10 +697,14 @@ g_file_info_get_attribute_uint32 (GFileInfo  *info,
 
 /**
  * g_file_info_get_attribute_int32:
- * @info:
- * @attribute:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
  * 
- * Returns:
+ * Gets a signed 32-bit integer contained within the attribute. If the 
+ * attribute does not contain a signed 32-bit integer, or is invalid, 
+ * %0 will be returned.
+ * 
+ * Returns: a signed 32-bit integer from the attribute.
  **/
 gint32
 g_file_info_get_attribute_int32 (GFileInfo  *info,
@@ -674,10 +721,14 @@ g_file_info_get_attribute_int32 (GFileInfo  *info,
 
 /**
  * g_file_info_get_attribute_uint64:
- * @info:
- * @attribute:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * 
+ * Gets a unsigned 64-bit integer contained within the attribute. If the 
+ * attribute does not contain an unsigned 64-bit integer, or is invalid, 
+ * %0 will be returned.
  * 
- * Returns: 
+ * Returns: a unsigned 64-bit integer from the attribute. 
  **/
 guint64
 g_file_info_get_attribute_uint64 (GFileInfo  *info,
@@ -694,10 +745,14 @@ g_file_info_get_attribute_uint64 (GFileInfo  *info,
 
 /**
  * g_file_info_get_attribute_int64:
- * @info:
- * @attribute:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * 
+ * Gets a signed 64-bit integer contained within the attribute. If the 
+ * attribute does not contain an signed 64-bit integer, or is invalid, 
+ * %0 will be returned.
  * 
- * Returns: 
+ * Returns: a signed 64-bit integer from the attribute. 
  **/
 gint64
 g_file_info_get_attribute_int64  (GFileInfo  *info,
@@ -754,9 +809,12 @@ g_file_info_create_value_by_name (GFileInfo *info,
 
 /**
  * g_file_info_set_attribute:
- * @info:
- * @attribute:
- * @attr_value:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a #GFileAttributeValue.
+ * 
+ * Sets the @attribute to contain the given @attr_value, 
+ * if possible.
  *
  **/
 void
@@ -777,9 +835,12 @@ g_file_info_set_attribute (GFileInfo  *info,
 
 /**
  * g_file_info_set_attribute_object:
- * @info:
- * @attribute:
- * @attr_value:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a #GObject.
+ * 
+ * Sets the @attribute to contain the given @attr_value, 
+ * if possible.
  * 
  **/
 void
@@ -800,9 +861,12 @@ g_file_info_set_attribute_object (GFileInfo  *info,
 
 /**
  * g_file_info_set_attribute_string:
- * @info:
- * @attribute:
- * @attr_value:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a string.
+ * 
+ * Sets the @attribute to contain the given @attr_value, 
+ * if possible.
  *
  **/
 void
@@ -823,9 +887,12 @@ g_file_info_set_attribute_string (GFileInfo  *info,
 
 /**
  * g_file_info_set_attribute_byte_string:
- * @info:
- * @attribute:
- * @attr_value:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a byte string.
+ * 
+ * Sets the @attribute to contain the given @attr_value, 
+ * if possible.
  * 
  **/
 void
@@ -846,9 +913,12 @@ g_file_info_set_attribute_byte_string (GFileInfo  *info,
 
 /**
  * g_file_info_set_attribute_boolean:
- * @info:
- * @attribute:
- * @attr_value:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a boolean value.
+ * 
+ * Sets the @attribute to contain the given @attr_value, 
+ * if possible.
  * 
  **/
 void
@@ -868,9 +938,12 @@ g_file_info_set_attribute_boolean (GFileInfo  *info,
 
 /**
  * g_file_info_set_attribute_uint32:
- * @info:
- * @attribute:
- * @attr_value:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: an unsigned 32-bit integer.
+ * 
+ * Sets the @attribute to contain the given @attr_value, 
+ * if possible.
  * 
  **/
 
@@ -892,9 +965,12 @@ g_file_info_set_attribute_uint32 (GFileInfo  *info,
 
 /**
  * g_file_info_set_attribute_int32:
- * @info:
- * @attribute:
- * @attr_value:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: a signed 32-bit integer
+ * 
+ * Sets the @attribute to contain the given @attr_value, 
+ * if possible.
  * 
  **/
 void
@@ -914,9 +990,12 @@ g_file_info_set_attribute_int32  (GFileInfo  *info,
 
 /**
  * g_file_info_set_attribute_uint64:
- * @info:
- * @attribute:
- * @attr_value:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ * @attr_value: an unsigned 64-bit integer.
+ * 
+ * Sets the @attribute to contain the given @attr_value, 
+ * if possible.
  * 
  **/
 void
@@ -936,10 +1015,13 @@ g_file_info_set_attribute_uint64 (GFileInfo  *info,
 
 /**
  * g_file_info_set_attribute_int64:
- * @info:
+ * @info: a #GFileInfo.
  * @attribute: attribute name to set.
  * @attr_value: int64 value to set attribute to.
  * 
+ * Sets the @attribute to contain the given @attr_value, 
+ * if possible.
+ * 
  **/
 void
 g_file_info_set_attribute_int64  (GFileInfo  *info,
@@ -961,6 +1043,9 @@ g_file_info_set_attribute_int64  (GFileInfo  *info,
  * g_file_info_get_file_type:
  * @info: a #GFileInfo.
  * 
+ * Gets a file's type (whether it is a regular file, symlink, etc). 
+ * This is different from the file's content type, see g_file_info_get_content_type().
+ * 
  * Returns: a #GFileType for the given file.
  **/
 GFileType
@@ -982,6 +1067,8 @@ g_file_info_get_file_type (GFileInfo *info)
  * g_file_info_get_is_hidden:
  * @info: a #GFileInfo.
  * 
+ * Checks if a file is hidden.
+ * 
  * Returns: %TRUE if the file is a hidden file, %FALSE otherwise.
  **/
 gboolean
@@ -1003,7 +1090,9 @@ g_file_info_get_is_hidden (GFileInfo *info)
  * g_file_info_get_is_backup:
  * @info: a #GFileInfo.
  * 
- * Returns: %TRUE if file is a backup file (.*~), %FALSE otherwise.
+ * Checks if a file is a backup file.
+ * 
+ * Returns: %TRUE if file is a backup file, %FALSE otherwise.
  **/
 gboolean
 g_file_info_get_is_backup (GFileInfo *info)
@@ -1024,6 +1113,8 @@ g_file_info_get_is_backup (GFileInfo *info)
  * g_file_info_get_is_symlink:
  * @info: a #GFileInfo.
  * 
+ * Checks if a file is a symlink.
+ * 
  * Returns: %TRUE if the given @info is a symlink.
  **/
 gboolean
@@ -1045,7 +1136,9 @@ g_file_info_get_is_symlink (GFileInfo *info)
  * g_file_info_get_name:
  * @info: a #GFileInfo.
  * 
- * Returns: 
+ * Gets the name for a file.
+ * 
+ * Returns: a string containing the file name.
  **/
 const char *
 g_file_info_get_name (GFileInfo *info)
@@ -1066,7 +1159,9 @@ g_file_info_get_name (GFileInfo *info)
  * g_file_info_get_display_name:
  * @info: a #GFileInfo.
  * 
- * Returns: 
+ * Gets a display name for a file.
+ * 
+ * Returns: a string containing the display name.
  **/
 const char *
 g_file_info_get_display_name (GFileInfo *info)
@@ -1087,7 +1182,9 @@ g_file_info_get_display_name (GFileInfo *info)
  * g_file_info_get_edit_name:
  * @info: a #GFileInfo.
  * 
- * Returns: 
+ * Gets the edit name for a file.
+ * 
+ * Returns: a string containing the edit name.
  **/
 const char *
 g_file_info_get_edit_name (GFileInfo *info)
@@ -1108,6 +1205,8 @@ g_file_info_get_edit_name (GFileInfo *info)
  * g_file_info_get_icon:
  * @info: a #GFileInfo.
  * 
+ * Gets the icon for a file.
+ * 
  * Returns: #GIcon for the given @info.
  **/
 GIcon *
@@ -1133,7 +1232,9 @@ g_file_info_get_icon (GFileInfo *info)
  * g_file_info_get_content_type:
  * @info: a #GFileInfo.
  * 
- * Returns: 
+ * Gets the file's content type.
+ * 
+ * Returns: a string containing the file's content type.s
  **/
 const char *
 g_file_info_get_content_type (GFileInfo *info)
@@ -1154,7 +1255,9 @@ g_file_info_get_content_type (GFileInfo *info)
  * g_file_info_get_size:
  * @info: a #GFileInfo.
  * 
- * Returns: goffset. 
+ * Gets the file's size.
+ * 
+ * Returns: a #goffset containing the file's size. 
  **/
 goffset
 g_file_info_get_size (GFileInfo *info)
@@ -1174,7 +1277,10 @@ g_file_info_get_size (GFileInfo *info)
 /**
  * g_file_info_get_modification_time:
  * @info: a #GFileInfo.
- * @result:
+ * @result: a #GTimeVal.
+ * 
+ * Gets the modification time of the current @info and sets it
+ * in @result.
  * 
  **/
 
@@ -1204,7 +1310,9 @@ g_file_info_get_modification_time (GFileInfo *info,
  * g_file_info_get_symlink_target:
  * @info: a #GFileInfo.
  * 
- * Returns: 
+ * Gets the symlink target for a given #GFileInfo.
+ * 
+ * Returns: a string containing the symlink target.
  **/
 const char *
 g_file_info_get_symlink_target (GFileInfo *info)
@@ -1225,7 +1333,10 @@ g_file_info_get_symlink_target (GFileInfo *info)
  * g_file_info_get_etag:
  * @info: a #GFileInfo.
  * 
- * Returns: 
+ * Gets the entity tag for a given #GFileInfo. 
+ * See %G_FILE_ATTRIBUTE_ETAG_VALUE.
+ * 
+ * Returns: a string containing the value of the "etag:value" attribute.
  **/
 const char *
 g_file_info_get_etag (GFileInfo *info)
@@ -1246,7 +1357,10 @@ g_file_info_get_etag (GFileInfo *info)
  * g_file_info_get_sort_order:
  * @info: a #GFileInfo.
  * 
- * Returns:
+ * Gets the value of the sort_order attribute from the #GFileInfo.
+ * See %G_FILE_ATTRIBUTE_STD_SORT_ORDER.
+ * 
+ * Returns: a #gint32 containing the value of the "std:sort_order" attribute.
  **/
 gint32
 g_file_info_get_sort_order (GFileInfo *info)
@@ -1267,8 +1381,10 @@ g_file_info_get_sort_order (GFileInfo *info)
 /**
  * g_file_info_set_file_type:
  * @info: a #GFileInfo.
- * @type:
- *  
+ * @type: a #GFileType.
+ * 
+ * Sets the file type in a #GFileInfo to @type.
+ * See %G_FILE_ATTRIBUTE_STD_TYPE.
  **/
 void
 g_file_info_set_file_type (GFileInfo         *info,
@@ -1290,8 +1406,10 @@ g_file_info_set_file_type (GFileInfo         *info,
 /**
  * g_file_info_set_is_hidden:
  * @info: a #GFileInfo.
- * @is_hidden:
+ * @is_hidden: a #gboolean.
  * 
+ * Sets the "is_hidden" attribute in a #GFileInfo according to @is_symlink.
+ * See %G_FILE_ATTRIBUTE_STD_IS_HIDDEN.
  **/
 void
 g_file_info_set_is_hidden (GFileInfo *info,
@@ -1313,7 +1431,10 @@ g_file_info_set_is_hidden (GFileInfo *info,
 /**
  * g_file_info_set_is_symlink:
  * @info: a #GFileInfo.
- * @is_symlink:
+ * @is_symlink: a #gboolean.
+ * 
+ * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink.
+ * See %G_FILE_ATTRIBUTE_STD_IS_SYMLINK.
  * 
  **/
 void
@@ -1336,7 +1457,10 @@ g_file_info_set_is_symlink (GFileInfo *info,
 /**
  * g_file_info_set_name:
  * @info: a #GFileInfo.
- * @name:
+ * @name: a string containing a name.
+ * 
+ * Sets the name attribute for the current #GFileInfo. 
+ * See %G_FILE_ATTRIBUTE_STD_NAME.
  * 
  **/
 void
@@ -1360,7 +1484,10 @@ g_file_info_set_name (GFileInfo         *info,
 /**
  * g_file_info_set_display_name:
  * @info: a #GFileInfo.
- * @display_name:
+ * @display_name: a string containing a display name.
+ * 
+ * Sets the display name for the current #GFileInfo.
+ * See %G_FILE_ATTRIBUTE_STD_DISPLAY_NAME.
  *  
  **/
 void
@@ -1384,7 +1511,10 @@ g_file_info_set_display_name (GFileInfo         *info,
 /**
  * g_file_info_set_edit_name:
  * @info: a #GFileInfo.
- * @edit_name:
+ * @edit_name: a string containing an edit name.
+ * 
+ * Sets the edit name for the current file.
+ * See %G_FILE_ATTRIBUTE_STD_EDIT_NAME.
  * 
  **/
 
@@ -1409,7 +1539,10 @@ g_file_info_set_edit_name (GFileInfo         *info,
 /**
  * g_file_info_set_icon:
  * @info: a #GFileInfo.
- * @icon:
+ * @icon: a #GIcon.
+ * 
+ * Sets the icon for a given #GFileInfo. 
+ * See %G_FILE_ATTRIBUTE_STD_ICON.
  *
  **/
 void
@@ -1433,7 +1566,10 @@ g_file_info_set_icon (GFileInfo   *info,
 /**
  * g_file_info_set_content_type:
  * @info: a #GFileInfo.
- * @content_type:
+ * @content_type: a content type. See #GContentType.
+ * 
+ * Sets the content type attribute for a given #GFileInfo.
+ * See %G_FILE_ATTRIBUTE_STD_CONTENT_TYPE.
  *
  **/
 void
@@ -1457,7 +1593,10 @@ g_file_info_set_content_type (GFileInfo         *info,
 /**
  * g_file_info_set_size:
  * @info: a #GFileInfo.
- * @size:
+ * @size: a #goffset containing the file's size.
+ * 
+ * Sets the %G_FILE_ATTRIBUTE_STD_SIZE attribute in the file info 
+ * to the given size.
  * 
  **/
 void
@@ -1480,7 +1619,10 @@ g_file_info_set_size (GFileInfo         *info,
 /**
  * g_file_info_set_modification_time
  * @info: a #GFileInfo.
- * @mtime:
+ * @mtime: a #GTimeVal.
+ * 
+ * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file
+ * info to the given time value.
  * 
  **/
 void
@@ -1510,7 +1652,10 @@ g_file_info_set_modification_time (GFileInfo         *info,
 /**
  * g_file_info_set_symlink_target:
  * @info: a #GFileInfo.
- * @symlink_target:
+ * @symlink_target: a static string containing a path to a symlink target.
+ * 
+ * Sets the %G_FILE_ATTRIBUTE_STD_SYMLINK_TARGET attribute in the file info 
+ * to the given symlink target.
  * 
  **/
 void
@@ -1534,7 +1679,10 @@ g_file_info_set_symlink_target (GFileInfo         *info,
 /**
  * g_file_info_set_sort_order:
  * @info: a #GFileInfo.
- * @sort_order:
+ * @sort_order: a sort order integer.
+ * 
+ * Sets the sort order attribute in the file info structure. See 
+ * %G_FILE_ATTRIBUTE_STD_SORT_ORDER.
  * 
  **/
 void
@@ -1559,6 +1707,17 @@ g_file_info_set_sort_order (GFileInfo         *info,
 #define MEGABYTE_FACTOR (1024.0 * 1024.0)
 #define GIGABYTE_FACTOR (1024.0 * 1024.0 * 1024.0)
 
+/**
+ * g_format_file_size_for_display:
+ * @size: a file size.
+ * 
+ * Formats a file size into a human readable string. Sizes are rounded
+ * to the nearest metric prefix and are displayed rounded to the nearest 
+ * tenth. E.g. the file size 3292528 bytes will be converted into the string 
+ * "3.1 MB".
+ * 
+ * Returns: a formatted string containing a human readable file size.
+ **/
 char *
 g_format_file_size_for_display (goffset size)
 {
@@ -1647,10 +1806,34 @@ matcher_add (GFileAttributeMatcher *matcher,
 }
 
 /**
- * g_file_attribute_matcher_new
- * @attributes:
+ * g_file_attribute_matcher_new:
+ * @attributes: an attribute string to match.
  * 
- * Returns: #GFileAttributeMatcher.
+ * Creates a new file attribute matcher, which matches attributes against
+ * a given string. #GFileAttributeMatcher<!-- -->s are reference counted structures, 
+ * and are created with a reference count of 1. If the number of references
+ * falls to 0, the #GFileAttributeMatcher is automatically destroyed.
+ * 
+ * The @attribute string should be formatted with specific keys separated
+ * from namespaces with a colon. Several "namespace:key" strings may be 
+ * concatenated with a single comma (e.g. "std:type,std:is_hidden"). 
+ * The wildcard "*" may be used to match all keys and namespaces, or "namespace:*" will 
+ * match all keys in a given namespace. 
+ * 
+ * Examples of strings to use:
+ * <table>
+ * <title>File Attribute Matcher strings and results</title>
+ * <tgroup cols='2' align='left'><thead>
+ * <row><entry> Matcher String </entry><entry> Matches </entry></row></thead>
+ * <tbody>
+ * <row><entry>"*"</entry><entry>matches all attributes.</entry></row>
+ * <row><entry>"std:is_hidden"</entry><entry>matches only the key is_hidden in the std namespace.</entry></row>
+ * <row><entry>"std:type,unix:*"</entry><entry>matches the type key in the std namespace and all keys in the unix 
+ * namespace.</entry></row>
+ * </tbody></tgroup>
+ * </table>
+ * 
+ * Returns: a #GFileAttributeMatcher.
  **/
 GFileAttributeMatcher *
 g_file_attribute_matcher_new (const char *attributes)
@@ -1707,6 +1890,8 @@ g_file_attribute_matcher_new (const char *attributes)
  * g_file_attribute_matcher_ref:
  * @matcher: a #GFileAttributeMatcher.
  * 
+ * References a file attribute matcher.
+ * 
  * Returns: a #GFileAttributeMatcher.
  **/
 GFileAttributeMatcher *
@@ -1746,9 +1931,12 @@ g_file_attribute_matcher_unref (GFileAttributeMatcher *matcher)
 /**
  * g_file_attribute_matcher_matches_only:
  * @matcher: a #GFileAttributeMatcher.
- * @attribute:
+ * @attribute: a file attribute key.
  * 
- * Returns: 
+ * Checks if a attribute matcher only matches a given attribute. Always
+ * returns %FALSE if "*" was used when creating the matcher.
+ * 
+ * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise.
  **/
 gboolean
 g_file_attribute_matcher_matches_only (GFileAttributeMatcher *matcher,
@@ -1817,9 +2005,13 @@ g_file_attribute_matcher_matches_id (GFileAttributeMatcher *matcher,
 /**
  * g_file_attribute_matcher_matches:
  * @matcher: a #GFileAttributeMatcher.
- * @attribute:
+ * @attribute: a file attribute key.
+ *
+ * Checks if an attribute will be matched by an attribute matcher. If 
+ * the matcher was created with the "*" matching string, this function
+ * will always return %TRUE.
  * 
- * Returns: 
+ * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise.
  **/
 gboolean
 g_file_attribute_matcher_matches (GFileAttributeMatcher *matcher,
@@ -1838,9 +2030,17 @@ g_file_attribute_matcher_matches (GFileAttributeMatcher *matcher,
 /**
  * g_file_attribute_matcher_enumerate_namespace:
  * @matcher: a #GFileAttributeMatcher.
- * @ns:
+ * @ns: a string containing a file attribute namespace.
+ * 
+ * Checks if the matcher will match all of the keys in a given namespace.
+ * This will always return %TRUE if a wildcard character is in use (e.g. if 
+ * matcher was created with "std:*" and @ns is "std", or if matcher was created
+ * using "*" and namespace is anything.) 
  * 
- * Returns: %TRUE, %FALSE.
+ * TODO: this is awkwardly worded.
+ * 
+ * Returns: %TRUE if the matcher matches all of the entries
+ * in the given @ns, %FALSE otherwise.
  **/
 gboolean
 g_file_attribute_matcher_enumerate_namespace (GFileAttributeMatcher *matcher,
@@ -1884,7 +2084,10 @@ g_file_attribute_matcher_enumerate_namespace (GFileAttributeMatcher *matcher,
  * g_file_attribute_matcher_enumerate_next:
  * @matcher: a #GFileAttributeMatcher.
  * 
- * Returns: 
+ * Gets the next matched attribute from a #GFileAttributeMatcher.
+ * 
+ * Returns: a string containing the next attribute or %NULL if 
+ * no more attribute exist.
  **/
 const char *
 g_file_attribute_matcher_enumerate_next (GFileAttributeMatcher *matcher)
diff --git a/gio/gfileinfo.h b/gio/gfileinfo.h
index 480d6a6de..c8ab32694 100644
--- a/gio/gfileinfo.h
+++ b/gio/gfileinfo.h
@@ -36,10 +36,33 @@ G_BEGIN_DECLS
 #define G_IS_FILE_INFO_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_INFO))
 #define G_FILE_INFO_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_INFO, GFileInfoClass))
 
+/**
+ * GFileInfo:
+ * 
+ * Stores information about a file system object referenced by a #GFile.
+ **/
 typedef struct _GFileInfo        GFileInfo;
 typedef struct _GFileInfoClass   GFileInfoClass;
+
+/**
+ * GFileAttributeMatcher:
+ * 
+ * Determines if a string matches a file attribute.
+ **/
 typedef struct _GFileAttributeMatcher GFileAttributeMatcher;
 
+/**
+ * GFileType:
+ * @G_FILE_TYPE_UNKNOWN: File's type is unknown.
+ * @G_FILE_TYPE_REGULAR: File handle represents a regular file.
+ * @G_FILE_TYPE_DIRECTORY: File handle represents a directory.
+ * @G_FILE_TYPE_SYMBOLIC_LINK: File handle represents a symbolic link (Unix systems)
+ * @G_FILE_TYPE_SPECIAL: File is a "special" file, such as a socket, fifo, blockdev,  or chardev.
+ * @G_FILE_TYPE_SHORTCUT: File is a shortcut (Windows systems)
+ * @G_FILE_TYPE_MOUNTABLE: File is a mountable location.
+ * 
+ * Indicates the file's on-disk type.
+ **/
 typedef enum {
   G_FILE_TYPE_UNKNOWN = 0,
   G_FILE_TYPE_REGULAR,
@@ -51,102 +74,537 @@ typedef enum {
 } GFileType;
 
 /* Common Attributes:  */
-
+/**
+ * G_FILE_ATTRIBUTE_STD_TYPE:
+ * 
+ * A key in the "std" namespace for storing file types. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * The value for this key should contain a #GFileType.
+ **/
 #define G_FILE_ATTRIBUTE_STD_TYPE "std:type"                     /* uint32 (GFileType) */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_IS_HIDDEN:
+ * 
+ * A key in the "std" namespace for checking if a file is hidden. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_STD_IS_HIDDEN "std:is_hidden"           /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_IS_BACKUP:
+ * 
+ * A key in the "std" namespace for checking if a file is a backup file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_STD_IS_BACKUP "std:is_backup"           /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_IS_SYMLINK:
+ * 
+ * A key in the "std" namespace for checking if the file is a symlink.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_STD_IS_SYMLINK "std:is_symlink"         /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_IS_VIRTUAL:
+ * 
+ * A key in the "std" namespace for checking if a file is virtual.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_STD_IS_VIRTUAL "std:is_virtual"         /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_NAME:
+ * 
+ * A key in the "std" namespace for getting the name of the file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_STD_NAME "std:name"                     /* byte string */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_DISPLAY_NAME:
+ * 
+ * A key in the "std" namespace for getting the display name of the file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_STD_DISPLAY_NAME "std:display_name"     /* string */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_EDIT_NAME:
+ * 
+ * A key in the "std" namespace for edit name of the file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_STD_EDIT_NAME "std:edit_name"           /* string */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_COPY_NAME:
+ * 
+ * A key in the "std" namespace for getting the copy name of the file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_STD_COPY_NAME "std:copy_name"           /* string */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_ICON:
+ * 
+ * A key in the "std" namespace for getting the icon for the file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT.
+ * The value for this key should contain a #GIcon.
+ **/
 #define G_FILE_ATTRIBUTE_STD_ICON "std:icon"                     /* object (GIcon) */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_CONTENT_TYPE:
+ * 
+ * A key in the "std" namespace for getting the content type of the file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * The value for this key should contain a valid content type.
+ **/
 #define G_FILE_ATTRIBUTE_STD_CONTENT_TYPE "std:content_type"     /* string */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_FAST_CONTENT_TYPE:
+ * 
+ * A key in the "std" namespace for getting the fast content type.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * 
+ **/
 #define G_FILE_ATTRIBUTE_STD_FAST_CONTENT_TYPE "std:fast_content_type" /* string */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_SIZE:
+ * 
+ * A key in the "std" namespace for getting the file's size.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ **/
 #define G_FILE_ATTRIBUTE_STD_SIZE "std:size"                     /* uint64 */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_SYMLINK_TARGET:
+ * 
+ * A key in the "std" namespace for getting the symlink target, if the file
+ * is a symlink. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_STD_SYMLINK_TARGET "std:symlink_target" /* byte string */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_TARGET_URI:
+ * 
+ * A key in the "std" namespace for getting the target URI for the file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_STD_TARGET_URI "std:target_uri"         /* string */
+
+/**
+ * G_FILE_ATTRIBUTE_STD_SORT_ORDER:
+ * 
+ * A key in the "std" namespace for setting the sort order of a file. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32.
+ * An example use would be in file managers, which would use this key to set 
+ * the order files are displayed.
+ **/
 #define G_FILE_ATTRIBUTE_STD_SORT_ORDER "std:sort_order"         /* int32  */
 
 /* Entity tags, used to avoid missing updates on save */
-
+/**
+ * G_FILE_ATTRIBUTE_ETAG_VALUE:
+ * 
+ * A key in the "etag" namespace for getting the value of the file's
+ * entity tag. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_ETAG_VALUE "etag:value"                 /* string */
 
 /* File identifier, for e.g. avoiding loops when doing recursive directory scanning */
-
+/**
+ * G_FILE_ATTRIBUTE_ID_FILE:
+ * 
+ * A key in the "id" namespace for getting a file identifier.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * An example use would be during listing files, to avoid recursive
+ * directory scanning.
+ **/
 #define G_FILE_ATTRIBUTE_ID_FILE "id:file"                     /* string */
+
+/**
+ * G_FILE_ATTRIBUTE_ID_FS:
+ * 
+ * A key in the "id" namespace for getting the file system identifier.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * An example use would be during listing files, to avoid recursive
+ * directory scanning.
+ **/
 #define G_FILE_ATTRIBUTE_ID_FS "id:fs"                         /* string */
 
 /* Calculated Access Rights for current user */
 
+/**
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_READ:
+ * 
+ * A key in the "access" namespace for getting read privilidges. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This key will be true if the user is able to read the file.
+ **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_READ "access:can_read"       /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE:
+ * 
+ * A key in the "access" namespace for getting write privilidges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This key will be true if the user is able to write to the file.
+ **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE "access:can_write"     /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE:
+ * 
+ * A key in the "access" namespace for getting execution privilidges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This key will be true if the user is able to execute the file.
+ **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE "access:can_execute" /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE:
+ * 
+ * A key in the "access" namespace for checking deletion privilidges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This key will be true if the user is able to delete the file.
+ **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE "access:can_delete"   /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH:
+ * 
+ * A key in the "access" namespace for checking trashing privilidges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This key will be true if the user is able to send the file to the 
+ * virtual file system trash location.
+ **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH "access:can_trash"     /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME:
+ * 
+ * A key in the "access" namespace for checking renaming privilidges.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * This key will be true if the user is able to rename the file.
+ **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME "access:can_rename"   /* boolean */ 
 /* TODO: Should we have special version for directories? can_enumerate, etc */
 
 /* Mountable attributes */
-
+/**
+ * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT:
+ * 
+ * A key in the "mountable" namespace for checking if a file is mountable.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT "mountable:can_mount"     /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT:
+ * 
+ * A key in the "mountable" namespace for checking if a file is unmountable.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT "mountable:can_unmount" /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT:
+ * 
+ * A key in the "mountable" namespace for checking if a file can be ejected.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT "mountable:can_eject"     /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE:
+ * 
+ * A key in the "mountable" namespace for getting the unix device.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ **/
 #define G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE "mountable:unix_device" /* uint32 */
+
+/**
+ * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI:
+ * 
+ * A key in the "mountable" namespace for getting the HAL UDI for the mounted
+ * file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI "mountable:hal_udi"         /* string */
 
 /* Time attributes */
 
   /* The last time the file content or an attribute was modified */
+/**
+ * G_FILE_ATTRIBUTE_TIME_MODIFIED:
+ * 
+ * A key in the "time" namespace for getting the time the file was last
+ * modified. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, 
+ * and contains the UNIX time since the file was modified.
+ **/
 #define G_FILE_ATTRIBUTE_TIME_MODIFIED "time:modified"           /* uint64 */
+
+/**
+ * G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC:
+ * 
+ * A key in the "time" namespace for getting the milliseconds of the time
+ * the file was last modified. This should be used in conjunction with 
+ * #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ **/
 #define G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC "time:modified_usec" /* uint32 */
   /* The last time the file was read */
+/**
+ * G_FILE_ATTRIBUTE_TIME_ACCESS:
+ * 
+ * A key in the "time" namespace for getting the time the file was last
+ * accessed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, 
+ * and contains the UNIX time since the file was last accessed.
+ **/
 #define G_FILE_ATTRIBUTE_TIME_ACCESS "time:access"               /* uint64 */
+/**
+ * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC:
+ * 
+ * A key in the "time" namespace for getting the milliseconds of the time
+ * the file was last accessed. This should be used in conjunction with
+ * #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ **/
 #define G_FILE_ATTRIBUTE_TIME_ACCESS_USEC "time:access_usec"     /* uint32 */
   /* The last time a file attribute was changed (e.g. unix ctime) */
+/**
+ * G_FILE_ATTRIBUTE_TIME_CHANGED:
+ * 
+ * A key in the "time" namespace for getting the time the file was last
+ * changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, 
+ * and contains the UNIX time since the file was last changed.
+ **/
 #define G_FILE_ATTRIBUTE_TIME_CHANGED "time:changed"             /* uint64 */
+/**
+ * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC:
+ * 
+ * A key in the "time" namespace for getting the milliseconds of the time
+ * the file was last changed. This should be used in conjunction with
+ * #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32. 
+ **/
 #define G_FILE_ATTRIBUTE_TIME_CHANGED_USEC "time:changed_usec"   /* uint32 */
   /* When the file was originally created (e.g. ntfs ctime) */
+/**
+ * G_FILE_ATTRIBUTE_TIME_CREATED:
+ * 
+ * A key in the "time" namespace for getting the time the file was created.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, 
+ * and contains the UNIX time since the file was created.
+ **/
 #define G_FILE_ATTRIBUTE_TIME_CREATED "time:created"             /* uint64 */
+
+/**
+ * G_FILE_ATTRIBUTE_TIME_CREATED_USEC:
+ * 
+ * A key in the "time" namespace for getting the milliseconds of the time
+ * the file was created. This should be used in conjunction with
+ * #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32. 
+ **/
 #define G_FILE_ATTRIBUTE_TIME_CREATED_USEC "time:created_usec"   /* uint32 */
 
 /* Unix specific attributes */
-
+/**
+ * G_FILE_ATTRIBUTE_UNIX_DEVICE:
+ * 
+ * A key in the "unix" namespace for getting the device id of the device the 
+ * file is located on (see man stat(2)). This attribute is only available 
+ * for UNIX file systems. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32. 
+ * 
+ **/
 #define G_FILE_ATTRIBUTE_UNIX_DEVICE "unix:device"               /* uint32 */
+/**
+ * G_FILE_ATTRIBUTE_UNIX_INODE:
+ * 
+ * A key in the "unix" namespace for getting the inode of the file.
+ * This attribute is only available for UNIX file systems. Corresponding 
+ * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ **/
 #define G_FILE_ATTRIBUTE_UNIX_INODE "unix:inode"                 /* uint64 */
+/**
+ * G_FILE_ATTRIBUTE_UNIX_MODE:
+ * 
+ * A key in the "unix" namespace for getting the mode of the file (e.g. whether the file 
+ * is a regular file, symlink, etc). See man lstat(2). This attribute is only available 
+ * for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ **/
 #define G_FILE_ATTRIBUTE_UNIX_MODE "unix:mode"                   /* uint32 */
+
+/**
+ * G_FILE_ATTRIBUTE_UNIX_NLINK:
+ * 
+ * A key in the "unix" namespace for getting the number of hard links for a 
+ * file. See man lstat(2). This attribute is only available for UNIX file systems. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * 
+ **/
 #define G_FILE_ATTRIBUTE_UNIX_NLINK "unix:nlink"                 /* uint32 */
+/**
+ * G_FILE_ATTRIBUTE_UNIX_UID:
+ * 
+ * A key in the "unix" namespace for getting the user ID for the file. 
+ * This attribute is only available for UNIX file systems. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ **/
 #define G_FILE_ATTRIBUTE_UNIX_UID "unix:uid"                     /* uint32 */
+/**
+ * G_FILE_ATTRIBUTE_UNIX_GID:
+ * 
+ * A key in the "unix" namespace for getting the group ID for the file.
+ * This attribute is only available for UNIX file systems. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ **/
 #define G_FILE_ATTRIBUTE_UNIX_GID "unix:gid"                     /* uint32 */
+/**
+ * G_FILE_ATTRIBUTE_UNIX_RDEV:
+ * 
+ * A key in the "unix" namespace for getting the device ID for the file (if it 
+ * is a special file). See man lstat(2). This attribute is only available for 
+ * UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ **/
 #define G_FILE_ATTRIBUTE_UNIX_RDEV "unix:rdev"                   /* uint32 */
+/**
+ * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE:
+ * 
+ * A key in the "unix" namespace for getting the block size for the file system.
+ * This attribute is only available for UNIX file systems. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ **/
 #define G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE "unix:block_size"       /* uint32 */
+/**
+ * G_FILE_ATTRIBUTE_UNIX_BLOCKS:
+ * 
+ * A key in the "unix" namespace for getting the number of blocks allocated for the file.
+ * This attribute is only available for UNIX file systems. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ **/
 #define G_FILE_ATTRIBUTE_UNIX_BLOCKS "unix:blocks"               /* uint64 */
+
+/**
+ * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT:
+ * 
+ * A key in the "unix" namespace for checking if the file represents a unix mount point.
+ * Returns %TRUE if the file is a unix mount point. This attribute is only available for 
+ * UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT "unix:is_mountpoint" /* boolean */
 
 /* DOS specific attributes */
-
+/**
+ * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE:
+ * 
+ * A key in the "dos" namespace for checking if the file's archive flag is set.
+ * Returns %TRUE if the archive flag is set. This attribute is only available for 
+ * DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE "dos:is_archive"         /* boolean */
+
+/**
+ * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM:
+ * 
+ * A key in the "dos" namespace for checking if the file's backup flag is set.
+ * Returns %TRUE if the backup flag is set. This attribute is only available for 
+ * DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_DOS_IS_SYSTEM "dos:is_system"           /* boolean */
 
 /* Owner attributes */
-
+/**
+ * G_FILE_ATTRIBUTE_OWNER_USER:
+ * 
+ * A key in the "owner" namespace for getting the user name of the file's owner.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_OWNER_USER "owner:user"                 /* string */
+
+/**
+ * G_FILE_ATTRIBUTE_OWNER_USER_REAL:
+ * 
+ * A key in the "owner" namespace for getting the real name of the user that owns the file.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_OWNER_USER_REAL "owner:user_real"       /* string */
+
+/**
+ * G_FILE_ATTRIBUTE_OWNER_GROUP:
+ * 
+ * A key in the "owner" namespace for getting the file owner's group.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_OWNER_GROUP "owner:group"               /* string */
 
 /* Thumbnails */
 
+/**
+ * G_FILE_ATTRIBUTE_THUMBNAIL_PATH:
+ * 
+ * A key in the "thumbnail" namespace for getting the path to the thumbnail image.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_THUMBNAIL_PATH "thumbnail:path"         /* bytestring */
-#define G_FILE_ATTRIBUTE_THUMBNAILING_FAILED "thumbnail:failed"         /* bytestring */
+/**
+ * G_FILE_ATTRIBUTE_THUMBNAIL_THUMNAILING_FAILED:
+ * 
+ * A key in the "thumbnail" namespace for checking if thumbnailing failed. 
+ * Is set to %TRUE if thumbnailing failed. Corresponding #GFileAttributeType 
+ * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. 
+ **/
+#define G_FILE_ATTRIBUTE_THUMBNAILING_FAILED "thumbnail:failed"         /* boolean */
 
 /* File system info (for g_file_get_filesystem_info) */
 
+/**
+ * G_FILE_ATTRIBUTE_FS_SIZE:
+ * 
+ * A key in the "fs" namespace for getting the size of the file system, used in
+ * g_file_get_filesystem_info(). Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ **/
 #define G_FILE_ATTRIBUTE_FS_SIZE "fs:size"                       /* uint64 */
+
+/**
+ * G_FILE_ATTRIBUTE_FS_FREE:
+ * 
+ * A key in the "fs" namespace for getting the free space left on the file system.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ **/
 #define G_FILE_ATTRIBUTE_FS_FREE "fs:free"                       /* uint64 */
+
+/**
+ * G_FILE_ATTRIBUTE_FS_TYPE:
+ * 
+ * A key in the "fs" namespace for getting the file system's type.
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_FS_TYPE "fs:type"                       /* string */
+
+/**
+ * G_FILE_ATTRIBUTE_FS_READONLY:
+ * 
+ * A key in the "fs" namespace for checking if the file system is read only.
+ * Is set to %TRUE if the file system is read only. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ **/
 #define G_FILE_ATTRIBUTE_FS_READONLY "fs:readonly"               /* boolean */
 
+/**
+ * G_FILE_ATTRIBUTE_GVFS_BACKEND:
+ * 
+ * A key in the "gvfs" namespace that gets the name of the current
+ * GVFS backend in use. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ **/
 #define G_FILE_ATTRIBUTE_GVFS_BACKEND "gvfs:backend"             /* string */
 
 GType g_file_info_get_type (void) G_GNUC_CONST;
diff --git a/gio/gfileinputstream.c b/gio/gfileinputstream.c
index 24c8a61fc..51b0ae0a2 100644
--- a/gio/gfileinputstream.c
+++ b/gio/gfileinputstream.c
@@ -28,6 +28,15 @@
 #include "gsimpleasyncresult.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gfileinputstream
+ * @short_description: file input streaming operations
+ * @see_also: #GInputStream, #GDataInputStream, #GSeekable.
+ * 
+ * 
+ *
+ **/
+
 static void       g_file_input_stream_seekable_iface_init    (GSeekableIface       *iface);
 static goffset    g_file_input_stream_seekable_tell          (GSeekable            *seekable);
 static gboolean   g_file_input_stream_seekable_can_seek      (GSeekable            *seekable);
@@ -89,12 +98,19 @@ g_file_input_stream_init (GFileInputStream *stream)
 
 /**
  * g_file_input_stream_query_info:
- * @stream:
- * @attributes:
+ * @stream: a #GFileInputStream.
+ * @attributes: a file attribute query string.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns: 
+ *
+ * Queries a file input stream the given @attributes.his function blocks while querying
+ * the stream. For the asynchronous (non-blocking) version of this function, see 
+ * g_file_input_stream_query_info_async(). While the stream is blocked, 
+ * the stream will set the pending flag internally, and any other operations on the 
+ * stream will fail with %G_IO_ERROR_PENDING.
+ *
+ * Returns: a #GFileInfo, or %NULL on error.
  **/
 GFileInfo *
 g_file_input_stream_query_info (GFileInputStream     *stream,
@@ -161,11 +177,19 @@ async_ready_callback_wrapper (GObject *source_object,
 
 /**
  * g_file_input_stream_query_info_async:
- * @stream:
- * @attributes:
- * @io_priority: the io priority of the request.
- * @cancellable: optional #GCancellable object, %NULL to ignore. @callback:
- * @user_data:
+ * @stream: a #GFileInputStream.
+ * @attributes: a file attribute query string.
+ * @io_priority: the i/o priority of the request.
+ * @cancellable: optional #GCancellable object, %NULL to ignore. 
+ * @callback: callback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
+ * 
+ * Queries the stream information asynchronously. For the synchronous version
+ * of this function, see g_file_input_stream_query_info(). 
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be set
  *  
  **/
 void
@@ -214,10 +238,13 @@ g_file_input_stream_query_info_async (GFileInputStream     *stream,
 
 /**
  * g_file_input_stream_query_info_finish:
- * @stream:
- * @result:
+ * @stream: a #GFileInputStream.
+ * @result: a #GAsyncResult.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
+ * 
+ * Finishes an asynchronous info query operation.
+ * 
  * Returns: #GFileInfo. 
  **/
 GFileInfo *
@@ -244,9 +271,11 @@ g_file_input_stream_query_info_finish (GFileInputStream     *stream,
 
 /**
  * g_file_input_stream_tell:
- * @stream:
+ * @stream: a #GFileInputStream.
+ * 
+ * Gets the current position in the stream.
  * 
- * Returns: 
+ * Returns: a #goffset with the position in the stream.
  **/
 goffset
 g_file_input_stream_tell (GFileInputStream  *stream)
@@ -273,7 +302,9 @@ g_file_input_stream_seekable_tell (GSeekable *seekable)
 
 /**
  * g_file_input_stream_can_seek:
- * @stream:
+ * @stream: a #GFileInputStream.
+ * 
+ * Checks if a file input stream can be seeked.
  * 
  * Returns: %TRUE if stream can be seeked. %FALSE otherwise.
  **/
@@ -306,13 +337,21 @@ g_file_input_stream_seekable_can_seek (GSeekable *seekable)
 
 /**
  * g_file_input_stream_seek:
- * @stream:
- * @offset:
- * @type:
+ * @stream: a #GFileInputStream.
+ * @offset: a #goffset to seek.
+ * @type: a #GSeekType.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns: 
+ * 
+ * Seeks in the file input stream.
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be set.
+ * 
+ * Returns: %TRUE if the stream was successfully seeked to the position.
+ * %FALSE on error.
  **/
 gboolean
 g_file_input_stream_seek (GFileInputStream  *stream,
diff --git a/gio/gfileinputstream.h b/gio/gfileinputstream.h
index ecf876634..9b61ed6d9 100644
--- a/gio/gfileinputstream.h
+++ b/gio/gfileinputstream.h
@@ -35,6 +35,12 @@ G_BEGIN_DECLS
 #define G_IS_FILE_INPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_INPUT_STREAM))
 #define G_FILE_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_INPUT_STREAM, GFileInputStreamClass))
 
+/**
+ * GFileInputStream:
+ * @parent: the parent #GInputStream instance.
+ * 
+ * Implements #GInputStream and #GSeekable for file input operations.
+ **/
 typedef struct _GFileInputStream         GFileInputStream;
 typedef struct _GFileInputStreamClass    GFileInputStreamClass;
 typedef struct _GFileInputStreamPrivate  GFileInputStreamPrivate;
@@ -71,7 +77,7 @@ struct _GFileInputStreamClass
   GFileInfo *(*query_info_finish) (GFileInputStream     *stream,
 				   GAsyncResult         *res,
 				   GError              **error);
-    
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gfilemonitor.c b/gio/gfilemonitor.c
index ba9fa561b..801034d8c 100644
--- a/gio/gfilemonitor.c
+++ b/gio/gfilemonitor.c
@@ -28,6 +28,15 @@
 #include "gvfs.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gfilemonitor
+ * @short_description: File Monitor
+ * @see_also: #GDirectoryMonitor
+ *
+ * Monitors a file for changes.
+ * 
+ **/
+
 enum {
   CHANGED,
   LAST_SIGNAL
@@ -103,6 +112,15 @@ g_file_monitor_class_init (GFileMonitorClass *klass)
   gobject_class->finalize = g_file_monitor_finalize;
   gobject_class->dispose = g_file_monitor_dispose;
 
+  /**
+   * GFileMonitor::changed:
+   * @monitor: a #GFileMonitor.
+   * @file: a #GFile.
+   * @other_file: a #GFile.
+   * @event_type: a #GFileMonitorEvent.
+   * 
+   * Emitted when a file has been changed. 
+   **/
   signals[CHANGED] =
     g_signal_new (I_("changed"),
 		  G_TYPE_FILE_MONITOR,
@@ -141,7 +159,9 @@ g_file_monitor_is_cancelled (GFileMonitor *monitor)
 
 /**
  * g_file_monitor_cancel:
- * @monitor:
+ * @monitor: a #GFileMonitor.
+ * 
+ * Cancels a file monitor.
  * 
  * Returns: %TRUE if monitor was cancelled.
  **/
@@ -318,10 +338,13 @@ cancel_virtual_changes_done (GFileMonitor *monitor)
 
 /**
  * g_file_monitor_emit_event:
- * @monitor:
- * @file:
- * @other_file:
- * @event_type:
+ * @monitor: a #GFileMonitor.
+ * @file: a #GFile.
+ * @other_file: a #GFile.
+ * @event_type: a #GFileMonitorEvent
+ * 
+ * Emits a file monitor event. This is mainly necessary for implementations
+ * of GFileMonitor.
  * 
  **/
 void
diff --git a/gio/gfilemonitor.h b/gio/gfilemonitor.h
index edb9f64be..bb96f6cad 100644
--- a/gio/gfilemonitor.h
+++ b/gio/gfilemonitor.h
@@ -35,6 +35,18 @@ G_BEGIN_DECLS
 #define G_IS_FILE_MONITOR_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_MONITOR))
 #define G_FILE_MONITOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_MONITOR, GFileMonitorClass))
 
+/**
+ * GFileMonitorEvent:
+ * @G_FILE_MONITOR_EVENT_CHANGED: Monitor file changed events.
+ * @G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT: Monitor file changed done events.
+ * @G_FILE_MONITOR_EVENT_DELETED: Monitors file deleted events.
+ * @G_FILE_MONITOR_EVENT_CREATED: Monitors file created events.
+ * @G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED: Monitors file attribute changed events.
+ * @G_FILE_MONITOR_EVENT_PRE_UNMOUNT: Monitors pre-unmount events.
+ * @G_FILE_MONITOR_EVENT_UNMOUNTED: Monitors unmount events.
+ * 
+ * Flags used when creating a #GFileMonitor to define what events to monitor for.
+ **/
 typedef enum {
   G_FILE_MONITOR_EVENT_CHANGED,
   G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT,
@@ -48,6 +60,11 @@ typedef enum {
 typedef struct _GFileMonitorClass	GFileMonitorClass;
 typedef struct _GFileMonitorPrivate	GFileMonitorPrivate;
 
+/**
+ * GFileMonitor:
+ * 
+ * Watches for changes within a #GFile.
+ **/
 struct _GFileMonitor
 {
   GObject parent;
@@ -69,7 +86,7 @@ struct _GFileMonitorClass
   /* Virtual Table */
   gboolean	(*cancel)(GFileMonitor* monitor);
 
-
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gfilenamecompleter.c b/gio/gfilenamecompleter.c
index c8d85d817..a7ef20705 100644
--- a/gio/gfilenamecompleter.c
+++ b/gio/gfilenamecompleter.c
@@ -27,6 +27,16 @@
 #include <string.h>
 #include "glibintl.h"
 
+/**
+ * SECTION:gfilenamecompleter
+ * @short_description: Filename Completer.
+ * 
+ * Completes partial file and directory names given a partial string by
+ * looking in the file system for clues. Can return a list of possible 
+ * completion strings for widget implementation.
+ * 
+ **/
+
 enum {
   GOT_COMPLETION_DATA,
   LAST_SIGNAL
@@ -84,7 +94,11 @@ g_filename_completer_class_init (GFilenameCompleterClass *klass)
   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
   
   gobject_class->finalize = g_filename_completer_finalize;
-
+  /**
+   * GFilenameCompleter::got-completion-data:
+   * 
+   * Emitted when the file name completion information comes available.
+   **/
   signals[GOT_COMPLETION_DATA] = g_signal_new (I_("got_completion_data"),
 					  G_TYPE_FILENAME_COMPLETER,
 					  G_SIGNAL_RUN_LAST,
@@ -102,7 +116,9 @@ g_filename_completer_init (GFilenameCompleter *completer)
 /**
  * g_filename_completer_new:
  * 
- * Returns: a new #GFilenameCompleter.
+ * Creates a new filename completer.
+ * 
+ * Returns: a #GFilenameCompleter.
  **/
 GFilenameCompleter *
 g_filename_completer_new (void)
@@ -439,6 +455,8 @@ g_filename_completer_get_completion_suffix (GFilenameCompleter *completer,
  * @completer: the filename completer.
  * @initial_text: text to be completed.
  * 
+ * Gets an array of completion strings for a given initial text.
+ * 
  * Returns: array of strings with possible completions for @initial_text.
  * This array must be freed by g_strfreev() when finished. 
  **/
@@ -474,7 +492,7 @@ g_filename_completer_get_completions (GFilenameCompleter *completer,
 /**
  * g_filename_completer_set_dirs_only:
  * @completer: the filename completer.
- * @dirs_only: 
+ * @dirs_only: a #gboolean.
  * 
  * If @dirs_only is %TRUE, @completer will only 
  * complete directory names, and not file names.
diff --git a/gio/gfilenamecompleter.h b/gio/gfilenamecompleter.h
index cf4cae198..4fd773458 100644
--- a/gio/gfilenamecompleter.h
+++ b/gio/gfilenamecompleter.h
@@ -34,6 +34,11 @@ G_BEGIN_DECLS
 #define G_IS_FILENAME_COMPLETER(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_FILENAME_COMPLETER))
 #define G_IS_FILENAME_COMPLETER_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILENAME_COMPLETER))
 
+/**
+ * GFilenameCompleter:
+ * 
+ * Completes filenames based on files that exist within the file system.
+ **/
 typedef struct _GFilenameCompleter GFilenameCompleter;
 typedef struct _GFilenameCompleterClass GFilenameCompleterClass;
 
@@ -44,6 +49,7 @@ struct _GFilenameCompleterClass {
   /* signals */
   void (* got_completion_data)	(GFilenameCompleter *filename_completer);
 
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gfileoutputstream.c b/gio/gfileoutputstream.c
index 40914d671..35eaf68b7 100644
--- a/gio/gfileoutputstream.c
+++ b/gio/gfileoutputstream.c
@@ -28,6 +28,15 @@
 #include "gsimpleasyncresult.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gfileoutputstream
+ * @short_description: file output streaming operations
+ * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable.
+ * 
+ * 
+ *
+ **/
+
 static void       g_file_output_stream_seekable_iface_init    (GSeekableIface       *iface);
 static goffset    g_file_output_stream_seekable_tell          (GSeekable            *seekable);
 static gboolean   g_file_output_stream_seekable_can_seek      (GSeekable            *seekable);
@@ -89,15 +98,29 @@ g_file_output_stream_init (GFileOutputStream *stream)
 /**
  * g_file_output_stream_query_info:
  * @stream: a #GFileOutputStream.
- * @attributes:
+ * @attributes: a file attribute query string.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
- * @error: a #GError location to store the error occuring, or %NULL to 
- * ignore.
+ * @error: a #GError, %NULL to ignore.
  *
- *  * Returns: %NULL or a #GFileInfo for the @stream.
+ * Queries a file output stream for the given @attributes. 
+ * This function blocks while querying the stream. For the asynchronous 
+ * version of this function, see g_file_output_stream_query_info_async(). 
+ * While the stream is blocked, the stream will set the pending flag 
+ * internally, and any other operations on the stream will fail with 
+ * %G_IO_ERROR_PENDING.
  * 
- * For the asynchronous version of this function, see 
- * g_file_output_stream_query_info_async(). 
+ * Can fail if the stream was already closed (with @error being set to 
+ * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being
+ * set to %G_IO_ERROR_PENDING), or if querying info is not supported for 
+ * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In
+ * all cases of failure, %NULL will be returned.
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will 
+ * be returned. 
+ * 
+ * Returns: a #GFileInfo for the @stream, or %NULL on error.
  **/
 GFileInfo *
 g_file_output_stream_query_info (GFileOutputStream      *stream,
@@ -165,11 +188,11 @@ async_ready_callback_wrapper (GObject *source_object,
 /**
  * g_file_output_stream_query_info_async:
  * @stream: a #GFileOutputStream.
- * @attributes:
+ * @attributes: a file attribute query string.
  * @io_priority: the io priority of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
- * @callback: a #GAsyncReadyCallback.
- * @user_data: user data for @callback.
+ * @callback: callback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
  * Asynchronously queries the @stream for a #GFileInfo. When completed,
  * @callback will be called with a #GAsyncResult which can be used to 
@@ -227,8 +250,7 @@ g_file_output_stream_query_info_async (GFileOutputStream     *stream,
  * g_file_output_stream_query_info_finish:
  * @stream: a #GFileOutputStream.
  * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occuring, or %NULL to 
- * ignore.
+ * @error: a #GError, %NULL to ignore.
  * 
  * Finalizes the asynchronous query started 
  * by g_file_output_stream_query_info_async().
@@ -259,9 +281,11 @@ g_file_output_stream_query_info_finish (GFileOutputStream     *stream,
 
 /**
  * g_file_output_stream_get_etag:
- * @stream: a #GFileOutputString.
+ * @stream: a #GFileOutputStream.
  * 
- * Returns: 
+ * Gets the entity tag for the file output stream.
+ * 
+ * Returns: the entity tag for the stream.
  **/
 char *
 g_file_output_stream_get_etag (GFileOutputStream  *stream)
@@ -291,9 +315,11 @@ g_file_output_stream_get_etag (GFileOutputStream  *stream)
 
 /**
  * g_file_output_stream_tell:
- * @stream:
+ * @stream: a #GFileOutputStream.
  * 
- * Returns: 
+ * Gets the current location within the stream.
+ * 
+ * Returns: a #goffset of the location within the stream.
  **/
 goffset
 g_file_output_stream_tell (GFileOutputStream  *stream)
@@ -320,9 +346,11 @@ g_file_output_stream_seekable_tell (GSeekable *seekable)
 
 /**
  * g_file_output_stream_can_seek:
- * @stream:
+ * @stream: a #GFileOutputStream.
+ * 
+ * Checks if the stream can be seeked.
  * 
- * Returns: 
+ * Returns: %TRUE if seeking is supported by the stream.
  **/
 gboolean
 g_file_output_stream_can_seek (GFileOutputStream  *stream)
@@ -353,13 +381,15 @@ g_file_output_stream_seekable_can_seek (GSeekable *seekable)
 
 /**
  * g_file_output_stream_seek:
- * @stream:
- * @offset:
- * @type:
+ * @stream: a #GFileOutputStream.
+ * @offset: a #goffset to seek.
+ * @type: a #GSeekType.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
- * @error: a #GError location to store the error occuring, or %NULL to 
- * ignore.
- * Returns: 
+ * @error: a #GError, %NULL to ignore.
+ * 
+ * Seeks to a location in a file output stream.
+ * 
+ * Returns: %TRUE if the seek was successful. %FALSE otherwise.
  **/
 gboolean
 g_file_output_stream_seek (GFileOutputStream  *stream,
@@ -426,7 +456,9 @@ g_file_output_stream_seekable_seek (GSeekable  *seekable,
 
 /**
  * g_file_output_stream_can_truncate:
- * @stream:
+ * @stream: a #GFileOutputStream.
+ * 
+ * Checks if the stream can be truncated.
  * 
  * Returns: %TRUE if stream can be truncated.
  **/
@@ -459,12 +491,14 @@ g_file_output_stream_seekable_can_truncate (GSeekable  *seekable)
 
 /**
  * g_file_output_stream_truncate:
- * @stream:
- * @size:
+ * @stream: a #GFileOutputStream.
+ * @size: a #goffset to truncate the stream at.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
- * @error: a #GError location to store the error occuring, or %NULL to 
- * ignore.
- * Returns: %TRUE if @stream is truncated.
+ * @error: a #GError, %NULL to ignore.
+ * 
+ * Truncates a file output stream.
+ * 
+ * Returns: %TRUE if @stream is truncated successfully.
  **/
 gboolean
 g_file_output_stream_truncate (GFileOutputStream  *stream,
diff --git a/gio/gfileoutputstream.h b/gio/gfileoutputstream.h
index 6525754e1..5cead47f8 100644
--- a/gio/gfileoutputstream.h
+++ b/gio/gfileoutputstream.h
@@ -35,6 +35,12 @@ G_BEGIN_DECLS
 #define G_IS_FILE_OUTPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_OUTPUT_STREAM))
 #define G_FILE_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_OUTPUT_STREAM, GFileOutputStreamClass))
 
+/**
+ * GFileOutputStream:
+ * @parent: The parent #GOutputStream instance.
+ *
+ * Implements #GOutputStream and #GSeekable for file output operations. 
+ **/
 typedef struct _GFileOutputStream         GFileOutputStream;
 typedef struct _GFileOutputStreamClass    GFileOutputStreamClass;
 typedef struct _GFileOutputStreamPrivate  GFileOutputStreamPrivate;
diff --git a/gio/gfilterinputstream.c b/gio/gfilterinputstream.c
index 6d2f99a33..edeac01ff 100644
--- a/gio/gfilterinputstream.c
+++ b/gio/gfilterinputstream.c
@@ -25,6 +25,12 @@
 #include "ginputstream.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gfilterinputstream
+ * @short_description: Filter Input Stream.
+ *
+ **/
+
 enum {
   PROP_0,
   PROP_BASE_STREAM
diff --git a/gio/gfilterinputstream.h b/gio/gfilterinputstream.h
index 331f9be68..e13635946 100644
--- a/gio/gfilterinputstream.h
+++ b/gio/gfilterinputstream.h
@@ -35,6 +35,11 @@ G_BEGIN_DECLS
 #define G_IS_FILTER_INPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_INPUT_STREAM))
 #define G_FILTER_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_INPUT_STREAM, GFilterInputStreamClass))
 
+/**
+ * GFilterInputStream:
+ * 
+ * Filtered input streams. Implements #GInputStream.
+ **/
 typedef struct _GFilterInputStream         GFilterInputStream;
 typedef struct _GFilterInputStreamClass    GFilterInputStreamClass;
 typedef struct _GFilterInputStreamPrivate  GFilterInputStreamPrivate;
@@ -50,7 +55,8 @@ struct _GFilterInputStream
 struct _GFilterInputStreamClass
 {
   GInputStreamClass parent_class;
-  
+
+  /*< private >*/  
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gfilteroutputstream.c b/gio/gfilteroutputstream.c
index ca41be5f9..a54683615 100644
--- a/gio/gfilteroutputstream.c
+++ b/gio/gfilteroutputstream.c
@@ -25,6 +25,12 @@
 #include "goutputstream.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gfilteroutputstream
+ * @short_description: Filter Output Stream
+ *
+ **/
+
 enum {
   PROP_0,
   PROP_BASE_STREAM
diff --git a/gio/gfilteroutputstream.h b/gio/gfilteroutputstream.h
index 604f9283d..1a131a59f 100644
--- a/gio/gfilteroutputstream.h
+++ b/gio/gfilteroutputstream.h
@@ -35,6 +35,11 @@ G_BEGIN_DECLS
 #define G_IS_FILTER_OUTPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_OUTPUT_STREAM))
 #define G_FILTER_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_OUTPUT_STREAM, GFilterOutputStreamClass))
 
+/**
+ * GFilterOutputStream:
+ * 
+ * Filtered output streams. Implements #GOutputStream.
+ **/
 typedef struct _GFilterOutputStream         GFilterOutputStream;
 typedef struct _GFilterOutputStreamClass    GFilterOutputStreamClass;
 typedef struct _GFilterOutputStreamPrivate  GFilterOutputStreamPrivate;
@@ -51,6 +56,7 @@ struct _GFilterOutputStreamClass
 {
  GOutputStreamClass parent_class;
 
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gicon.c b/gio/gicon.c
index 5913ac3ad..4b2bf3f4f 100644
--- a/gio/gicon.c
+++ b/gio/gicon.c
@@ -74,6 +74,8 @@ g_icon_base_init (gpointer g_class)
  * g_icon_hash:
  * @icon: #gconstpointer to an icon object.
  * 
+ * Gets a hash for an icon.
+ * 
  * Returns: a #guint containing a hash for the @icon, suitable for 
  * use in a #GHashTable or similar data structure.
  **/
@@ -94,6 +96,8 @@ g_icon_hash (gconstpointer icon)
  * @icon1: pointer to the first #GIcon.
  * @icon2: pointer to the second #GIcon.
  * 
+ * Checks if two icons are equal.
+ * 
  * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
  **/
 gboolean
diff --git a/gio/gicon.h b/gio/gicon.h
index 6c0dbc0de..039cbee98 100644
--- a/gio/gicon.h
+++ b/gio/gicon.h
@@ -32,10 +32,24 @@ G_BEGIN_DECLS
 #define G_IS_ICON(obj)	       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_ICON))
 #define G_ICON_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ICON, GIconIface))
 
+/**
+ * GIcon:
+ *
+ * Icons for file, content, drive and volume types.
+ **/
 typedef struct _GIcon         		GIcon; /* Dummy typedef */
 typedef struct _GIconIface    		GIconIface;
 
-
+/**
+ * GIconIface:
+ * @g_iface: The parent interface.
+ * @hash: A hash for a given #GIcon.
+ * @equal: Checks if two #GIcon<!-- -->s are equal.
+ *
+ * GIconIface is used to implement GIcon types for various
+ * different systems. See #GThemedIcon and #GLoadableIcon for
+ * examples of how to use this interface.
+ */
 struct _GIconIface
 {
   GTypeInterface g_iface;
diff --git a/gio/ginputstream.c b/gio/ginputstream.c
index 127f5200e..77def7016 100644
--- a/gio/ginputstream.c
+++ b/gio/ginputstream.c
@@ -28,6 +28,14 @@
 #include "gseekable.h"
 #include "gsimpleasyncresult.h"
 
+/**
+ * SECTION:ginputstream
+ * @short_description: base class for implementing streaming input
+ *
+ * 
+ * 
+ **/
+
 G_DEFINE_TYPE (GInputStream, g_input_stream, G_TYPE_OBJECT);
 
 struct _GInputStreamPrivate {
@@ -228,14 +236,14 @@ g_input_stream_read  (GInputStream  *stream,
  * read as many bytes as requested, only stopping on an error or end of stream.
  *
  * On a successful read of @count bytes, or if we reached the end of the
- * stream,  TRUE is returned, and @bytes_read is set to the number of bytes
+ * stream,  %TRUE is returned, and @bytes_read is set to the number of bytes
  * read into @buffer.
  * 
- * If there is an error during the operation FALSE is returned and @error
+ * If there is an error during the operation %FALSE is returned and @error
  * is set to indicate the error status, @bytes_read is updated to contain
  * the number of bytes read into @buffer before the error occured.
  *
- * Return value: TRUE on success, FALSE if there was an error
+ * Return value: %TRUE on success, %FALSE if there was an error
  **/
 gboolean
 g_input_stream_read_all (GInputStream              *stream,
@@ -407,6 +415,7 @@ g_input_stream_real_skip (GInputStream         *stream,
 /**
  * g_input_stream_close:
  * @stream: A #GInputStream.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: location to store the error occuring, or %NULL to ignore
  *
  * Closes the stream, releasing resources related to it.
@@ -604,11 +613,14 @@ g_input_stream_read_async (GInputStream        *stream,
 
 /**
  * g_input_stream_read_finish:
- * @stream:
- * @result:
+ * @stream: a #GInputStream.
+ * @result: a #GAsyncResult.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns: 
+ * 
+ * Finishes an asynchronous stream read operation. 
+ * 
+ * Returns: number of bytes read in, or -1 on error.
  **/
 gssize
 g_input_stream_read_finish (GInputStream              *stream,
@@ -733,11 +745,14 @@ g_input_stream_skip_async (GInputStream        *stream,
 
 /**
  * g_input_stream_skip_finish:
- * @stream:
- * @result:
+ * @stream: a #GInputStream.
+ * @result: a #GAsyncResult.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns: 
+ * 
+ * Finishes a stream skip operation.
+ * 
+ * Returns: the size of the bytes skipped, or %-1 on error.
  **/
 gssize
 g_input_stream_skip_finish (GInputStream              *stream,
@@ -826,11 +841,14 @@ g_input_stream_close_async (GInputStream       *stream,
 
 /**
  * g_input_stream_close_finish:
- * @stream:
- * @result:
+ * @stream: a #GInputStream.
+ * @result: a #GAsyncResult.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns: 
+ * 
+ * Finishes closing a stream asynchronously, started from g_input_stream_close_async().
+ * 
+ * Returns: %TRUE if the stream was closed successfully.
  **/
 gboolean
 g_input_stream_close_finish (GInputStream              *stream,
@@ -862,6 +880,8 @@ g_input_stream_close_finish (GInputStream              *stream,
  * g_input_stream_is_closed:
  * @stream: input stream.
  * 
+ * Checks if an input stream is closed.
+ * 
  * Returns: %TRUE if the stream is closed.
  **/
 gboolean
@@ -876,6 +896,8 @@ g_input_stream_is_closed (GInputStream *stream)
  * g_input_stream_has_pending:
  * @stream: input stream.
  * 
+ * Checks if an input stream has pending actions.
+ * 
  * Returns: %TRUE if @stream has pending actions.
  **/  
 gboolean
diff --git a/gio/ginputstream.h b/gio/ginputstream.h
index 7df266298..c6ec44370 100644
--- a/gio/ginputstream.h
+++ b/gio/ginputstream.h
@@ -37,6 +37,11 @@ G_BEGIN_DECLS
 #define G_IS_INPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_INPUT_STREAM))
 #define G_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_INPUT_STREAM, GInputStreamClass))
 
+/**
+ * GInputStream:
+ * 
+ * Base class for streaming input operations.
+ **/
 typedef struct _GInputStream         GInputStream;
 typedef struct _GInputStreamClass    GInputStreamClass;
 typedef struct _GInputStreamPrivate  GInputStreamPrivate;
@@ -97,6 +102,7 @@ struct _GInputStreamClass
 			    GAsyncResult       *result,
 			    GError            **error);
 
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gioerror.c b/gio/gioerror.c
index 9b1553d54..829383cd9 100644
--- a/gio/gioerror.c
+++ b/gio/gioerror.c
@@ -25,9 +25,17 @@
 #include "gioerror.h"
 
 /**
+ * SECTION:gioerror
+ * @short_description: Error helper functions.
+ *
+ **/
+
+/**
  * g_io_error_quark:
+ * 
+ * Gets the GIO Error Quark.
  *
- * Return value: The quark used as %G_IO_ERROR
+ * Return value: a #GQuark.
  **/
 GQuark
 g_io_error_quark (void)
@@ -35,6 +43,14 @@ g_io_error_quark (void)
   return g_quark_from_static_string ("g-io-error-quark");
 }
 
+/**
+ * g_io_error_from_errno:
+ * @err_no: Error number as defined in errno.h.
+ *
+ * Converts errno.h error codes into GIO error codes.
+ *
+ * Returns: #GIOErrorEnum value for the given errno.h error number.
+ **/
 GIOErrorEnum
 g_io_error_from_errno (gint err_no)
 {
diff --git a/gio/gioerror.h b/gio/gioerror.h
index c4606fcec..b928a9026 100644
--- a/gio/gioerror.h
+++ b/gio/gioerror.h
@@ -29,6 +29,12 @@ G_BEGIN_DECLS
 
 GQuark          g_io_error_quark      (void);
 
+/**
+ * G_IO_ERROR:
+ * 
+ * Error domain for GIO. Errors in this domain will be from the #GIOErrorEnum enumeration.
+ * See #GError for more information on error domains.
+ **/
 #define G_IO_ERROR g_io_error_quark()
 
 /* This enumeration conflicts with GIOError in giochannel.h. However,
@@ -37,6 +43,42 @@ GQuark          g_io_error_quark      (void);
  * the actual enumeration (which is rarely used) GIOErrorEnum.
  */
 
+/**
+ * GIOErrorEnum:
+ * @G_IO_ERROR_FAILED: Generic error condition for when any operation fails.
+ * @G_IO_ERROR_NOT_FOUND: File not found error.
+ * @G_IO_ERROR_EXISTS: File already exists error.
+ * @G_IO_ERROR_IS_DIRECTORY: File is a directory error.
+ * @G_IO_ERROR_NOT_DIRECTORY: File is not a directory.
+ * @G_IO_ERROR_NOT_EMPTY: File is a directory that isn't empty.
+ * @G_IO_ERROR_NOT_REGULAR_FILE: File is not a regular file.
+ * @G_IO_ERROR_NOT_SYMBOLIC_LINK: File is not a symbolic link.
+ * @G_IO_ERROR_NOT_MOUNTABLE_FILE: File cannot be mounted.
+ * @G_IO_ERROR_FILENAME_TOO_LONG: Filename is too many characters.
+ * @G_IO_ERROR_INVALID_FILENAME: Filename is invalid or contains invalid characters.
+ * @G_IO_ERROR_TOO_MANY_LINKS: File contains too many symbolic links.
+ * @G_IO_ERROR_NO_SPACE: No space left on drive.
+ * @G_IO_ERROR_INVALID_ARGUMENT: Invalid argument.
+ * @G_IO_ERROR_PERMISSION_DENIED: Permission denied.
+ * @G_IO_ERROR_NOT_SUPPORTED: Operation not supported for the current backend.
+ * @G_IO_ERROR_NOT_MOUNTED: File isn't mounted.
+ * @G_IO_ERROR_ALREADY_MOUNTED: File is already mounted.
+ * @G_IO_ERROR_CLOSED: File was closed.
+ * @G_IO_ERROR_CANCELLED: Operation was cancelled. See #GCancellable.
+ * @G_IO_ERROR_PENDING: Operations are still pending.
+ * @G_IO_ERROR_READ_ONLY: File is read only.
+ * @G_IO_ERROR_CANT_CREATE_BACKUP: Backup couldn't be created.
+ * @G_IO_ERROR_WRONG_ETAG: File's Entity Tag was incorrect.
+ * @G_IO_ERROR_TIMED_OUT: Operation timed out.
+ * @G_IO_ERROR_WOULD_RECURSE: Operation would be recursive.
+ * @G_IO_ERROR_BUSY: File is busy.
+ * @G_IO_ERROR_WOULD_BLOCK: Operation would block.
+ * @G_IO_ERROR_HOST_NOT_FOUND: Host couldn't be found (remote operations).
+ * @G_IO_ERROR_WOULD_MERGE: Operation would merge files.
+ *
+ * Error codes returned by GIO functions.
+ * 
+ **/
 typedef enum
 {
   G_IO_ERROR_FAILED,
diff --git a/gio/giomodule.c b/gio/giomodule.c
index ab7c29d14..1214d817b 100644
--- a/gio/giomodule.c
+++ b/gio/giomodule.c
@@ -24,6 +24,15 @@
 
 #include "giomodule.h"
 
+/**
+ * SECTION:giomodule
+ * @short_description: Loadable GIO Modules
+ *
+ * Provides an interface and default functions for loading and unloading 
+ * GIO modules.
+ * 
+ **/
+
 struct _GIOModule {
   GTypeModule parent_instance;
   
@@ -130,7 +139,9 @@ g_io_module_unload_module (GTypeModule *gmodule)
  * g_io_module_new:
  * @filename: filename of the module to load.
  * 
- * Returns: a new #GIOModule from given @filename, 
+ * Loads a new module into GIO.
+ * 
+ * Returns: a #GIOModule from given @filename, 
  * or %NULL on error.
  **/
 GIOModule *
@@ -208,9 +219,10 @@ G_LOCK_DEFINE_STATIC (loaded_dirs);
 static GHashTable *loaded_dirs = NULL;
 
 /**
- * g_io_module_ensure_loaded:
- * @directory: directory to ensure is loaded.
+ * g_io_modules_ensure_loaded:
+ * @directory: string containing a directory path.
  * 
+ * Loads all of the modules within the @directory. 
  **/
 void
 g_io_modules_ensure_loaded (const char *directory)
diff --git a/gio/giomodule.h b/gio/giomodule.h
index 44ed052f1..031f349a9 100644
--- a/gio/giomodule.h
+++ b/gio/giomodule.h
@@ -35,6 +35,11 @@ G_BEGIN_DECLS
 #define G_IO_IS_MODULE_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_IO_TYPE_MODULE))
 #define G_IO_MODULE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_IO_TYPE_MODULE, GIOModuleClass))
 
+/**
+ * GIOModule:
+ * 
+ * Opaque module base class for extending GIO.
+ **/
 typedef struct _GIOModule GIOModule;
 typedef struct _GIOModuleClass GIOModuleClass;
 
@@ -44,7 +49,22 @@ GIOModule *g_io_module_new      (const gchar *filename);
 void       g_io_modules_ensure_loaded (const char *directory);
 
 /* API for the modules to implement */
+/**
+ * g_io_module_load:
+ * @module: a #GIOModule.
+ * 
+ * Required API for GIO modules to implement. This function is ran after the module
+ * has been loaded into GIO, to initialize the module.
+ **/
 void        g_io_module_load     (GIOModule   *module);
+
+/**
+ * g_io_module_unload:
+ * @module: a #GIOModule.
+ * 
+ * Required API for GIO modules to implement. This function is ran when the module
+ * is being unloaded from GIO, to finalize the module.
+ **/
 void        g_io_module_unload   (GIOModule   *module);
 
 G_END_DECLS
diff --git a/gio/gioscheduler.c b/gio/gioscheduler.c
index 1c5f5485d..932375516 100644
--- a/gio/gioscheduler.c
+++ b/gio/gioscheduler.c
@@ -24,6 +24,15 @@
 
 #include "gioscheduler.h"
 
+/**
+ * SECTION:gioscheduler
+ * @short_description: I/O Scheduler
+ * 
+ * Schedules asynchronous I/O operations for integration into the main 
+ * event loop (#GMainLoop).
+ * 
+ **/
+
 struct _GIOJob {
   GSList *active_link;
   GIOJobFunc job_func;
@@ -177,10 +186,10 @@ run_job_at_idle (gpointer data)
  * @job_func: a #GIOJobFunc.
  * @user_data: a #gpointer.
  * @notify: a #GDestroyNotify.
- * @io_priority: the io priority of the request. a #gint.
+ * @io_priority: the i/o priority of the request. a #gint.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  *
- * Schedules the @job_func.
+ * Schedules the I/O Job.
  * 
  **/
 void
@@ -314,6 +323,7 @@ mainloop_proxy_notify (gpointer data)
  * @notify: a #GDestroyNotify.
  * @block: boolean flag indicating whether or not this job should block.
  * 
+ * Sends an I/O job to the application's main loop for processing.
  * 
  **/
 void
diff --git a/gio/gioscheduler.h b/gio/gioscheduler.h
index 73f2684e5..c6da94ddf 100644
--- a/gio/gioscheduler.h
+++ b/gio/gioscheduler.h
@@ -28,12 +28,33 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GIOJob:
+ * 
+ * Opaque class for definining and scheduling IO jobs.
+ **/
 typedef struct _GIOJob GIOJob;
 
+/**
+ * GIOJobFunc:
+ * @job: a #GIOJob.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @user_data: the data to pass to callback function
+ * 
+ * I/O Job function.
+ * 
+ **/
 typedef void (*GIOJobFunc) (GIOJob *job,
 			    GCancellable *cancellable,
 			    gpointer user_data);
 
+/**
+ * GIODataFunc:
+ * @user_data:
+ * 
+ * I/O Data function.
+ * 
+ **/
 typedef void (*GIODataFunc) (gpointer user_data);
 
 void g_schedule_io_job         (GIOJobFunc      job_func,
diff --git a/gio/gloadableicon.c b/gio/gloadableicon.c
index 569065e94..85e8e6d8e 100644
--- a/gio/gloadableicon.c
+++ b/gio/gloadableicon.c
@@ -21,11 +21,19 @@
  */
 
 #include <config.h>
-
 #include "gsimpleasyncresult.h"
 #include "gloadableicon.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gloadableicon
+ * @short_description: Loadable Icons
+ * @see_also: #GIcon, #GThemedIcon
+ * 
+ * Implements #GIcon and adds the ability to load icons.
+ *
+ **/
+
 static void          g_loadable_icon_real_load_async  (GLoadableIcon        *icon,
 						       int                   size,
 						       GCancellable         *cancellable,
@@ -86,13 +94,17 @@ g_loadable_icon_base_init (gpointer g_class)
 
 /**
  * g_loadable_icon_load:
- * @icon:
- * @size:
- * @type:
+ * @icon: a #GLoadableIcon.
+ * @size: an integer.
+ * @type: 
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns: 
+ * 
+ * Loads a loadable icon. For the asynchronous version of this function, 
+ * see g_loadable_icon_load_async().
+ * 
+ * Returns: a #GInputStream to read the icon from.
  **/
 GInputStream *
 g_loadable_icon_load (GLoadableIcon        *icon,
@@ -113,12 +125,15 @@ g_loadable_icon_load (GLoadableIcon        *icon,
 
 /**
  * g_loadable_icon_load_async:
- * @icon:
- * @size:
- * @cancellable: optional #GCancellable object, %NULL to ignore. @callback:
- * @user_data:
+ * @icon: a #GLoadableIcon.
+ * @size: an integer.
+ * @cancellable: optional #GCancellable object, %NULL to ignore. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
- * Loads an icon asynchronously.
+ * Loads an icon asynchronously. To finish this function, see 
+ * g_loadable_icon_load_finish(). For the synchronous, blocking 
+ * version of this function, see g_loadable_icon_load().
  * 
  **/
 void
@@ -140,12 +155,15 @@ g_loadable_icon_load_async (GLoadableIcon        *icon,
 
 /**
  * g_loadable_icon_load_finish:
- * @icon:
- * @res:
+ * @icon: a #GLoadableIcon.
+ * @res: a #GAsyncResult.
  * @type:
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns:
+ * 
+ * Finishes an asynchronous icon load started in g_loadable_icon_load_async().
+ * 
+ * Returns: a #GInputStream to read the icon from.
  **/
 GInputStream *
 g_loadable_icon_load_finish (GLoadableIcon        *icon,
diff --git a/gio/gloadableicon.h b/gio/gloadableicon.h
index ef203d709..fdbece22e 100644
--- a/gio/gloadableicon.h
+++ b/gio/gloadableicon.h
@@ -34,10 +34,24 @@ G_BEGIN_DECLS
 #define G_IS_LOADABLE_ICON(obj)	        (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_LOADABLE_ICON))
 #define G_LOADABLE_ICON_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_LOADABLE_ICON, GLoadableIconIface))
 
+/**
+ * GLoadableIcon:
+ * 
+ * Dummy type for subclassing loadable icon types.
+ **/
 typedef struct _GLoadableIcon         		GLoadableIcon; /* Dummy typedef */
 typedef struct _GLoadableIconIface    		GLoadableIconIface;
 
-
+/**
+ * GLoadableIconIface:
+ * @g_iface: The parent interface.
+ * @load: Loads an icon.
+ * @load_async: Loads an icon asynchronously.
+ * @load_finish: Finishes an asynchronous icon load.
+ * 
+ * GLoadableIconIface is used for implementing loadable icon types, 
+ * for implementations that need to load an icon.
+ **/
 struct _GLoadableIconIface
 {
   GTypeInterface g_iface;
diff --git a/gio/glocalfileoutputstream.c b/gio/glocalfileoutputstream.c
index c8b58c9da..db51aad01 100644
--- a/gio/glocalfileoutputstream.c
+++ b/gio/glocalfileoutputstream.c
@@ -400,15 +400,6 @@ g_local_file_output_stream_query_info (GFileOutputStream     *stream,
 					 error);
 }
 
-/**
- * g_local_file_output_stream_create:
- * @filename:
- * @flags:
- * @cancellable: optional #GCancellable object, %NULL to ignore. 
- * @error: a #GError location to store the error occuring, or %NULL to 
- * ignore.
- * Returns: #GFileOutputStream.
- **/
 GFileOutputStream *
 g_local_file_output_stream_create  (const char       *filename,
 				    GFileCreateFlags  flags,
@@ -452,15 +443,6 @@ g_local_file_output_stream_create  (const char       *filename,
   return G_FILE_OUTPUT_STREAM (stream);
 }
 
-/**
- * g_local_file_output_stream_append:
- * @filename:
- * @flags:
- * @cancellable: optional #GCancellable object, %NULL to ignore. 
- * @error: a #GError location to store the error occuring, or %NULL to 
- * ignore.
- * Returns: 
- **/
 GFileOutputStream *
 g_local_file_output_stream_append  (const char       *filename,
 				    GFileCreateFlags  flags,
@@ -834,17 +816,6 @@ handle_overwrite_open (const char *filename,
   return -1;
 }
 
-/**
- * g_local_file_output_stream_replace:
- * @filename: the file name.
- * @etag:
- * @create_backup: if set, create a backup of the file.
- * @flags:
- * @cancellable: optional #GCancellable object, %NULL to ignore. 
- * @error: a #GError location to store the error occuring, or %NULL to 
- * ignore.
- * Returns: #GFileOutputStream
- **/
 GFileOutputStream *
 g_local_file_output_stream_replace (const char        *filename,
 				    const char        *etag,
diff --git a/gio/gmemoryinputstream.c b/gio/gmemoryinputstream.c
index fea27a4d7..ee29df1fd 100644
--- a/gio/gmemoryinputstream.c
+++ b/gio/gmemoryinputstream.c
@@ -21,15 +21,23 @@
  */
 
 #include <config.h>
-
 #include "gmemoryinputstream.h"
 #include "ginputstream.h"
 #include "gseekable.h"
 #include "string.h"
 #include "gsimpleasyncresult.h"
-
 #include "glibintl.h"
 
+/**
+ * SECTION:gmemoryinputstream
+ * @short_description: streaming input operations on memory chunks
+ * @see_also: #GMemoryOutputStream.
+ *
+ * #GMemoryInputStream is a class for using arbitrary
+ * memory chunks as input for GIO streaming input operations.
+ *
+ */
+
 struct _GMemoryInputStreamPrivate {
   guint8 *buffer;      
   gsize   pos;
diff --git a/gio/gmemoryinputstream.h b/gio/gmemoryinputstream.h
index d62cb7fb2..3f39b0c18 100644
--- a/gio/gmemoryinputstream.h
+++ b/gio/gmemoryinputstream.h
@@ -35,6 +35,11 @@ G_BEGIN_DECLS
 #define G_IS_MEMORY_INPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_MEMORY_INPUT_STREAM))
 #define G_MEMORY_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_MEMORY_INPUT_STREAM, GMemoryInputStreamClass))
 
+/**
+ * GMemoryInputStream:
+ * 
+ * Implements #GInputStream for arbitrary memory chunks.
+ **/
 typedef struct _GMemoryInputStream         GMemoryInputStream;
 typedef struct _GMemoryInputStreamClass    GMemoryInputStreamClass;
 typedef struct _GMemoryInputStreamPrivate  GMemoryInputStreamPrivate;
diff --git a/gio/gmemoryoutputstream.c b/gio/gmemoryoutputstream.c
index 966f34be0..ae5ac9def 100644
--- a/gio/gmemoryoutputstream.c
+++ b/gio/gmemoryoutputstream.c
@@ -28,6 +28,16 @@
 #include "string.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gmemoryoutputstream
+ * @short_description: streaming output operations on memory chunks
+ * @see_also: #GMemoryInputStream.
+ *
+ * #GMemoryOutputStream is a class for using arbitrary
+ * memory chunks as output for GIO streaming output operations.
+ *
+ */
+
 struct _GMemoryOutputStreamPrivate {
   
   GByteArray *data;
diff --git a/gio/gmemoryoutputstream.h b/gio/gmemoryoutputstream.h
index bcb3cc7de..5fc32f38a 100644
--- a/gio/gmemoryoutputstream.h
+++ b/gio/gmemoryoutputstream.h
@@ -35,6 +35,11 @@ G_BEGIN_DECLS
 #define G_IS_MEMORY_OUTPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_MEMORY_OUTPUT_STREAM))
 #define G_MEMORY_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_MEMORY_OUTPUT_STREAM, GMemoryOutputStreamClass))
 
+/**
+ * GMemoryOutputStream:
+ * 
+ * Implements #GOutputStream for arbitrary memory chunks.
+ **/
 typedef struct _GMemoryOutputStream         GMemoryOutputStream;
 typedef struct _GMemoryOutputStreamClass    GMemoryOutputStreamClass;
 typedef struct _GMemoryOutputStreamPrivate  GMemoryOutputStreamPrivate;
@@ -51,6 +56,7 @@ struct _GMemoryOutputStreamClass
 {
  GOutputStreamClass parent_class;
 
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gmountoperation.c b/gio/gmountoperation.c
index 034854bd3..4c0895e31 100644
--- a/gio/gmountoperation.c
+++ b/gio/gmountoperation.c
@@ -28,6 +28,21 @@
 #include "gio-marshal.h"
 #include "glibintl.h"
 
+/** 
+ * SECTION:gmountoperation
+ * @short_description: Authentication methods for mountable locations.
+ *
+ * #GMountOperation provides a mechanism for authenticating mountable 
+ * operations, such as loop mounting files, hard drive partitions or 
+ * server locations. 
+ *
+ * Mountable GIO backends should implement #GMountOperation if they 
+ * require any priviledges or authentication for their volumes to be 
+ * mounted (e.g. a hard disk partition or an encrypted filesystem), or 
+ * if they are implementing a remote server protocol which requires user
+ * credentials such as FTP or WebDAV. 
+ **/
+
 G_DEFINE_TYPE (GMountOperation, g_mount_operation, G_TYPE_OBJECT);
 
 enum {
@@ -112,6 +127,16 @@ g_mount_operation_class_init (GMountOperationClass *klass)
   klass->ask_password = ask_password;
   klass->ask_question = ask_question;
   
+  /**
+   * GMountOperation::ask-password:
+   * @op: a #GMountOperation requesting a password.
+   * @message: string containing a message to display to the user.
+   * @default_user: string containing the default user name.
+   * @default_domain: string containing the default domain.
+   * @flags: a set of #GPasswordFlags.
+   * 
+   * Emitted when a mount operation asks the user for a password.
+   */
   signals[ASK_PASSWORD] =
     g_signal_new (I_("ask_password"),
 		  G_TYPE_FROM_CLASS (gobject_class),
@@ -121,7 +146,16 @@ g_mount_operation_class_init (GMountOperationClass *klass)
 		  _gio_marshal_BOOLEAN__STRING_STRING_STRING_INT,
 		  G_TYPE_BOOLEAN, 4,
 		  G_TYPE_STRING, G_TYPE_STRING, G_TYPE_STRING, G_TYPE_UINT);
-  
+		  
+  /**
+   * GMountOperation::ask-question:
+   * @op: a #GMountOperation asking a question.
+   * @message: string containing a message to display to the user.
+   * @choices: an array of strings for each possible choice.
+   * 
+   * Emitted when asking the user a question and gives a list of choices for the 
+   * user to choose from. 
+   */
   signals[ASK_QUESTION] =
     g_signal_new (I_("ask_question"),
 		  G_TYPE_FROM_CLASS (gobject_class),
@@ -131,7 +165,14 @@ g_mount_operation_class_init (GMountOperationClass *klass)
 		  _gio_marshal_BOOLEAN__STRING_POINTER,
 		  G_TYPE_BOOLEAN, 2,
 		  G_TYPE_STRING, G_TYPE_POINTER);
-
+		  
+  /**
+   * GMountOperation::reply:
+   * @op: a #GMountOperation.
+   * @abort: a gboolean indicating %TRUE if the operation was aborted.
+   * 
+   * Emitted when the user has replied to the mount operation.
+   */
   signals[REPLY] =
     g_signal_new (I_("reply"),
 		  G_TYPE_FROM_CLASS (gobject_class),
@@ -154,7 +195,9 @@ g_mount_operation_init (GMountOperation *operation)
 /**
  * g_mount_operation_new:
  * 
- * Returns: a new #GMountOperation.
+ * Creates a new mount operation.
+ * 
+ * Returns: a #GMountOperation.
  **/
 GMountOperation *
 g_mount_operation_new (void)
@@ -164,9 +207,11 @@ g_mount_operation_new (void)
 
 /**
  * g_mount_operation_get_username
- * @op:
+ * @op: a #GMountOperation.
  * 
- * Returns: 
+ * Get the user name from the mount operation.
+ *
+ * Returns: a string containing the user name.
  **/
 const char *
 g_mount_operation_get_username (GMountOperation *op)
@@ -177,8 +222,10 @@ g_mount_operation_get_username (GMountOperation *op)
 
 /**
  * g_mount_operation_set_username:
- * @op:
+ * @op: a #GMountOperation.
  * @username: input username.
+ *
+ * Sets the user name within @op to @username.
  * 
  **/
 void
@@ -192,9 +239,11 @@ g_mount_operation_set_username (GMountOperation *op,
 
 /**
  * g_mount_operation_get_password:
- * @op:
- * 
- * Returns:  
+ * @op: a #GMountOperation.
+ *
+ * Gets a password from the mount operation. 
+ *
+ * Returns: a string containing the password within @op.
  **/
 const char *
 g_mount_operation_get_password (GMountOperation *op)
@@ -205,7 +254,7 @@ g_mount_operation_get_password (GMountOperation *op)
 
 /**
  * g_mount_operation_set_password:
- * @op: the given #GMountOperation.
+ * @op: a #GMountOperation.
  * @password: password to set.
  * 
  * Sets the mount operation's password to @password.  
@@ -222,7 +271,10 @@ g_mount_operation_set_password (GMountOperation *op,
 
 /**
  * g_mount_operation_get_anonymous:
- * @op:
+ * @op: a #GMountOperation.
+ * 
+ * Check to see whether the mount operation is being used 
+ * for an anonymous user.
  * 
  * Returns: %TRUE if mount operation is anonymous. 
  **/
@@ -235,9 +287,10 @@ g_mount_operation_get_anonymous (GMountOperation *op)
 
 /**
  * g_mount_operation_set_anonymous:
- * @op: the given #GMountOperation.
+ * @op: a #GMountOperation.
  * @anonymous: boolean value.
  * 
+ * Sets the mount operation to use an anonymous user if @anonymous is %TRUE.
  **/  
 void
 g_mount_operation_set_anonymous (GMountOperation *op,
@@ -249,9 +302,11 @@ g_mount_operation_set_anonymous (GMountOperation *op,
 
 /**
  * g_mount_operation_get_domain:
- * @op:
+ * @op: a #GMountOperation.
+ * 
+ * Gets the domain of the mount operation.
  * 
- * Returns: a const string set to the domain.
+ * Returns: a string set to the domain. 
  **/
 const char *
 g_mount_operation_get_domain (GMountOperation *op)
@@ -262,7 +317,7 @@ g_mount_operation_get_domain (GMountOperation *op)
 
 /**
  * g_mount_operation_set_domain:
- * @op: the given #GMountOperation.
+ * @op: a #GMountOperation.
  * @domain: the domain to set.
  * 
  * Sets the mount operation's domain. 
@@ -278,9 +333,11 @@ g_mount_operation_set_domain (GMountOperation *op,
 
 /**
  * g_mount_operation_get_password_save:
- * @op: the given #GMountOperation.
+ * @op: a #GMountOperation.
+ * 
+ * Gets the state of saving passwords for the mount operation.
  *
- * Returns: #GPasswordSave. 
+ * Returns: a #GPasswordSave flag. 
  **/  
 
 GPasswordSave
@@ -291,9 +348,11 @@ g_mount_operation_get_password_save (GMountOperation *op)
 }
 
 /**
- * g_mount_operation_set_password_save
- * @op:
- * @save: #GPasswordSave
+ * g_mount_operation_set_password_save:
+ * @op: a #GMountOperation.
+ * @save: a set of #GPasswordSave flags.
+ * 
+ * Sets the state of saving passwords for the mount operation.
  * 
  **/   
 void
@@ -306,9 +365,12 @@ g_mount_operation_set_password_save (GMountOperation *op,
 
 /**
  * g_mount_operation_get_choice:
- * @op:
+ * @op: a #GMountOperation.
  * 
- * Returns: 
+ * Gets a choice from the mount operation.
+ *
+ * Returns: an integer containing an index of the user's choice from 
+ * the choice's list, or %0.
  **/
 int
 g_mount_operation_get_choice (GMountOperation *op)
@@ -319,9 +381,10 @@ g_mount_operation_get_choice (GMountOperation *op)
 
 /**
  * g_mount_operation_set_choice:
- * @op:
- * @choice:
- *  
+ * @op: a #GMountOperation.
+ * @choice: an integer.
+ *
+ * Sets a default choice for the mount operation.
  **/
 void
 g_mount_operation_set_choice (GMountOperation *op,
@@ -333,11 +396,10 @@ g_mount_operation_set_choice (GMountOperation *op,
 
 /**
  * g_mount_operation_reply:
- * @op: #GMountOperation.
+ * @op: a #GMountOperation.
  * @abort: boolean.
  * 
- * Emits the #GMountOperation::Reply signal with the abort flag set to
- * @abort.
+ * Emits the #GMountOperation::reply signal.
  **/
 void
 g_mount_operation_reply (GMountOperation *op,
diff --git a/gio/gmountoperation.h b/gio/gmountoperation.h
index 3b730b5ff..a07bc28b3 100644
--- a/gio/gmountoperation.h
+++ b/gio/gmountoperation.h
@@ -36,6 +36,12 @@ G_BEGIN_DECLS
 #define G_IS_MOUNT_OPERATION_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_MOUNT_OPERATION))
 #define G_MOUNT_OPERATION_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_MOUNT_OPERATION, GMountOperationClass))
 
+/**
+ * GMountOperation:
+ * 
+ * Class for providing authentication methods for mounting operations, 
+ * such as mounting a file locally, or authenticating with a server.
+ **/
 typedef struct _GMountOperation        GMountOperation;
 typedef struct _GMountOperationClass   GMountOperationClass;
 typedef struct _GMountOperationPrivate GMountOperationPrivate;
@@ -47,6 +53,19 @@ struct _GMountOperation
   GMountOperationPrivate *priv;
 };
 
+/**
+ * GPasswordFlags:
+ * @G_PASSWORD_FLAGS_NEED_PASSWORD: operation requires a password.
+ * @G_PASSWORD_FLAGS_NEED_USERNAME: operation requires a username.
+ * @G_PASSWORD_FLAGS_NEED_DOMAIN: operation requires a domain.
+ * @G_PASSWORD_FLAGS_SAVING_SUPPORTED: operation supports saving settings.
+ * @G_PASSWORD_FLAGS_ANON_SUPPORTED: operation supports anonymous users.
+ * 
+ * #GPasswordFlags are used to request specific information from the 
+ * user, or to notify the user of their choices in an authentication
+ * situation. 
+ * 
+ **/ 
 typedef enum {
   G_PASSWORD_FLAGS_NEED_PASSWORD    = 1<<0,
   G_PASSWORD_FLAGS_NEED_USERNAME    = 1<<1,
@@ -55,6 +74,14 @@ typedef enum {
   G_PASSWORD_FLAGS_ANON_SUPPORTED   = 1<<5
 } GPasswordFlags;
 
+/**
+ * GPasswordSave:
+ * @G_PASSWORD_SAVE_NEVER: never save a password.
+ * @G_PASSWORD_SAVE_FOR_SESSION: save a password for the session.
+ * @G_PASSWORD_SAVE_PERMANENTLY: save a password permanently.
+ * 
+ * #GPasswordSave is used to indicate the lifespan of a saved password.
+ **/ 
 typedef enum {
   G_PASSWORD_SAVE_NEVER,
   G_PASSWORD_SAVE_FOR_SESSION,
@@ -72,15 +99,15 @@ struct _GMountOperationClass
 			     const char      *default_user,
 			     const char      *default_domain,
 			     GPasswordFlags   flags);
-  
+
   gboolean (* ask_question) (GMountOperation *op,
 			     const char      *message,
 			     const char      *choices[]);
-
+  
   void     (* reply)        (GMountOperation *op,
 			     gboolean         abort);
   
-  
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/goutputstream.c b/gio/goutputstream.c
index 514ea87ba..931e76400 100644
--- a/gio/goutputstream.c
+++ b/gio/goutputstream.c
@@ -21,11 +21,18 @@
  */
 
 #include <config.h>
-
 #include "goutputstream.h"
 #include "gsimpleasyncresult.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:goutputstream
+ * @short_description: base class for implementing streaming output
+ * 
+ * 
+ *
+ **/
+
 G_DEFINE_TYPE (GOutputStream, g_output_stream, G_TYPE_OBJECT);
 
 struct _GOutputStreamPrivate {
@@ -293,11 +300,11 @@ g_output_stream_write_all (GOutputStream *stream,
  *
  * This function is optional for inherited classes.
  * 
- * If @cancellable is not NULL, then the operation can be cancelled by
+ * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
- * was cancelled, the error G_IO_ERROR_CANCELLED will be returned.
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
  *
- * Return value: TRUE on success, FALSE on error
+ * Return value: %TRUE on success, %FALSE on error
  **/
 gboolean
 g_output_stream_flush (GOutputStream    *stream,
@@ -344,15 +351,16 @@ g_output_stream_flush (GOutputStream    *stream,
 
 /**
  * g_output_stream_splice:
- * @stream:
- * @source:
- * @flags:
+ * @stream: a #GOutputStream.
+ * @source: a #GInputStream.
+ * @flags: a set of #GOutputStreamSpliceFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
  *
+ * Splices an input stream into an output stream.
  *
- * Returns: 
+ * Returns: a #gssize containig the size of the data spliced.
  **/
 gssize
 g_output_stream_splice (GOutputStream *stream,
@@ -697,8 +705,9 @@ g_output_stream_write_async (GOutputStream       *stream,
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
  * 
+ * Finishes a stream write operation.
  * 
- * Returns: 
+ * Returns: a #gssize containing the number of bytes written to the stream.
  **/
 gssize
 g_output_stream_write_finish (GOutputStream *stream,
@@ -752,13 +761,15 @@ async_ready_splice_callback_wrapper (GObject *source_object,
 
 /**
  * g_output_stream_splice_async:
- * @stream:
- * @source:
- * @flags:
+ * @stream: a #GOutputStream.
+ * @source: a #GInputStream. 
+ * @flags: a set of #GOutputStreamSpliceFlags.
  * @io_priority: the io priority of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
- * @callback:
- * @user_data:
+ * @callback: a #GAsyncReadyCallback. 
+ * @user_data: user data passed to @callback.
+ * 
+ * Splices a stream asynchronously.
  * 
  **/
 void
@@ -827,7 +838,9 @@ g_output_stream_splice_async (GOutputStream             *stream,
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
  *
- * Returns: 
+ * Finishes an asynchronous stream splice operation.
+ * 
+ * Returns: a #gssize of the number of bytes spliced.
  **/
 gssize
 g_output_stream_splice_finish (GOutputStream             *stream,
@@ -853,11 +866,13 @@ g_output_stream_splice_finish (GOutputStream             *stream,
 
 /**
  * g_output_stream_flush_async:
- * @stream:
+ * @stream: a #GOutputStream.
  * @io_priority: the io priority of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback.
- * @user_data:
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
+ * 
+ * Flushes a stream asynchronously.
  * 
  **/
 void
@@ -918,6 +933,9 @@ g_output_stream_flush_async (GOutputStream       *stream,
  * @result: a GAsyncResult.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
+ * 
+ * Finishes flushing an output stream.
+ * 
  * Returns: %TRUE if flush operation suceeded, %FALSE otherwise.
  **/
 gboolean
@@ -1006,11 +1024,14 @@ g_output_stream_close_async (GOutputStream      *stream,
 
 /**
  * g_output_stream_close_finish:
- * @stream:
- * @result:
+ * @stream: a #GOutputStream.
+ * @result: a #GAsyncResult.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns: %TRUE, %FALSE otherwise.
+ * 
+ * Closes an output stream.
+ * 
+ * Returns: %TRUE if stream was successfully closed, %FALSE otherwise.
  **/
 gboolean
 g_output_stream_close_finish (GOutputStream *stream,
@@ -1040,7 +1061,9 @@ g_output_stream_close_finish (GOutputStream *stream,
 
 /**
  * g_output_stream_is_closed:
- * @stream:
+ * @stream: a #GOutputStream.
+ * 
+ * Checks if an output stream has already been closed.
  * 
  * Returns: %TRUE if @stream is closed. %FALSE otherwise. 
  **/
@@ -1054,7 +1077,9 @@ g_output_stream_is_closed (GOutputStream *stream)
 
 /**
  * g_output_stream_has_pending:
- * @stream:
+ * @stream: a #GOutputStream.
+ * 
+ * Checks if an ouput stream has pending actions.
  * 
  * Returns: %TRUE if @stream has pending actions. 
  **/
@@ -1068,11 +1093,10 @@ g_output_stream_has_pending (GOutputStream *stream)
 
 /**
  * g_output_stream_set_pending:
- * @stream:
- * @pending: 
- * 
- * Sets the @stream as having pending actions. 
+ * @stream: a #GOutputStream.
+ * @pending: a #gboolean.
  * 
+ * Sets the @stream as having pending actions if @pending is %TRUE. 
  **/
 void
 g_output_stream_set_pending (GOutputStream              *stream,
diff --git a/gio/goutputstream.h b/gio/goutputstream.h
index 4bfb621e2..d62afc25d 100644
--- a/gio/goutputstream.h
+++ b/gio/goutputstream.h
@@ -38,12 +38,29 @@ G_BEGIN_DECLS
 #define G_IS_OUTPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_OUTPUT_STREAM))
 #define G_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_OUTPUT_STREAM, GOutputStreamClass))
 
+/**
+ * GOutputStreamSpliceFlags:
+ * @G_OUTPUT_STREAM_SPLICE_FLAGS_NONE:
+ * @G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_SOURCE:
+ * @G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_TARGET:
+ * 
+ * 
+ **/
 typedef enum {
   G_OUTPUT_STREAM_SPLICE_FLAGS_NONE = 0,
   G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_SOURCE = 1 << 0,
   G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_TARGET = 1 << 1
 } GOutputStreamSpliceFlags;
 
+/**
+ * GOutputStream:
+ * 
+ * Base class for writing output. 
+ * 
+ * All classes derived from GOutputStream should implement synchronous 
+ * writing, splicing, flushing and closing streams, but may implement
+ * asynchronous versions.
+ **/
 typedef struct _GOutputStream         GOutputStream;
 typedef struct _GOutputStreamClass    GOutputStreamClass;
 typedef struct _GOutputStreamPrivate  GOutputStreamPrivate;
@@ -119,6 +136,7 @@ struct _GOutputStreamClass
 			     GAsyncResult        *result,
 			     GError             **error);
 
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gpollfilemonitor.c b/gio/gpollfilemonitor.c
index 0b5a5e79d..4c15ad2e5 100644
--- a/gio/gpollfilemonitor.c
+++ b/gio/gpollfilemonitor.c
@@ -192,7 +192,9 @@ got_initial_info (GObject *source_object,
 
 /**
  * g_poll_file_monitor_new:
- * @file:
+ * @file: a #GFile.
+ * 
+ * Polls @file for changes.
  * 
  * Returns a new #GFileMonitor for the given #GFile. 
  **/
diff --git a/gio/gseekable.c b/gio/gseekable.c
index 90f53da0a..bc2a2b219 100644
--- a/gio/gseekable.c
+++ b/gio/gseekable.c
@@ -24,6 +24,17 @@
 #include "gseekable.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gseekable
+ * @short_description: Stream seeking interface.
+ * @see_also: #GInputStream, #GOutputStream.
+ * 
+ * #GSeekable is implemented by streams (implementations of 
+ * #GInputStream or #GOutputStream) that support seeking.
+ * 
+ **/
+
+
 static void g_seekable_base_init (gpointer g_class);
 
 
@@ -64,9 +75,11 @@ g_seekable_base_init (gpointer g_class)
 
 /**
  * g_seekable_tell:
- * @seekable:
+ * @seekable: a #GSeekable.
  * 
- * Returns: a goffset.
+ * Tells the current position within the stream.
+ * 
+ * Returns: the offset from the beginning of the buffer.
  **/
 goffset
 g_seekable_tell (GSeekable *seekable)
@@ -82,7 +95,9 @@ g_seekable_tell (GSeekable *seekable)
 
 /**
  * g_seekable_can_seek:
- * @seekable:
+ * @seekable: a #GSeekable.
+ * 
+ * Tests if the stream supports the #GSeekableIface.
  * 
  * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
  **/
@@ -100,13 +115,22 @@ g_seekable_can_seek (GSeekable *seekable)
 
 /**
  * g_seekable_seek:
- * @seekable:
- * @offset:
- * @type:
+ * @seekable: a #GSeekable.
+ * @offset: a #goffset.
+ * @type: a #GSeekType.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns: %TRUE, %FALSE otherwise.
+ * 
+ * Seeks in the stream by the given @offset, modified by @type.
+ *
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
+ * 
+ * Returns: %TRUE if successful. If an error
+ * has occured, this function will return %FALSE and set @error
+ * appropriately if present.
  **/
 gboolean
 g_seekable_seek (GSeekable     *seekable,
@@ -126,9 +150,11 @@ g_seekable_seek (GSeekable     *seekable,
 
 /**
  * g_seekable_can_truncate:
- * @seekable:
+ * @seekable: a #GSeekable.
+ * 
+ * Tests if the stream can be truncated.
  * 
- * Returns: 
+ * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
  **/
 gboolean
 g_seekable_can_truncate (GSeekable *seekable)
@@ -144,12 +170,23 @@ g_seekable_can_truncate (GSeekable *seekable)
 
 /**
  * g_seekable_truncate:
- * @seekable:
- * @offset:
+ * @seekable: a #GSeekable.
+ * @offset: a #goffset.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns: 
+ * 
+ * Truncates a stream with a given #offset. 
+ * 
+ * If @cancellable is not %NULL, then the operation can be cancelled by
+ * triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an
+ * operation was partially finished when the operation was cancelled the
+ * partial result will be returned, without an error.
+ * 
+ * Returns: %TRUE if successful. If an error
+ * has occured, this function will return %FALSE and set @error
+ * appropriately if present. 
  **/
 gboolean
 g_seekable_truncate (GSeekable     *seekable,
diff --git a/gio/gseekable.h b/gio/gseekable.h
index 33fc619b8..b289df587 100644
--- a/gio/gseekable.h
+++ b/gio/gseekable.h
@@ -33,9 +33,25 @@ G_BEGIN_DECLS
 #define G_IS_SEEKABLE(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_SEEKABLE))
 #define G_SEEKABLE_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_SEEKABLE, GSeekableIface))
 
+/**
+ * GSeekable:
+ * 
+ * Seek object for streaming operations.
+ **/ 
 typedef struct _GSeekable        GSeekable;
 typedef struct _GSeekableIface   GSeekableIface;
 
+/**
+ * GSeekableIface:
+ * @g_iface: The parent interface.
+ * @tell: Tells the current location within a stream.
+ * @can_seek: Checks if seeking is supported by the stream.
+ * @seek: Seeks to a location within a stream.
+ * @can_truncate: Chekcs if truncation is suppored by the stream.
+ * @truncate: Truncates a stream.
+ * 
+ * Provides an interface for implementing seekable functionality on I/O Streams.
+ **/ 
 struct _GSeekableIface
 {
   GTypeInterface g_iface;
diff --git a/gio/gsimpleasyncresult.c b/gio/gsimpleasyncresult.c
index 3c69f19d9..bc4f63513 100644
--- a/gio/gsimpleasyncresult.c
+++ b/gio/gsimpleasyncresult.c
@@ -34,6 +34,58 @@
 #include <gio/gioerror.h>
 #include "glibintl.h"
 
+/**
+ * SECTION:gsimpleasyncresult
+ * @short_description: simple asynchronous results implementation.
+ * @see_also: #GAsyncResult.
+ *
+ * Implements #GAsyncResult for simple cases. Most of the time, this 
+ * will be all an application needs, and will be used transparently. 
+ * Because of this, #GSimpleAsyncResult is used throughout GIO for 
+ * handling asynchronous functions. 
+ * 
+ * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error reporting,
+ * operation cancellation and the final state of an operation, completely
+ * transparent to the application. Results can be returned as a pointer e.g. 
+ * for functions that return data that is collected asynchronously,
+ * a boolean value for checking the success or failure of an operation,
+ * or a #gssize for operations which return the number of bytes modified 
+ * by the operation; all of the simple return cases are covered.
+ * 
+ * Most of the time, an application will not need to know of the details 
+ * of this API; it is handled transparently, and any necessary operations are handled by
+ * #GAsyncResult's interface. However, if implementing a new GIO module, for writing 
+ * language bindings, or for complex applications that need better control of how
+ * asynchronous operations are completed, it is important to understand this functionality.
+ * 
+ * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). If the 
+ * result needs to be created for a #GError, use g_simple_async_result_new_from_error().
+ * If a #GError is not available (e.g. the asynchronous operation's doesn't take a #GError
+ * argument), but the result still needs to be created for an error condition, use 
+ * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va()
+ * if your application or binding requires passing a variable argument list directly), 
+ * and the error can then be propegated through the use of g_simple_async_result_propagate_error().
+ * 
+ * An asynchronous operation can be made to ignore a cancellation event by calling 
+ * g_simple_async_result_set_handle_cancellation() with a #GSimpleAsyncResult for the operation
+ * and %FALSE. 
+ * 
+ * GSimpleAsyncResult can integrate into GLib's Main Event Loop <!-- TODO: Crosslink -->, 
+ * or it can use #GThread<!-- -->s if available. g_simple_async_result_complete() will finish an 
+ * I/O task directly within the main event loop. g_simple_async_result_complete_in_idle() will integrate 
+ * the I/O task into the main event loop as an idle function and g_simple_async_result_run_in_thread() 
+ * will run the job in a separate thread.
+ * 
+ * To set the results of an asynchronous function, g_simple_async_result_set_op_res_gpointer(), 
+ * g_simple_async_result_set_op_res_gboolean(), and g_simple_async_result_set_op_res_gssize()
+ * are provided, setting the operation's result to a gpointer, gboolean, or gssize, respectively.
+ * 
+ * Likewise, to get the result of an asynchronous function, g_simple_async_result_get_op_res_gpointer(),
+ * g_simple_async_result_get_op_res_gboolean(), and g_simple_async_result_get_op_res_gssize() are 
+ * provided, getting the operation's result as a gpointer, gboolean, and gssize, respectively.
+ * 
+ **/
+
 static void g_simple_async_result_async_result_iface_init (GAsyncResultIface       *iface);
 
 struct _GSimpleAsyncResult
@@ -104,12 +156,14 @@ g_simple_async_result_init (GSimpleAsyncResult *simple)
 
 /**
  * g_simple_async_result_new:
- * @source_object:
- * @callback:
- * @user_data:
+ * @source_object: a #GObject.
+ * @callback: a #GAsyncReadyCallback.
+ * @user_data: user data passed to @callback.
  * @source_tag:
  * 
- * Returns: #GSimpleAsyncResult
+ * Creates a #GSimpleAsyncResult.
+ * 
+ * Returns: a #GSimpleAsyncResult.
  **/
 GSimpleAsyncResult *
 g_simple_async_result_new (GObject *source_object,
@@ -132,12 +186,14 @@ g_simple_async_result_new (GObject *source_object,
 
 /**
  * g_simple_async_result_new_from_error:
- * @source_object:
- * @callback:
- * @user_data:
- * @error: a #GError location to store the error occuring, or %NULL to 
- * ignore.
- * Returns: #GSimpleAsyncResult
+ * @source_object: a #GObject.
+ * @callback: a #GAsyncReadyCallback.
+ * @user_data: user data passed to @callback.
+ * @error: a #GError location.
+ * 
+ * Creates a #GSimpleAsyncResult from an error condition.
+ * 
+ * Returns: a #GSimpleAsyncResult.
  **/
 GSimpleAsyncResult *
 g_simple_async_result_new_from_error (GObject *source_object,
@@ -159,15 +215,17 @@ g_simple_async_result_new_from_error (GObject *source_object,
 
 /**
  * g_simple_async_result_new_error:
- * @source_object:
- * @callback:
- * @user_data:
- * @domain:
- * @code:
- * @format:
- * @...
- * 
- * Returns: #GSimpleAsyncResult.
+ * @source_object: a #GObject.
+ * @callback: a #GAsyncReadyCallback. 
+ * @user_data: user data passed to @callback.
+ * @domain: a #GQuark.
+ * @code: an error code.
+ * @format: a string with format characters.
+ * @Varargs: a list of values to insert into @format.
+ * 
+ * Creates a new #GSimpleAsyncResult with a set error.
+ * 
+ * Returns: a #GSimpleAsyncResult.
  **/
 GSimpleAsyncResult *
 g_simple_async_result_new_error (GObject *source_object,
@@ -220,8 +278,10 @@ g_simple_async_result_async_result_iface_init (GAsyncResultIface *iface)
 
 /**
  * g_simple_async_result_set_handle_cancellation:
- * @simple:
- * @handle_cancellation:
+ * @simple: a #GSimpleAsyncResult.
+ * @handle_cancellation: a #gboolean.
+ * 
+ * Sets whether to handle cancellation within the asynchronous operation.
  * 
  **/
 void
@@ -234,9 +294,11 @@ g_simple_async_result_set_handle_cancellation (GSimpleAsyncResult *simple,
 
 /**
  * g_simple_async_result_get_source_tag:
- * @simple:
+ * @simple: a #GSimpleAsyncResult.
  * 
- * Returns: 
+ * Gets the source tag for the #GSimpleAsyncResult.
+ * 
+ * Returns: a #gpointer to the source object for the #GSimpleAsyncResult.
  **/
 gpointer
 g_simple_async_result_get_source_tag (GSimpleAsyncResult *simple)
@@ -246,11 +308,14 @@ g_simple_async_result_get_source_tag (GSimpleAsyncResult *simple)
 }
 
 /**
- * g_simple_async_result_result_propagate_error:
- * @simple:
- * @dest:
+ * g_simple_async_result_propagate_error:
+ * @simple: a #GSimpleAsyncResult.
+ * @dest: a location to propegate the error to.
+ * 
+ * Propegates an error from within the simple asynchronous result to
+ * a given destination.
  * 
- * Returns: 
+ * Returns: %TRUE if the error was propegated to @dest. %FALSE otherwise.
  **/
 gboolean
 g_simple_async_result_propagate_error (GSimpleAsyncResult *simple,
@@ -269,10 +334,11 @@ g_simple_async_result_propagate_error (GSimpleAsyncResult *simple,
 
 /**
  * g_simple_async_result_set_op_res_gpointer:
- * @simple:
- * @op_res:
- * @destroy_op_res:
+ * @simple: a #GSimpleAsyncResult.
+ * @op_res: a pointer result from an asynchronous function.
+ * @destroy_op_res: a #GDestroyNotify function.
  * 
+ * Sets the operation result within the asynchronous result to a pointer.
  **/
 void
 g_simple_async_result_set_op_res_gpointer (GSimpleAsyncResult      *simple,
@@ -287,9 +353,11 @@ g_simple_async_result_set_op_res_gpointer (GSimpleAsyncResult      *simple,
 
 /**
  * g_simple_async_result_get_op_res_gpointer:
- * @simple:
+ * @simple: a #GSimpleAsyncResult.
  * 
- * Returns: gpointer.
+ * Gets a pointer result as returned by the asynchronous function.
+ * 
+ * Returns: a pointer from the result.
  **/
 gpointer
 g_simple_async_result_get_op_res_gpointer (GSimpleAsyncResult      *simple)
@@ -300,9 +368,10 @@ g_simple_async_result_get_op_res_gpointer (GSimpleAsyncResult      *simple)
 
 /**
  * g_simple_async_result_set_op_res_gssize:
- * @simple:
- * @op_res:
+ * @simple: a #GSimpleAsyncResult.
+ * @op_res: a #gssize.
  * 
+ * Sets the operation result within the asynchronous result to the given @op_res. 
  **/
 void
 g_simple_async_result_set_op_res_gssize   (GSimpleAsyncResult      *simple,
@@ -314,9 +383,11 @@ g_simple_async_result_set_op_res_gssize   (GSimpleAsyncResult      *simple,
 
 /**
  * g_simple_async_result_get_op_res_gssize:
- * @simple:
+ * @simple: a #GSimpleAsyncResult.
+ * 
+ * Gets a gssize from the asynchronous result.
  * 
- * Returns:
+ * Returns: a gssize returned from the asynchronous function.
  **/
 gssize
 g_simple_async_result_get_op_res_gssize   (GSimpleAsyncResult      *simple)
@@ -327,8 +398,10 @@ g_simple_async_result_get_op_res_gssize   (GSimpleAsyncResult      *simple)
 
 /**
  * g_simple_async_result_set_op_res_gboolean:
- * @simple:
- * @op_res:
+ * @simple: a #GSimpleAsyncResult.
+ * @op_res: a #gboolean.
+ * 
+ * Sets the operation result to a boolean within the asynchronous result.
  *  
  **/
 void
@@ -341,9 +414,12 @@ g_simple_async_result_set_op_res_gboolean (GSimpleAsyncResult      *simple,
 
 /**
  * g_simple_async_result_get_op_res_gboolean:
- * @simple:
+ * @simple: a #GSimpleAsyncResult.
+ * 
+ * Gets the operation result boolean from within the asynchronous result.
  * 
- * Returns a #gboolean. 
+ * Returns: %TRUE if the operation's result was %TRUE, %FALSE if the operation's
+ * result was %FALSE. 
  **/
 gboolean
 g_simple_async_result_get_op_res_gboolean (GSimpleAsyncResult      *simple)
@@ -354,11 +430,10 @@ g_simple_async_result_get_op_res_gboolean (GSimpleAsyncResult      *simple)
 
 /**
  * g_simple_async_result_set_from_error:
- * @simple:
+ * @simple: a #GSimpleAsyncResult.
  * @error: #GError.
  * 
- * Sets the result from given @error.
- * 
+ * Sets the result from a #GError. 
  **/
 void
 g_simple_async_result_set_from_error (GSimpleAsyncResult *simple,
@@ -390,14 +465,14 @@ _g_error_new_valist (GQuark         domain,
 
 /**
  * g_simple_async_result_set_error_va:
- * @simple:
- * @domain:
- * @code:
- * @format:
+ * @simple: a #GSimpleAsyncResult.
+ * @domain: a #GQuark (usually #G_IO_ERROR).
+ * @code: an error code.
+ * @format: a formatted error reporting string.
  * @args: va_list of arguments. 
  * 
- * Sets error va_list, suitable for language bindings.
- * 
+ * Sets an error within the asynchronous result without a #GError. Unless 
+ * writing a binding, see g_simple_async_result_set_error().
  **/
 void
 g_simple_async_result_set_error_va (GSimpleAsyncResult *simple,
@@ -416,11 +491,13 @@ g_simple_async_result_set_error_va (GSimpleAsyncResult *simple,
 
 /**
  * g_simple_async_result_set_error:
- * @simple:
- * @domain:
- * @code:
- * @format:
- * @...
+ * @simple: a #GSimpleAsyncResult.
+ * @domain: a #GQuark (usually #G_IO_ERROR).
+ * @code: an error code.
+ * @format: a formatted error reporting string.
+ * @Varargs: a list of variables to fill in @format.
+ * 
+ * Sets an error within the asynchronous result without a #GError.
  * 
  **/
 void
@@ -443,7 +520,9 @@ g_simple_async_result_set_error (GSimpleAsyncResult *simple,
 
 /**
  * g_simple_async_result_complete:
- * @simple:
+ * @simple: a #GSimpleAsyncResult.
+ * 
+ * Completes an asynchronous I/O job.
  * 
  **/
 void
@@ -469,7 +548,10 @@ complete_in_idle_cb (gpointer data)
 
 /**
  * g_simple_async_result_complete_in_idle:
- * @simple:
+ * @simple: a #GSimpleAsyncResult.
+ * 
+ * Completes an asynchronous function in the main event loop using 
+ * an idle function.
  *  
  **/
 void
@@ -525,10 +607,13 @@ run_in_thread (GIOJob *job,
 
 /**
  * g_simple_async_result_run_in_thread:
- * @simple:
- * @func:
+ * @simple: a #GSimpleAsyncResult.
+ * @func: a #GSimpleAsyncThreadFunc.
  * @io_priority: the io priority of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
+ * 
+ * Runs the asynchronous job in a separated thread.
+ * 
  **/
 void
 g_simple_async_result_run_in_thread (GSimpleAsyncResult *simple,
@@ -550,12 +635,14 @@ g_simple_async_result_run_in_thread (GSimpleAsyncResult *simple,
 /**
  * g_simple_async_report_error_in_idle:
  * @object:
- * @callback:
- * @user_data:
- * @domain:
- * @code:
- * @format:
- * @...
+ * @callback: a #GAsyncReadyCallback. 
+ * @user_data: user data passed to @callback.
+ * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).
+ * @code: a specific error code.
+ * @format: a formatted error reporting string.
+ * @Varargs: a list of variables to fill in @format.
+ * 
+ * Reports an error in an idle function.
  * 
  **/
 void
diff --git a/gio/gsimpleasyncresult.h b/gio/gsimpleasyncresult.h
index 4c4ecf8e6..0607f8835 100644
--- a/gio/gsimpleasyncresult.h
+++ b/gio/gsimpleasyncresult.h
@@ -35,9 +35,23 @@ G_BEGIN_DECLS
 #define G_IS_SIMPLE_ASYNC_RESULT_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SIMPLE_ASYNC_RESULT))
 #define G_SIMPLE_ASYNC_RESULT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SIMPLE_ASYNC_RESULT, GSimpleAsyncResultClass))
 
+/**
+ * GSimpleAsyncResult:
+ * 
+ * A simple implementation of #GAsyncResult.
+ **/
 typedef struct _GSimpleAsyncResult        GSimpleAsyncResult;
 typedef struct _GSimpleAsyncResultClass   GSimpleAsyncResultClass;
 
+/**
+ * GSimpleAsyncThreadFunc:
+ * @res: a #GSimpleAsyncResult. 
+ * @object: a #GObject.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * 
+ * Simple thread function that runs an asynchronous operation and 
+ * checks for cancellation.
+ **/
 typedef void (*GSimpleAsyncThreadFunc) (GSimpleAsyncResult *res,
 					GObject *object,
 					GCancellable *cancellable);
diff --git a/gio/gsocketinputstream.c b/gio/gsocketinputstream.c
index 890e8e1f8..1b7b2b8a1 100644
--- a/gio/gsocketinputstream.c
+++ b/gio/gsocketinputstream.c
@@ -37,9 +37,17 @@
 #include "gsocketinputstream.h"
 #include "gcancellable.h"
 #include "gasynchelper.h"
-
 #include "glibintl.h"
 
+/**
+ * SECTION:gsocketinputstream
+ * @short_description: Socket Input Stream
+ * @see_also: #GInputStream.
+ *
+ * #GSocketInputStream implements #GInputStream for reading from a socket, 
+ * including asynchronous operations.
+ **/
+
 G_DEFINE_TYPE (GSocketInputStream, g_socket_input_stream, G_TYPE_INPUT_STREAM);
 
 struct _GSocketInputStreamPrivate {
@@ -128,12 +136,13 @@ g_socket_input_stream_init (GSocketInputStream *socket)
 
 /**
  * g_socket_input_stream_new:
- * @fd: file descriptor.
- * @close_fd_at_close: boolean value
+ * @fd: socket file descriptor.
+ * @close_fd_at_close: a #gboolean.
  * 
+ * Creates a new #GSocketInputStream for the given @fd. If @close_fd_at_close
+ * is %TRUE, the socket will be closed when the stream is closed.
  * 
- * Returns: new #GInputStream. If @close_fd_at_close is %TRUE, 
- * @fd will be closed when the #GInputStream is closed.
+ * Returns: a #GSocketInputStream. 
  **/
 GInputStream *
 g_socket_input_stream_new (int fd,
diff --git a/gio/gsocketinputstream.h b/gio/gsocketinputstream.h
index 31b79ce50..ec98cdb85 100644
--- a/gio/gsocketinputstream.h
+++ b/gio/gsocketinputstream.h
@@ -34,6 +34,11 @@ G_BEGIN_DECLS
 #define G_IS_SOCKET_INPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SOCKET_INPUT_STREAM))
 #define G_SOCKET_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SOCKET_INPUT_STREAM, GSocketInputStreamClass))
 
+/**
+ * GSocketInputStream:
+ * 
+ * Implements #GInputStream for reading from sockets.
+ **/
 typedef struct _GSocketInputStream         GSocketInputStream;
 typedef struct _GSocketInputStreamClass    GSocketInputStreamClass;
 typedef struct _GSocketInputStreamPrivate  GSocketInputStreamPrivate;
@@ -50,6 +55,7 @@ struct _GSocketInputStreamClass
 {
   GInputStreamClass parent_class;
 
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gsocketoutputstream.c b/gio/gsocketoutputstream.c
index 54539f589..b42162feb 100644
--- a/gio/gsocketoutputstream.c
+++ b/gio/gsocketoutputstream.c
@@ -37,9 +37,17 @@
 #include "gcancellable.h"
 #include "gsimpleasyncresult.h"
 #include "gasynchelper.h"
-
 #include "glibintl.h"
 
+/**
+ * SECTION:gsocketoutputstream
+ * @short_description: Socket Output Stream
+ * @see_also: #GOutputStream.
+ *
+ * #GSocketOutputStream implements #GOutputStream for writing to a socket, including
+ * asynchronous operations.
+ **/
+
 G_DEFINE_TYPE (GSocketOutputStream, g_socket_output_stream, G_TYPE_OUTPUT_STREAM);
 
 
@@ -116,8 +124,11 @@ g_socket_output_stream_init (GSocketOutputStream *socket)
 
 /**
  * g_socket_output_stream_new:
- * @fd: file descriptor.
- * @close_fd_at_close: boolean value.
+ * @fd: socket's file descriptor.
+ * @close_fd_at_close: a #gboolean.
+ * 
+ * Creates a new socket output stream for @fd. If @close_fd_at_close
+ * is %TRUE, the socket will be closed when the output stream is destroyed.
  * 
  * Returns: #GOutputStream. If @close_fd_at_close is %TRUE, then
  * @fd will be closed when the #GOutputStream is closed.
diff --git a/gio/gsocketoutputstream.h b/gio/gsocketoutputstream.h
index cff198654..09527def3 100644
--- a/gio/gsocketoutputstream.h
+++ b/gio/gsocketoutputstream.h
@@ -34,6 +34,11 @@ G_BEGIN_DECLS
 #define G_IS_SOCKET_OUTPUT_STREAM_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SOCKET_OUTPUT_STREAM))
 #define G_SOCKET_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SOCKET_OUTPUT_STREAM, GSocketOutputStreamClass))
 
+/**
+ * GSocketOutputStream:
+ * 
+ * Implements #GOutputStream for outputting to sockets.
+ **/
 typedef struct _GSocketOutputStream         GSocketOutputStream;
 typedef struct _GSocketOutputStreamClass    GSocketOutputStreamClass;
 typedef struct _GSocketOutputStreamPrivate  GSocketOutputStreamPrivate;
@@ -50,6 +55,7 @@ struct _GSocketOutputStreamClass
 {
   GOutputStreamClass parent_class;
 
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gthemedicon.c b/gio/gthemedicon.c
index e27b03374..d46c726c9 100644
--- a/gio/gthemedicon.c
+++ b/gio/gthemedicon.c
@@ -24,6 +24,14 @@
 
 #include "gthemedicon.h"
 
+/**
+ * SECTION:gthemedicon
+ * @short_description: Themed Icons
+ * @see_also: #GIcon, #GLoadableIcon.
+ *
+ * #GThemedIcon is an implementation of #GIcon for themed icons.
+ **/
+
 static void g_themed_icon_icon_iface_init (GIconIface       *iface);
 
 struct _GThemedIcon
@@ -70,9 +78,11 @@ g_themed_icon_init (GThemedIcon *themed)
 
 /**
  * g_themed_icon_new:
- * @iconname:
+ * @iconname: a string containing an icon name.
  * 
- * Returns: a new #GIcon.
+ * Creates a new themed icon for @iconname.
+ * 
+ * Returns: a new #GThemedIcon.
  **/
 GIcon *
 g_themed_icon_new (const char *iconname)
@@ -91,10 +101,12 @@ g_themed_icon_new (const char *iconname)
 
 /**
  * g_themed_icon_new_from_names:
- * @iconnames:
- * @len:
+ * @iconnames: an array of strings containing icon names.
+ * @len: the number of elements in the @iconnames array.
+ * 
+ * Creates a new themed icon for @iconnames.
  * 
- * Returns: a new #GIcon.
+ * Returns: a new #GThemedIcon.
  **/
 GIcon *
 g_themed_icon_new_from_names (char **iconnames, int len)
@@ -121,9 +133,11 @@ g_themed_icon_new_from_names (char **iconnames, int len)
 
 /**
  * g_themed_icon_get_names:
- * @icon:
+ * @icon: a #GThemedIcon.
+ * 
+ * Gets the names of icons from within @icon.
  * 
- * Returns: 
+ * Returns: a list of icon names.
  **/
 const char * const *
 g_themed_icon_get_names (GThemedIcon *icon)
diff --git a/gio/gthemedicon.h b/gio/gthemedicon.h
index f560f1871..b249d3565 100644
--- a/gio/gthemedicon.h
+++ b/gio/gthemedicon.h
@@ -34,6 +34,11 @@ G_BEGIN_DECLS
 #define G_IS_THEMED_ICON_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_THEMED_ICON))
 #define G_THEMED_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_THEMED_ICON, GThemedIconClass))
 
+/**
+ * GThemedIcon:
+ * 
+ * An implementation of #GIcon for themed icons.
+ **/
 typedef struct _GThemedIcon        GThemedIcon;
 typedef struct _GThemedIconClass   GThemedIconClass;
 
diff --git a/gio/gunixdrive.c b/gio/gunixdrive.c
index 464399264..25e05392c 100644
--- a/gio/gunixdrive.c
+++ b/gio/gunixdrive.c
@@ -30,7 +30,6 @@
 #include "gdriveprivate.h"
 #include "gthemedicon.h"
 #include "gvolumemonitor.h"
-
 #include "glibintl.h"
 
 struct _GUnixDrive {
diff --git a/gio/gunixmounts.c b/gio/gunixmounts.c
index da23bd4c0..244581d87 100644
--- a/gio/gunixmounts.c
+++ b/gio/gunixmounts.c
@@ -47,6 +47,14 @@
 #include "gfile.h"
 #include "gfilemonitor.h"
 
+/**
+ * SECTION:gunixmounts
+ * @short_description: Unix Mounts
+ * 
+ * Routines for managing mounted UNIX mount points and paths.
+ *
+ **/
+
 struct _GUnixMount {
   char *mount_path;
   char *device_path;
@@ -898,8 +906,12 @@ get_mount_points_timestamp (void)
  * g_get_unix_mounts:
  * @time_read: guint64 to contain a timestamp.
  * 
- * Returns a #GList of the UNIX mounts. If @time_read
- * is set, it will be filled with the mount timestamp.
+ * Gets a #GList of strings containing the unix mounts. If @time_read
+ * is set, it will be filled with the mount timestamp, 
+ * allowing for checking if the mounts have changed with 
+ * g_unix_mounts_changed_since().
+ * 
+ * Returns: a #GList of the UNIX mounts. 
  **/
 GList *
 g_get_unix_mounts (guint64 *time_read)
@@ -912,11 +924,14 @@ g_get_unix_mounts (guint64 *time_read)
 
 /**
  * g_get_unix_mount_at:
- * @mount_path: path to mount.
+ * @mount_path: path for a possible unix mount.
  * @time_read: guint64 to contain a timestamp.
  * 
- * Returns a #GUnixMount. If @time_read
- * is set, it will be filled with the mount timestamp.
+ * Gets a #GUnixMount for a given mount path. If @time_read
+ * is set, it will be filled with a unix timestamp for checking
+ * if the mounts have changed since with g_unix_mounts_changed_since().
+ * 
+ * Returns: a #GUnixMount. 
  **/
 GUnixMount *
 g_get_unix_mount_at (const char *mount_path,
@@ -947,8 +962,12 @@ g_get_unix_mount_at (const char *mount_path,
  * g_get_unix_mount_points:
  * @time_read: guint64 to contain a timestamp.
  * 
- * Returns a #GList of the UNIX mountpoints. If @time_read
- * is set, it will be filled with the mount timestamp.
+ * Gets a #GList of strings containing the unix mount points. 
+ * If @time_read is set, it will be filled with the mount timestamp,
+ * allowing for checking if the mounts have changed with 
+ * g_unix_mounts_points_changed_since().
+ * 
+ * Returns a #GList of the UNIX mountpoints. 
  **/
 GList *
 g_get_unix_mount_points (guint64 *time_read)
@@ -960,9 +979,11 @@ g_get_unix_mount_points (guint64 *time_read)
 }
 
 /**
- * g_unix_mounts_change_since:
+ * g_unix_mounts_changed_since:
  * @time: guint64 to contain a timestamp.
  * 
+ * Checks if the unix mounts have changed since a given unix time.
+ * 
  * Returns %TRUE if the mounts have changed since @time. 
  **/
 gboolean
@@ -972,9 +993,11 @@ g_unix_mounts_changed_since (guint64 time)
 }
 
 /**
- * g_unix_mount_points_change_since:
+ * g_unix_mount_points_changed_since:
  * @time: guint64 to contain a timestamp.
  * 
+ * Checks if the unix mount points have changed since a given unix time.
+ * 
  * Returns %TRUE if the mount points have changed since @time. 
  **/
 gboolean
@@ -1015,7 +1038,11 @@ g_unix_mount_monitor_class_init (GUnixMountMonitorClass *klass)
   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 
   gobject_class->finalize = g_unix_mount_monitor_finalize;
-  
+  /**
+   * GUnixMountMonitor::mounts-changed:
+   * 
+   * Emitted when the unix mounts have changed.
+   **/ 
   signals[MOUNTS_CHANGED] =
     g_signal_new ("mounts_changed",
 		  G_TYPE_FROM_CLASS (klass),
@@ -1024,7 +1051,11 @@ g_unix_mount_monitor_class_init (GUnixMountMonitorClass *klass)
 		  NULL, NULL,
 		  g_cclosure_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
-  
+  /**
+   * GUnixMountMonitor::mountpoints-changed:
+   * 
+   * Emitted when the unix mount points have changed.
+   **/
   signals[MOUNTPOINTS_CHANGED] =
     g_signal_new ("mountpoints_changed",
 		  G_TYPE_FROM_CLASS (klass),
@@ -1098,7 +1129,9 @@ g_unix_mount_monitor_init (GUnixMountMonitor *monitor)
 /**
  * g_unix_mount_monitor_new:
  * 
- * Returns a new #GUnixMountMonitor. 
+ * Gets a new #GUnixMountMonitor.
+ * 
+ * Returns: a #GUnixMountMonitor. 
  **/
 GUnixMountMonitor *
 g_unix_mount_monitor_new (void)
@@ -1116,6 +1149,7 @@ g_unix_mount_monitor_new (void)
  * g_unix_mount_free:
  * @mount_entry: a #GUnixMount.
  * 
+ * Frees a unix mount.
  **/
 void
 g_unix_mount_free (GUnixMount *mount_entry)
@@ -1130,8 +1164,9 @@ g_unix_mount_free (GUnixMount *mount_entry)
 
 /**
  * g_unix_mount_point_free:
- * @mount_point: 
+ * @mount_point: unix mount point to free.
  * 
+ * Frees a unix mount point.
  **/
 void
 g_unix_mount_point_free (GUnixMountPoint *mount_point)
@@ -1162,6 +1197,8 @@ strcmp_null (const char *str1,
  * @mount1: first #GUnixMount to compare.
  * @mount2: second #GUnixMount to compare.
  * 
+ * Compares two unix mounts.
+ * 
  * Returns 1, 0 or -1 if @mount1 is greater than, equal to,
  * or less than @mount2, respectively. 
  **/
@@ -1196,8 +1233,9 @@ g_unix_mount_compare (GUnixMount      *mount1,
  * g_unix_mount_get_mount_path:
  * @mount_entry: input #GUnixMount to get the mount path for.
  * 
- * Returns the mount path for @mount_entry.
+ * Gets the mount path for a unix mount.
  * 
+ * Returns: the mount path for @mount_entry.
  **/
 const char *
 g_unix_mount_get_mount_path (GUnixMount *mount_entry)
@@ -1211,6 +1249,9 @@ g_unix_mount_get_mount_path (GUnixMount *mount_entry)
  * g_unix_mount_get_device_path:
  * @mount_entry: a #GUnixMount.
  * 
+ * Gets the device path for a unix mount.
+ * 
+ * Returns: a string containing the device path.
  **/
 const char *
 g_unix_mount_get_device_path (GUnixMount *mount_entry)
@@ -1224,6 +1265,9 @@ g_unix_mount_get_device_path (GUnixMount *mount_entry)
  * g_unix_mount_get_fs_type:
  * @mount_entry: a #GUnixMount.
  * 
+ * Gets the filesystem type for the unix mount.
+ * 
+ * Returns: a string containing the file system type.
  **/
 const char *
 g_unix_mount_get_fs_type (GUnixMount *mount_entry)
@@ -1237,8 +1281,9 @@ g_unix_mount_get_fs_type (GUnixMount *mount_entry)
  * g_unix_mount_is_readonly:
  * @mount_entry: a #GUnixMount.
  * 
- * Returns %TRUE if @mount_entry is read only.
+ * Checks if a unix mount is mounted read only.
  * 
+ * Returns: %TRUE if @mount_entry is read only.
  **/
 gboolean
 g_unix_mount_is_readonly (GUnixMount *mount_entry)
@@ -1252,6 +1297,9 @@ g_unix_mount_is_readonly (GUnixMount *mount_entry)
  * g_unix_mount_is_system_internal:
  * @mount_entry: a #GUnixMount.
  * 
+ * Checks if a unix mount is a system path.
+ * 
+ * Returns: %TRUE if the unix mount is for a system path.
  **/
 gboolean
 g_unix_mount_is_system_internal (GUnixMount *mount_entry)
@@ -1266,6 +1314,8 @@ g_unix_mount_is_system_internal (GUnixMount *mount_entry)
  * @mount1: a #GUnixMount.
  * @mount2: a #GUnixMount.
  * 
+ * Compares two unix mount points.
+ * 
  * Returns 1, 0 or -1 if @mount1 is greater than, equal to,
  * or less than @mount2, respectively.
  **/
@@ -1306,8 +1356,11 @@ g_unix_mount_point_compare (GUnixMountPoint *mount1,
 
 /**
  * g_unix_mount_point_get_mount_path:
- * @mount_point: a #GUnixMount.
+ * @mount_point: a #GUnixMountPoint.
+ * 
+ * Gets the mount path for a unix mount point.
  * 
+ * Returns: a string containing the mount path.
  **/
 const char *
 g_unix_mount_point_get_mount_path (GUnixMountPoint *mount_point)
@@ -1319,8 +1372,11 @@ g_unix_mount_point_get_mount_path (GUnixMountPoint *mount_point)
 
 /**
  * g_unix_mount_point_get_device_path:
- * @mount_point: a #GUnixMount.
+ * @mount_point: a #GUnixMountPoint.
+ * 
+ * Gets the device path for a unix mount point.
  * 
+ * Returns: a string containing the device path.
  **/
 const char *
 g_unix_mount_point_get_device_path (GUnixMountPoint *mount_point)
@@ -1332,8 +1388,11 @@ g_unix_mount_point_get_device_path (GUnixMountPoint *mount_point)
 
 /**
  * g_unix_mount_point_get_fs_type:
- * @mount_point: a #GUnixMount.
+ * @mount_point: a #GUnixMountPoint.
  * 
+ * Gets the file system type for the mount point.
+ * 
+ * Returns: a string containing the file system type.
  **/
 const char *
 g_unix_mount_point_get_fs_type (GUnixMountPoint *mount_point)
@@ -1345,8 +1404,11 @@ g_unix_mount_point_get_fs_type (GUnixMountPoint *mount_point)
 
 /**
  * g_unix_mount_point_is_readonly:
- * @mount_point: a #GUnixMount.
+ * @mount_point: a #GUnixMountPoint.
+ * 
+ * Checks if a unix mount point is read only.
  * 
+ * Returns: %TRUE if a mount point is read only.
  **/
 gboolean
 g_unix_mount_point_is_readonly (GUnixMountPoint *mount_point)
@@ -1358,8 +1420,11 @@ g_unix_mount_point_is_readonly (GUnixMountPoint *mount_point)
 
 /**
  * g_unix_mount_point_is_user_mountable:
- * @mount_point:  a #GUnixMount.
+ * @mount_point: a #GUnixMountPoint.
+ * 
+ * Checks if a unix mount point is mountable by the user.
  * 
+ * Returns: %TRUE if the mount point is user mountable.
  **/
 gboolean
 g_unix_mount_point_is_user_mountable (GUnixMountPoint *mount_point)
@@ -1371,8 +1436,11 @@ g_unix_mount_point_is_user_mountable (GUnixMountPoint *mount_point)
 
 /**
  * g_unix_mount_point_is_loopback:
- * @mount_point:  a #GUnixMount.
+ * @mount_point: a #GUnixMountPoint.
  * 
+ * Checks if a unix mount point is a loopback device.
+ * 
+ * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise. 
  **/
 gboolean
 g_unix_mount_point_is_loopback (GUnixMountPoint *mount_point)
@@ -1482,6 +1550,10 @@ guess_mount_type (const char *mount_path,
  * g_unix_mount_guess_type:
  * @mount_entry: a #GUnixMount.
  * 
+ * Guesses the type of a unix mount. If the mount type cannot be 
+ * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
+ * 
+ * Returns: a #GUnixMountType. 
  **/
 GUnixMountType
 g_unix_mount_guess_type (GUnixMount *mount_entry)
@@ -1498,8 +1570,12 @@ g_unix_mount_guess_type (GUnixMount *mount_entry)
 
 /**
  * g_unix_mount_point_guess_type:
- * @mount_point: a #GUnixMount.
+ * @mount_point: a #GUnixMountPoint.
+ * 
+ * Guesses the type of a unix mount point. If the mount type cannot be 
+ * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN.
  * 
+ * Returns: a #GUnixMountType.
  **/
 GUnixMountType
 g_unix_mount_point_guess_type (GUnixMountPoint *mount_point)
diff --git a/gio/gunixmounts.h b/gio/gunixmounts.h
index 7e9c03b11..401612c3f 100644
--- a/gio/gunixmounts.h
+++ b/gio/gunixmounts.h
@@ -28,9 +28,38 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GUnixMount:
+ * 
+ * Defines a Unix mount.
+ **/
 typedef struct _GUnixMount GUnixMount;
+
+/**
+ * GUnixMountPoint:
+ * 
+ * Defines a Unix mount point (e.g. "/dev").
+ **/
 typedef struct _GUnixMountPoint GUnixMountPoint;
 
+/**
+ * GUnixMountType:
+ * @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_FLOPPY: Floppy disk UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_CDROM: CDROM UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_NFS: Network File System (NFS) UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_ZIP: ZIP UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_JAZ: JAZZ UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_MEMSTICK: Memory Stick UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_CF: Compact Flash UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_SM: Smart Media UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_SDMMC: SD/MMC UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_IPOD: iPod UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_CAMERA: Digital camera UNIX mount type.
+ * @G_UNIX_MOUNT_TYPE_HD: Hard drive UNIX mount type.
+ * 
+ * Types of UNIX mounts.
+ **/
 typedef enum {
   G_UNIX_MOUNT_TYPE_UNKNOWN,
   G_UNIX_MOUNT_TYPE_FLOPPY,
@@ -47,6 +76,11 @@ typedef enum {
   G_UNIX_MOUNT_TYPE_HD
 } GUnixMountType;
 
+/**
+ * GUnixMountMonitor:
+ * 
+ * Watches #GUnixMount<!-- -->s for changes.
+ **/
 typedef struct _GUnixMountMonitor GUnixMountMonitor;
 typedef struct _GUnixMountMonitorClass GUnixMountMonitorClass;
 
diff --git a/gio/gunixvolume.c b/gio/gunixvolume.c
index 6ce1260c7..a6e9867b2 100644
--- a/gio/gunixvolume.c
+++ b/gio/gunixvolume.c
@@ -31,7 +31,6 @@
 #include "gvolumeprivate.h"
 #include "gvolumemonitor.h"
 #include "gthemedicon.h"
-
 #include "glibintl.h"
 
 struct _GUnixVolume {
diff --git a/gio/gunixvolumemonitor.c b/gio/gunixvolumemonitor.c
index 2430e4bcc..08ad02d79 100644
--- a/gio/gunixvolumemonitor.c
+++ b/gio/gunixvolumemonitor.c
@@ -30,7 +30,6 @@
 #include "gunixvolume.h"
 #include "gunixdrive.h"
 #include "gvolumeprivate.h"
-
 #include "glibintl.h"
 
 struct _GUnixVolumeMonitor {
diff --git a/gio/gurifuncs.c b/gio/gurifuncs.c
index 2e1072319..757a9c0e2 100644
--- a/gio/gurifuncs.c
+++ b/gio/gurifuncs.c
@@ -24,6 +24,17 @@
 #include "gurifuncs.h"
 #include "string.h"
 
+/**
+ * SECTION:gurifuncs
+ * @short_description: URI Functions
+ * 
+ * Functions for manipulating Universal Resource Identifiers (URIs) as 
+ * defined by RFC 3986. It is highly recommended that you have read and
+ * understand RFC 3986 for understanding this API. A copy of RFC 3986 
+ * can be found at <ulink url="http://www.ietf.org/rfc/rfc3986.txt"/>.
+ *
+ **/
+
 static int
 unescape_character (const char *scanner)
 {
@@ -47,6 +58,8 @@ unescape_character (const char *scanner)
  * @escaped_string_end: a string.
  * @illegal_characters: a string of illegal characters not to be allowed.
  * 
+ * Unescapes a segment of an escaped string.
+ * 
  * Returns: an unescaped version of @escaped_string or %NULL on error.
  * The returned string should be freed when no longer needed.
  **/
@@ -109,10 +122,10 @@ g_uri_unescape_segment (const char *escaped_string,
  * @escaped_string: an escaped string to be unescaped.
  * @illegal_characters: a string of illegal characters not to be allowed.
  * 
- * Returns: an unescaped version of @escaped_string. 
- *
- * The returned string should be freed when no longer needed
- *
+ * Unescapes a whole escaped string.
+ * 
+ * Returns: an unescaped version of @escaped_string. The returned string 
+ * should be freed when no longer needed.
  **/
 char *
 g_uri_unescape_string (const char *escaped_string,
@@ -125,13 +138,12 @@ g_uri_unescape_string (const char *escaped_string,
  * g_uri_get_scheme:
  * @uri: a valid URI.
  * 
- * Returns: The "Scheme" component of the URI, or %NULL on error. 
- * RFC 3986 decodes the scheme as:
+ * Gets the scheme portion of a URI. RFC 3986 decodes the scheme as:
  * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] 
- * Popular schemes include "file", "http", "svn", etc.
- *
+ * Common schemes include "file", "http", "svn+ssh", etc.
+ * 
+ * Returns: The "Scheme" component of the URI, or %NULL on error. 
  * The returned string should be freed when no longer needed.
- *
  **/
 char *
 g_uri_get_scheme (const char  *uri)
@@ -205,8 +217,9 @@ gunichar_ok (gunichar c)
  * @reserved_chars_allowed: a string of reserve characters allowed to be used.
  * @allow_utf8: set %TRUE if the return value may include UTF8 characters.
  * 
- * Returns a #GString with the escaped URI appended.
- *
+ * Appends an escaped URI to @string.
+ * 
+ * Returns: a #GString with the escaped URI appended.
  **/
 GString *
 g_string_append_uri_escaped (GString *string,
@@ -253,11 +266,12 @@ g_string_append_uri_escaped (GString *string,
  * g_uri_escape_string:
  * @unescaped: the unescaped input string.
  * @reserved_chars_allowed: a string of reserve characters allowed to be used.
- * @allow_utf8: set to %TRUE if string can include UTF8 characters.
+ * @allow_utf8: a #gboolean. Set to %TRUE if string can include UTF8 characters.
  * 
- * Returns an escaped version of @unescaped. 
+ * Escapes a string for use in a URI.
  * 
- * The returned string should be freed when no longer needed.
+ * Returns: an escaped version of @unescaped. The returned string should be 
+ * freed when no longer needed.
  **/
 char *
 g_uri_escape_string (const char *unescaped,
diff --git a/gio/gurifuncs.h b/gio/gurifuncs.h
index cace2d90e..f162d0d76 100644
--- a/gio/gurifuncs.h
+++ b/gio/gurifuncs.h
@@ -27,10 +27,39 @@
 
 G_BEGIN_DECLS
 
+/**
+ * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS:
+ * 
+ * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@".
+ **/
 #define G_URI_RESERVED_CHARS_GENERIC_DELIMITERS ":/?#[]@"
+
+/**
+ * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS
+ * 
+ * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=".
+ **/
 #define G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS "!$&'()*+,;="
+
+/**
+ * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT:
+ * 
+ * Allowed characters in path elements. Includes "!$&'()*+,;=:@".
+ **/
 #define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":@"
+
+/**
+ * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH:
+ * 
+ * Allowed characters in a path. Includes "!$&'()*+,;=:@/".
+ **/
 #define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT "/"
+
+/**
+ * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO:
+ * 
+ * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:".
+ **/
 #define G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":"
 
 char *   g_uri_unescape_string       (const char *escaped_string,
diff --git a/gio/gvfs.c b/gio/gvfs.c
index 4dc1f256b..94f821983 100644
--- a/gio/gvfs.c
+++ b/gio/gvfs.c
@@ -27,6 +27,15 @@
 #include "giomodule.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gvfs
+ * @short_description: Virtual File System 
+ * @include: gio/gvfs.h
+ * 
+ * Entry point for using GIO functionality.
+ *
+ **/
+
 G_DEFINE_TYPE (GVfs, g_vfs, G_TYPE_OBJECT);
 
 static void
@@ -41,9 +50,11 @@ g_vfs_init (GVfs *vfs)
 
 /**
  * g_vfs_is_active:
- * @vfs: an  #GVfs.
+ * @vfs: a #GVfs.
+ * 
+ * Checks if the VFS is active.
  * 
- * Returns TRUE if construction of the @vfs was successful and its now active.
+ * Returns: %TRUE if construction of the @vfs was successful and it is now active.
  **/
 gboolean
 g_vfs_is_active (GVfs *vfs)
@@ -60,11 +71,12 @@ g_vfs_is_active (GVfs *vfs)
 
 /**
  * g_vfs_get_file_for_path:
- * @vfs: an input #GVfs.
+ * @vfs: a #GVfs.
  * @path: a string containing a VFS path.
  * 
- * Returns a #GFile for the given @path.
+ * Gets a #GFile for @path.
  * 
+ * Returns: a #GFile.
  **/
 GFile *
 g_vfs_get_file_for_path (GVfs *vfs,
@@ -82,14 +94,16 @@ g_vfs_get_file_for_path (GVfs *vfs,
 
 /**
  * g_vfs_get_file_for_uri:
- * @vfs: an input #GVfs.
- * @uri: an input string containing a URI path.
- *
+ * @vfs: a#GVfs.
+ * @uri: a string containing a URI path.
+ * 
+ * Gets a #GFile for @uri.
+ * 
  * This operation never fails, but the returned object
  * might not support any I/O operation if the uri
  * is malformed or if the uri type is not supported.
  * 
- * Returns a #GFile for the given @uri. 
+ * Returns: a #GFile. 
  * 
  **/
 GFile *
@@ -108,10 +122,11 @@ g_vfs_get_file_for_uri (GVfs *vfs,
 
 /**
  * g_vfs_get_supported_uri_schemes:
- * @vfs: an input #GVfs.
+ * @vfs: a #GVfs.
  * 
- * Returns: 
+ * Gets a list of URI schemes supported by GVFS. 
  * 
+ * Returns: a list of strings.
  **/
 const gchar * const *
 g_vfs_get_supported_uri_schemes (GVfs *vfs)
@@ -127,7 +142,7 @@ g_vfs_get_supported_uri_schemes (GVfs *vfs)
 
 /**
  * g_vfs_parse_name:
- * @vfs: an input #GVfs.
+ * @vfs: a #GVfs.
  * @parse_name: a string to be parsed by the VFS module.
  * 
  * This operation never fails, but the returned object might 
@@ -135,7 +150,6 @@ g_vfs_get_supported_uri_schemes (GVfs *vfs)
  * be parsed by the #GVfs module.
  * 
  * Returns a #GFile for the given @parse_name.
- * 
  **/
 GFile *
 g_vfs_parse_name (GVfs *vfs,
@@ -230,7 +244,9 @@ get_default_vfs (gpointer arg)
 /**
  * g_vfs_get_default:
  * 
- * Returns the default #GVfs for the system.
+ * Gets the default #GVfs for the system.
+ * 
+ * Returns: a #GVfs. 
  **/
 GVfs *
 g_vfs_get_default (void)
@@ -243,7 +259,9 @@ g_vfs_get_default (void)
 /**
  * g_vfs_get_local:
  * 
- * Returns the local #GVfs for the system.
+ * Gets the local #GVfs for the system.
+ * 
+ * Returns: a #GVfs.
  **/
 GVfs *
 g_vfs_get_local (void)
diff --git a/gio/gvfs.h b/gio/gvfs.h
index ebc82bded..ce7e3cd8c 100644
--- a/gio/gvfs.h
+++ b/gio/gvfs.h
@@ -35,6 +35,11 @@ G_BEGIN_DECLS
 #define G_IS_VFS(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_VFS))
 #define G_IS_VFS_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_VFS))
 
+/**
+ * GVfs:
+ * 
+ * Virtual File System object.
+ **/
 typedef struct _GVfs         GVfs; /* Dummy typedef */
 typedef struct _GVfsClass    GVfsClass;
 
@@ -61,7 +66,7 @@ struct _GVfsClass
 				                     const char *parse_name);
 
 
-
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);
diff --git a/gio/gvolume.c b/gio/gvolume.c
index 280f46c26..1f60525c2 100644
--- a/gio/gvolume.c
+++ b/gio/gvolume.c
@@ -26,6 +26,33 @@
 #include "gsimpleasyncresult.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gvolume
+ * @short_description: mounted volume management
+ * 
+ * Class for managing mounted volumes.
+ * 
+ * Unmounting volumes is an asynchronous operation. For more information about
+ * asynchronous operations, see #GAsyncReady and #GSimpleAsyncReady. To unmount a volume, 
+ * first call g_volume_unmount() with (at least) the volume and a #GAsyncReadyCallback.
+ * The callback will be fired when the operation has resolved (either with success or failure), 
+ * and a #GAsyncReady structure will be passed to the callback. 
+ * That callback should then call g_volume_unmount_finish() with
+ * the volume and the #GAsyncReady data to see if the operation was completed successfully.
+ * If an @error is present when g_volume_unmount_finish() is called, then it will
+ * be filled with any error information.
+ * 
+ * Ejecting volumes is also an asynchronous operation. 
+ * To eject a volume, call g_volume_eject() with (at least) the volume to eject 
+ * and a #GAsyncReadyCallback. The callback will be fired when the eject operation
+ * has resolved (either with success or failure), and a #GAsyncReady structure will
+ * be passed to the callback. That callback should then call g_volume_eject_finish()
+ * with the volume and the #GAsyncReady data to determine if the operation was completed
+ * successfully. If an @error is present when g_volume_eject_finish() is called, then
+ * it will be filled with any error information. 
+ *
+ **/
+
 static void g_volume_base_init (gpointer g_class);
 static void g_volume_class_init (gpointer g_class,
 				 gpointer class_data);
@@ -73,6 +100,11 @@ g_volume_base_init (gpointer g_class)
 
   if (! initialized)
     {
+     /**
+      * GVolume::changed:
+      * 
+      * Emitted when the volume has been changed.
+      **/
       g_signal_new (I_("changed"),
                     G_TYPE_VOLUME,
                     G_SIGNAL_RUN_LAST,
@@ -89,8 +121,9 @@ g_volume_base_init (gpointer g_class)
  * g_volume_get_root:
  * @volume: a #GVolume.
  * 
- * Returns a #GFile.
+ * Gets the root directory on @volume.
  * 
+ * Returns a #GFile.
  **/
 GFile *
 g_volume_get_root (GVolume *volume)
@@ -108,10 +141,10 @@ g_volume_get_root (GVolume *volume)
  * g_volume_get_name:
  * @volume: a #GVolume.
  * 
- * Returns the name for the given @volume. 
- * 
- * The returned string should be freed when no longer needed.
+ * Gets the name of @volume.
  * 
+ * Returns the name for the given @volume. The returned string should 
+ * be freed when no longer needed.
  **/
 char *
 g_volume_get_name (GVolume *volume)
@@ -127,10 +160,11 @@ g_volume_get_name (GVolume *volume)
 
 /**
  * g_volume_get_icon:
- * @volume:
+ * @volume: a #GVolume.
  * 
- * Returns the #GIcon for the given @volume.
+ * Gets the icon for @volume.
  * 
+ * Returns: a #GIcon.
  **/
 GIcon *
 g_volume_get_icon (GVolume *volume)
@@ -146,10 +180,11 @@ g_volume_get_icon (GVolume *volume)
   
 /**
  * g_volume_get_drive:
- * @volume:
+ * @volume: a #GVolume.
  * 
- * Returns the #GDrive for the given @volume.
+ * Gets the drive for the @volume.
  * 
+ * Returns: a #GDrive.
  **/
 GDrive *
 g_volume_get_drive (GVolume *volume)
@@ -165,7 +200,9 @@ g_volume_get_drive (GVolume *volume)
 
 /**
  * g_volume_can_unmount: 
- * @volume:
+ * @volume: a #GVolume.
+ * 
+ * Checks if @volume can be mounted.
  * 
  * Returns %TRUE if the @volume can be unmounted.
  **/
@@ -183,10 +220,11 @@ g_volume_can_unmount (GVolume *volume)
 
 /**
  * g_volume_can_eject:
- * @volume:
+ * @volume: a #GVolume.
  * 
- * Returns %TRUE if the @volume can be ejected.
+ * Checks if @volume can be ejected.
  * 
+ * Returns %TRUE if the @volume can be ejected.
  **/
 gboolean
 g_volume_can_eject (GVolume *volume)
@@ -202,10 +240,14 @@ g_volume_can_eject (GVolume *volume)
 
 /**
  * g_volume_unmount:
- * @volume:
- * @callback:
- * @user_data:
+ * @volume: a #GVolume.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @callback: a #GAsyncReadyCallback.
+ * @user_data: user data passed to @callback.
  * 
+ * Unmounts a volume. This is an asynchronous operation, and is finished by calling 
+ * g_volume_unmount_finish() with the @volume and #GAsyncResults data returned in the 
+ * @callback.
  * 
  **/
 void
@@ -235,12 +277,15 @@ g_volume_unmount (GVolume *volume,
 
 /**
  * g_volume_unmount_finish:
- * @volume:
- * @result:
+ * @volume: a #GVolume.
+ * @result: a #GAsyncResult.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Return:
  * 
+ * Finishes unmounting a volume. If any errors occured during the operation, 
+ * @error will be set to contain the errors and %FALSE will be returned.
+ * 
+ * Returns: %TRUE if the volume was successfully unmounted. %FALSE otherwise.
  **/
 gboolean
 g_volume_unmount_finish (GVolume              *volume,
@@ -265,9 +310,14 @@ g_volume_unmount_finish (GVolume              *volume,
 
 /**
  * g_volume_eject:
- * @volume:
- * @callback:
- * @user_data:
+ * @volume: a #GVolume.
+ * @cancellable: optional #GCancellable object, %NULL to ignore. 
+ * @callback: a #GAsyncReadyCallback.
+ * @user_data: user data passed to @callback.
+ * 
+ * Ejects a volume. This is an asynchronous operation, and is finished
+ * by calling g_volume_eject_finish() from the @callback with the @volume and 
+ * #GAsyncResults returned in the callback.
  * 
  **/
 void
@@ -297,12 +347,15 @@ g_volume_eject (GVolume         *volume,
 
 /**
  * g_volume_eject_finish:
- * @volume:
- * @result:
+ * @volume: a #GVolume.
+ * @result: a #GAsyncResult.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
- * Returns: 
  * 
+ * Finishes ejecting the volume. If any errors occured during the operation, 
+ * @error will be set to contain the errors and %FALSE will be returned.
+ * 
+ * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise.
  **/
 gboolean
 g_volume_eject_finish (GVolume              *volume,
diff --git a/gio/gvolume.h b/gio/gvolume.h
index 38addbe19..d45c901fb 100644
--- a/gio/gvolume.h
+++ b/gio/gvolume.h
@@ -34,9 +34,31 @@ G_BEGIN_DECLS
 #define G_VOLUME_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_VOLUME, GVolumeIface))
 
 /* GVolume typedef is in gfile.h due to include order issues */
+/**
+ * GDrive:
+ * 
+ * Opaque drive object.
+ **/
 typedef struct _GDrive          GDrive; /* Dummy typedef */
 typedef struct _GVolumeIface    GVolumeIface;
 
+/**
+ * GVolumeIface:
+ * @g_iface: The parent interface.
+ * @changed: Changed signal that is emitted when the volume's state has changed.
+ * @get_root: Gets a #GFile to the root directory of the #GVolume.
+ * @get_name: Gets a string containing the name of the #GVolume.
+ * @get_icon: Gets a #GIcon for the #GVolume.
+ * @get_drive: Gets a #GDrive the volume is located on.
+ * @can_unmount: Checks if a #GVolume can be unmounted.
+ * @can_eject: Checks if a #GVolume can be ejected.
+ * @unmount: Starts unmounting a #GVolume.
+ * @unmount_finish: Finishes an unmounting operation.
+ * @eject: Starts ejecting a #GVolume.
+ * @eject_finish: Finishes an eject operation.
+ * 
+ * Interface for implementing operations for mounted volumes.
+ **/
 struct _GVolumeIface
 {
   GTypeInterface g_iface;
diff --git a/gio/gvolumemonitor.c b/gio/gvolumemonitor.c
index a1b7c9b82..a1c983c88 100644
--- a/gio/gvolumemonitor.c
+++ b/gio/gvolumemonitor.c
@@ -24,6 +24,15 @@
 #include "gvolumemonitor.h"
 #include "glibintl.h"
 
+/**
+ * SECTION:gvolumemonitor
+ * @short_description: Volume Monitor
+ * @see_also: #GDirectoryMonitor, #GFileMonitor
+ * 
+ * Monitors a mounted volume for changes.
+ *
+ **/
+
 G_DEFINE_TYPE (GVolumeMonitor, g_volume_monitor, G_TYPE_OBJECT);
 
 enum {
@@ -56,6 +65,13 @@ g_volume_monitor_class_init (GVolumeMonitorClass *klass)
   
   gobject_class->finalize = g_volume_monitor_finalize;
 
+  /**
+   * GVolumeMonitor::volume-mounted:   
+   * @volume_monitor: The volume monitor emitting the signal.
+   * @volume: the volume that was mounted.
+   *
+   * Emitted when a volume is mounted.
+   **/
   signals[VOLUME_MOUNTED] = g_signal_new (I_("volume_mounted"),
 					  G_TYPE_VOLUME_MONITOR,
 					  G_SIGNAL_RUN_LAST,
@@ -63,7 +79,13 @@ g_volume_monitor_class_init (GVolumeMonitorClass *klass)
 					  NULL, NULL,
 					  g_cclosure_marshal_VOID__OBJECT,
 					  G_TYPE_NONE, 1, G_TYPE_VOLUME);
-  
+  /**
+   * GVolumeMonitor::volume-pre-unmount:
+   * @volume_monitor: The volume monitor emitting the signal.
+   * @volume: the volume that is being unmounted.
+   *
+   * Emitted when a volume is about to be unmounted.
+   **/ 
   signals[VOLUME_PRE_UNMOUNT] = g_signal_new (I_("volume_pre_unmount"),
 					      G_TYPE_VOLUME_MONITOR,
 					      G_SIGNAL_RUN_LAST,
@@ -71,7 +93,13 @@ g_volume_monitor_class_init (GVolumeMonitorClass *klass)
 					      NULL, NULL,
 					      g_cclosure_marshal_VOID__OBJECT,
 					      G_TYPE_NONE, 1, G_TYPE_VOLUME);
-  
+  /**
+   * GVolumeMonitor::volume-unmounted:
+   * @volume_monitor: The volume monitor emitting the signal.
+   * @volume: the volume that was unmounted.
+   * 
+   * Emitted when a volume is unmounted.
+   **/  
   signals[VOLUME_UNMOUNTED] = g_signal_new (I_("volume_unmounted"),
 					    G_TYPE_VOLUME_MONITOR,
 					    G_SIGNAL_RUN_LAST,
@@ -79,7 +107,13 @@ g_volume_monitor_class_init (GVolumeMonitorClass *klass)
 					    NULL, NULL,
 					    g_cclosure_marshal_VOID__OBJECT,
 					    G_TYPE_NONE, 1, G_TYPE_VOLUME);
-
+  /**
+   * GVolumeMonitor::drive-connected:
+   * @volume_monitor: The volume monitor emitting the signal.
+   * @drive: a #GDrive that was connected.
+   * 
+   * Emitted when a drive is connected to the system.
+   **/
   signals[DRIVE_CONNECTED] = g_signal_new (I_("drive_connected"),
 					   G_TYPE_VOLUME_MONITOR,
 					   G_SIGNAL_RUN_LAST,
@@ -88,7 +122,13 @@ g_volume_monitor_class_init (GVolumeMonitorClass *klass)
 					   g_cclosure_marshal_VOID__OBJECT,
 					   G_TYPE_NONE, 1, G_TYPE_DRIVE);
   
-  
+  /**
+   * GVolumeMonitor::drive-disconnected:
+   * @volume_monitor: The volume monitor emitting the signal.
+   * @drive: a #GDrive that was disconnected.
+   * 
+   * Emitted when a drive is disconnected from the system.
+   **/  
   signals[DRIVE_DISCONNECTED] = g_signal_new (I_("drive_disconnected"),
 					      G_TYPE_VOLUME_MONITOR,
 					      G_SIGNAL_RUN_LAST,
@@ -107,8 +147,9 @@ g_volume_monitor_init (GVolumeMonitor *monitor)
  * g_volume_monitor_get_mounted_volumes:
  * @volume_monitor: a #GVolumeMonitor.
  * 
- * Returns a #GList of mounted #GVolumes.
+ * Gets a list of volumes mounted on the computer.
  * 
+ * Returns a #GList of mounted #GVolumes.
  **/
 GList *
 g_volume_monitor_get_mounted_volumes  (GVolumeMonitor *volume_monitor)
@@ -126,8 +167,9 @@ g_volume_monitor_get_mounted_volumes  (GVolumeMonitor *volume_monitor)
  * g_volume_monitor_get_connected_drives:
  * @volume_monitor: a #GVolumeMonitor.
  * 
- * Returns a #GList of connected #GDrives. 
+ * Gets a list of drives connected to the computer.
  * 
+ * Returns: a #GList of connected #GDrives. 
  **/
 GList *
 g_volume_monitor_get_connected_drives (GVolumeMonitor *volume_monitor)
diff --git a/gio/gvolumemonitor.h b/gio/gvolumemonitor.h
index ef990a1c4..63892e925 100644
--- a/gio/gvolumemonitor.h
+++ b/gio/gvolumemonitor.h
@@ -36,11 +36,19 @@ G_BEGIN_DECLS
 #define G_IS_VOLUME_MONITOR(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_VOLUME_MONITOR))
 #define G_IS_VOLUME_MONITOR_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_VOLUME_MONITOR))
 
+/**
+ * GVolumeMonitor:
+ * @parent: The parent class.
+ *
+ * A Volume Monitor that watches for volume events.
+ **/
 typedef struct _GVolumeMonitor GVolumeMonitor;
 typedef struct _GVolumeMonitorClass GVolumeMonitorClass;
 
 struct _GVolumeMonitor {
   GObject parent;
+
+  /*< private >*/
   gpointer priv;
 };
 
@@ -65,7 +73,7 @@ struct _GVolumeMonitorClass {
   GList * (*get_mounted_volumes)  (GVolumeMonitor *volume_monitor);
   GList * (*get_connected_drives) (GVolumeMonitor *volume_monitor);
 
-
+  /*< private >*/
   /* Padding for future expansion */
   void (*_g_reserved1) (void);
   void (*_g_reserved2) (void);