More documentation cleanup and filling in missing information, bringing

2007-12-09  A. Walton  <awalton@svn.gnome.org>

	* gdesktopappinfo.c:
	* gdrive.c:
	* gdrive.h:
	* gfile.c:
	* gfile.h:
	* gfileattribute.c:
	* gfileenumerator.c:
	* gioerror.c:
	* gioscheduler.c:
	* gioscheduler.h:
	* gloadableicon.c:
	* gmemoryinputstream.c:
	* gmemoryoutputstream.c:
	* goutputstream.h:
	* gsimpleasyncresult.c:
	More documentation cleanup and filling in missing information, 
bringing
	GIO to 99% symbol coverage.

svn path=/trunk/; revision=6077

17 files changed, 213 insertions, 90 deletions

diff --git a/gio/ChangeLog b/gio/ChangeLog
index 0e2a34c21..0d427658c 100644
--- a/gio/ChangeLog
+++ b/gio/ChangeLog
@@ -1,3 +1,23 @@
+2007-12-09  A. Walton  <awalton@svn.gnome.org>
+
+	* gdesktopappinfo.c:
+	* gdrive.c:
+	* gdrive.h:
+	* gfile.c:
+	* gfile.h:
+	* gfileattribute.c:
+	* gfileenumerator.c:
+	* gioerror.c:
+	* gioscheduler.c:
+	* gioscheduler.h:
+	* gloadableicon.c:
+	* gmemoryinputstream.c:
+	* gmemoryoutputstream.c:
+	* goutputstream.h:
+	* gsimpleasyncresult.c:
+	More documentation cleanup and filling in missing information, bringing
+	GIO to 99% symbol coverage.
+
 2007-12-08  Hans Breuer  <hans@breuer.org>
 
 	[gio compiles and links on win32, not sure how much already works]
diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c
index 121ff3370..1849fbd09 100644
--- a/gio/gdesktopappinfo.c
+++ b/gio/gdesktopappinfo.c
@@ -1572,9 +1572,13 @@ g_app_info_get_default_for_type (const char *content_type,
 
 /**
  * g_app_info_get_default_for_uri_scheme:
- * @uri_scheme:
+ * @uri_scheme: a string containing a URI scheme.
+ *
+ * Gets the default application for launching applications using this URI scheme.
+ *
+ * TODO: This is currently unimplemented.
  * 
- * Returns: #GAppInfo
+ * Returns: %NULL.
  **/
 GAppInfo *
 g_app_info_get_default_for_uri_scheme (const char *uri_scheme)
@@ -1668,8 +1672,10 @@ collect_apps (gpointer key,
 
 /**
  * g_app_info_get_all:
+ *
+ * Gets a list of all of the applications currently registered on this system.
  * 
- * Returns: a newly allocated #GList of references to #GAppInfo s.
+ * Returns: a newly allocated #GList of references to #GAppInfo<!---->s.
  **/
 GList *
 g_app_info_get_all (void)
diff --git a/gio/gdrive.c b/gio/gdrive.c
index 5d851e39b..41e5171a6 100644
--- a/gio/gdrive.c
+++ b/gio/gdrive.c
@@ -171,7 +171,7 @@ g_drive_has_volumes (GDrive *drive)
  * Gets a list of volumes for a drive.
  * 
  * Returns: #GList containing any #GVolume<!---->s on the given @drive.
- * NOTE: Fact-check this.
+ * <!-- NOTE: Fact-check this. -->
  **/
 GList *
 g_drive_get_volumes (GDrive *drive)
@@ -289,13 +289,17 @@ g_drive_mount (GDrive              *drive,
 
 /**
  * g_drive_mount_finish:
- * @drive: pointer to a #GDrive.
+ * @drive: a #GDrive.
  * @result: a #GAsyncResult.
  * @error: a #GError.
  * 
- * Finishes mounting a drive.
+ * Finishes mounting a drive. 
+ *
+ * If the @drive's interface does not implement the mount operation, @error will 
+ * be set to %G_IO_ERROR_NOT_SUPPORTED and %FALSE will be returned.
  * 
- * Returns: %TRUE, %FALSE if operation failed.
+ * Returns: %TRUE if the mount was finished successfully, 
+ *     %FALSE if operation failed.
  **/
 gboolean
 g_drive_mount_finish (GDrive        *drive,
@@ -359,6 +363,9 @@ g_drive_eject (GDrive              *drive,
  * @error: a #GError.
  * 
  * Finishes ejecting a drive.
+ *
+ * If @drive's interface does not implement the eject operation, @error will 
+ * be set to %G_IO_ERROR_NOT_SUPPORTED and %FALSE will be returned.
  * 
  * Returns: %TRUE if the drive has been ejected successfully,
  * %FALSE otherwise.
diff --git a/gio/gdrive.h b/gio/gdrive.h
index 7d0965362..f81339c8c 100644
--- a/gio/gdrive.h
+++ b/gio/gdrive.h
@@ -45,7 +45,7 @@ G_BEGIN_DECLS
  * @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_fn: Mounts a given #GDrive.
  * @mount_finish: Finishes a mount operation.
  * @eject: Ejects a #GDrive.
  * @eject_finish: Finishes an eject operation.
diff --git a/gio/gfile.c b/gio/gfile.c
index 99cdac066..f9a9cbc7d 100644
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -52,6 +52,7 @@
  * 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.
+ * g_file_new_for_commandline_arg() for a command line argument.
  * 
  * You can move through the filesystem with #GFile handles with
  * g_file_get_parent() to get a handle to the parent directory.
@@ -425,9 +426,9 @@ g_file_dup (GFile *file)
  * Creates a hash value for a #GFile.
  *
  * Returns: 0 if @file is not a valid #GFile, otherwise an 
- * integer that can be used as hash value for the #GFile. 
- * This function is intended for easily hashing a #GFile to 
- * add to a #GHashTable or similar data structure.
+ *     integer that can be used as hash value for the #GFile. 
+ *     This function is intended for easily hashing a #GFile to 
+ *     add to a #GHashTable or similar data structure.
  **/
 guint
 g_file_hash (gconstpointer file)
@@ -449,7 +450,7 @@ g_file_hash (gconstpointer file)
  * Checks equality of two given #GFile<!-- -->s
  *
  * Returns: %TRUE if @file1 and @file2 are equal.
- * %FALSE if either is not a #GFile.
+ *     %FALSE if either is not a #GFile.
  **/
 gboolean
 g_file_equal (GFile *file1,
@@ -478,7 +479,7 @@ g_file_equal (GFile *file1,
  * file system, then %NULL will be returned.
  *
  * Returns: a #GFile structure to the parent of the given
- * #GFile or %NULL. 
+ *     #GFile or %NULL. 
  **/
 GFile *
 g_file_get_parent (GFile *file)
@@ -501,8 +502,8 @@ g_file_get_parent (GFile *file)
  * it exists.
  *
  * Returns: a #GFile to a child specified by 
- * @name or %NULL if @name is %NULL, or the specified
- * child doesn't exist.
+ *     @name or %NULL if @name is %NULL, or the specified
+ *     child doesn't exist.
  **/
 GFile *
 g_file_get_child (GFile      *file,
@@ -525,7 +526,7 @@ g_file_get_child (GFile      *file,
  * set with %G_IO_ERROR_INVALID_FILENAME.
  * 
  * Returns: a #GFile to the specified child, or 
- * %NULL if @display_name is %NULL.  
+ *     %NULL if @display_name is %NULL.  
  **/
 GFile *
 g_file_get_child_for_display_name (GFile      *file,
@@ -628,9 +629,10 @@ g_file_resolve_relative_path (GFile      *file,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
  *
- * Gets a #GFileEnumerator for the children of @file that match @attributes, 
+ * Gets a #GFileEnumerator for the children of @file. The returned enumerator will 
+ * automatically generate a #GFileAttributeMatcher internally that match @attributes, 
  * where attributes is a #GFileAttributeInfo query string (e.g. "std:type", 
- * "std:*").
+ * "std:*"). See g_file_enumerator_next_file() for details.
  * 
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
@@ -683,10 +685,11 @@ g_file_enumerate_children (GFile                *file,
  * @callback: a #GAsyncReadyCallback to call when the request is satisfied
  * @user_data: the data to pass to callback function
  *
- * 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().
+ * Asynchronously gets a #GFileEnumerator for the children of @file. The returned 
+ * file enumerator will automatically generate a #GFileAttributeMatcher 
+ * that matches @attributes, where attributes is a #GFileAttributeInfo query 
+ * string (e.g. "std:type", "std:*"). See g_file_enumerator_next_file() for details.
+ * For the synchronous version of this function, see g_file_enumerate_children().
  * 
  * To finish this asynchronous operation, see g_file_enumerate_children_finish().
  **/
@@ -1166,8 +1169,8 @@ g_file_replace (GFile             *file,
  * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback.
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  *
  * Asynchronously reads @file. 
  *
@@ -1239,8 +1242,8 @@ g_file_read_finish (GFile         *file,
  * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
  * Readies a file for appending data asynchronously. 
  *
@@ -1316,8 +1319,8 @@ g_file_append_to_finish (GFile         *file,
  * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
  * Creates a new file asynchronously. 
  *
@@ -1396,8 +1399,8 @@ g_file_create_finish (GFile         *file,
  * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
  * Replaces a file's contents asynchronously. If @make_backup is 
  * %TRUE, this function will attempt to make a backup of the current file.
@@ -1659,6 +1662,22 @@ build_attribute_list_for_copy (GFileAttributeInfoList *attributes,
   return g_string_free (s, FALSE);
 }
 
+/**
+ * g_file_copy_attributes:
+ * @source: a #GFile with attributes.
+ * @destination: a #GFile to copy attributes to.
+ * @flags: a set of #GFileCopyFlags.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @error: a #GError, %NULL to ignore.
+ *
+ * Copies the file attributes from @source to @destination. 
+ *
+ * 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 attributes were copied successfully, %FALSE otherwise.
+ **/
 gboolean
 g_file_copy_attributes (GFile           *source,
 			GFile           *destination,
@@ -2323,8 +2342,8 @@ g_file_set_display_name (GFile         *file,
  * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
  * Asynchronously sets the display name for a given #GFile.
  * For the synchronous version of this function, see g_file_set_display_name().
@@ -2906,8 +2925,8 @@ g_file_set_attribute_int64 (GFile                *file,
  * @file: input #GFile.
  * @mount_operation: a #GMountOperation.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
  * Mounts a mountable file using @mount_operation, if possible. 
  *
@@ -2982,8 +3001,8 @@ g_file_mount_mountable_finish (GFile         *file,
  * g_file_unmount_mountable:
  * @file: input #GFile.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  *
  * Starts an asynchronous unmount operation. 
  * 
@@ -3058,8 +3077,8 @@ g_file_unmount_mountable_finish (GFile         *file,
  * g_file_eject_mountable:
  * @file: input #GFile.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
  * Starts an asynchronous eject on a mountable.  
  * When this operation has completed, @callback will be called with
@@ -3901,8 +3920,8 @@ g_file_new_for_commandline_arg (const char *arg)
  * @location: input #GFile.
  * @mount_operation: a #GMountOperation.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
  * Starts the @mount_operation, mounting the volume at @location. 
  * 
@@ -4241,9 +4260,17 @@ load_contents_open_callback (GObject      *obj,
  * @file: input #GFile.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @read_more_callback: a #GFileReadMoreCallback.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
- * 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to the callback functions.
+ *
+ * Reads the partial contents of a file. A #GFileReadMoreCallback should be 
+ * used to stop reading from the file when appropriate, else this function
+ * will behave exactly as g_file_load_contents_async(). This operation 
+ * can be finished by g_file_load_partial_contents_finish().
+ *
+ * Users of this function should be aware that @user_data is passed to 
+ * both the @read_more_callback and the @callback.
+ *
  * 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. 
@@ -4348,8 +4375,8 @@ g_file_load_partial_contents_finish (GFile         *file,
  * g_file_load_contents_async:
  * @file: input #GFile.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
  * Starts an asynchronous load of the @file's contents. 
  * When the load operation has completed, @callback will be called 
@@ -4625,8 +4652,8 @@ replace_contents_open_callback (GObject      *obj,
  * @make_backup: a #gboolean.
  * @flags: a set of #GFileCreateFlags.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback. 
- * @user_data: a #gpointer. 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  * 
  * Starts an asynchronous replacement of @file with the given 
  * @contents of @length bytes. @etag will replace the document's 
diff --git a/gio/gfile.h b/gio/gfile.h
index 5872b8d00..67dce7ab4 100644
--- a/gio/gfile.h
+++ b/gio/gfile.h
@@ -127,11 +127,16 @@ typedef void (*GFileProgressCallback) (goffset current_num_bytes,
 
 /**
  * GFileReadMoreCallback:
- * @file_contents:
- * @file_size:
- * @callback_data:
+ * @file_contents: the data as currently read.
+ * @file_size: the size of the data currently read.
+ * @callback_data: data passed to the callback.
  *
- * 
+ * When loading the partial contents of a file with g_file_read_partial_contents(), 
+ * it may become necessary to determine if any more data from the file should be loaded. 
+ * A #GFileReadMoreCallback function facilitates this by returning %TRUE if more data 
+ * should be read, or %FALSE otherwise.
+ *
+ * Returns: %TRUE if more data should be read back. %FALSE otherwise.
  **/
 typedef gboolean (* GFileReadMoreCallback) (const char *file_contents,
 					    goffset file_size,
@@ -180,7 +185,7 @@ typedef gboolean (* GFileReadMoreCallback) (const char *file_contents,
  * @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_fn: 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.
diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c
index d9492be47..31bb1e1c7 100644
--- a/gio/gfileattribute.c
+++ b/gio/gfileattribute.c
@@ -61,7 +61,7 @@
  * 
  * <para>
  * <table>
- * <title>GFileAttributes Namespaces</title>
+ * <title>GFileAttributes Default Namespaces</title>
  * <tgroup cols='2' align='left'><thead>
  * <row><entry>Namspace</entry><entry>Description</entry></row>
  * </thead>
@@ -110,8 +110,12 @@
  * </table>
  * </para>
  * 
+ * Please note that these are not all of the possible namespaces.
  * More namespaces can be added from GIO modules or by individual applications. 
  * For more information about writing GIO modules, see #GIOModule.
+ *
+ * <!-- TODO: Implementation note about using extended attributes on supported 
+ * file systems -->
  * 
  * <para><table>
  * <title>GFileAttributes Built-in Keys and Value Types</title>
diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c
index 3b8b84b83..7b96cd796 100644
--- a/gio/gfileenumerator.c
+++ b/gio/gfileenumerator.c
@@ -33,6 +33,19 @@
  * SECTION:gfileenumerator
  * @short_description: Enumerated Files Routines
  * 
+ * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s, returning
+ * a #GFileInfo structure for each file enumerated (e.g. g_file_enumerate_children() 
+ * will return a #GFileEnumerator for each of the children within a directory).
+ *
+ * To get the next file's information from a #GFileEnumerator, use 
+ * g_file_enumerator_next_file() or its asynchronous version, 
+ * g_file_enumerator_next_file_async(). Note that the asynchronous version will
+ * return a list of #GFileInfo<!---->s, whereas the synchronous will only return 
+ * the next file in the enumerator.
+ *
+ * To close a #GFileEnumerator, use g_file_enumerator_close(), or its asynchronous 
+ * version, g_file_enumerator_close_async(). Once a #GFileEnumerator is closed, 
+ * no further actions may be performed on it, and it should be freed with g_object_unref().
  * 
  **/ 
 
@@ -108,7 +121,9 @@ g_file_enumerator_init (GFileEnumerator *enumerator)
  * @error: location to store the error occuring, or %NULL to ignore
  *
  * Returns information for the next file in the enumerated object.
- * Will block until the information is available.
+ * Will block until the information is available. The #GFileInfo 
+ * returned from this function will contain attributes that match the 
+ * attribute string that was passed when the #GFileEnumerator was created.
  *
  * On error, returns %NULL and sets @error to the error. If the
  * enumerator is at the end, %NULL will be returned and @error will
@@ -234,12 +249,12 @@ next_async_callback_wrapper (GObject      *source_object,
  * @io_priority: the <link linkend="gioscheduler">io priority</link> 
  *     of the request. 
  * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: callback to call when the request is satisfied
- * @user_data: the user_data to pass to callback function 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
  *
  * Request information for a number of files from the enumerator asynchronously.
  * When all i/o for the operation is finished the @callback will be called with
- * the requested information.
+ * the requested information. 
  *
  * The callback can be called with less than @num_files files in case of error
  * or at the end of the enumerator. In case of a partial error the callback will
@@ -316,9 +331,9 @@ g_file_enumerator_next_files_async (GFileEnumerator     *enumerator,
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
  * 
+ * Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
  * 
- * 
- * Returns: 
+ * Returns: a #GList of #GFileInfo<!---->s.
  **/
 GList *
 g_file_enumerator_next_files_finish (GFileEnumerator  *enumerator,
@@ -366,9 +381,15 @@ close_async_callback_wrapper (GObject      *source_object,
  * @io_priority: the <link linkend="io-priority">I/O priority</link> 
  *     of the request.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
- * @callback: callback to call when the request is satisfied
- * @user_data: the user_data to pass to callback function 
- * 
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
+ *
+ * Asynchronously closes the file enumerator. 
+ *
+ * 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 in 
+ * g_file_enumerator_close_finish(). 
  **/
 void
 g_file_enumerator_close_async (GFileEnumerator     *enumerator,
@@ -417,7 +438,16 @@ g_file_enumerator_close_async (GFileEnumerator     *enumerator,
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
  * 
+ * Finishes closing a file enumerator, started from g_file_enumerator_close_async().
  * 
+ * If the file enumerator was already closed when g_file_enumerator_close_async() 
+ * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and 
+ * return %FALSE. If the file enumerator had pending operation when the close 
+ * operation was started, then this function will report %G_IO_ERROR_PENDING, and
+ * return %FALSE.  If @cancellable was not %NULL, then the operation may have been 
+ * cancelled by triggering the cancellable object from another thread. If the operation
+ * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be 
+ * returned. 
  * 
  * Returns: %TRUE if the close operation has finished successfully.
  **/
@@ -446,6 +476,8 @@ g_file_enumerator_close_finish (GFileEnumerator  *enumerator,
 /**
  * g_file_enumerator_is_closed:
  * @enumerator: a #GFileEnumerator.
+ *
+ * Checks if the file enumerator has been closed.
  * 
  * Returns: %TRUE if the @enumerator is closed.
  **/
@@ -461,6 +493,8 @@ g_file_enumerator_is_closed (GFileEnumerator *enumerator)
  * g_file_enumerator_has_pending:
  * @enumerator: a #GFileEnumerator.
  * 
+ * Checks if the file enumerator has pending operations.
+ *
  * Returns: %TRUE if the @enumerator has pending operations.
  **/
 gboolean
@@ -476,6 +510,7 @@ g_file_enumerator_has_pending (GFileEnumerator *enumerator)
  * @enumerator: a #GFileEnumerator.
  * @pending: a boolean value.
  * 
+ * Sets the file enumerator as having pending operations.
  **/
 void
 g_file_enumerator_set_pending (GFileEnumerator *enumerator,
diff --git a/gio/gioerror.c b/gio/gioerror.c
index df2d31b60..194275dba 100644
--- a/gio/gioerror.c
+++ b/gio/gioerror.c
@@ -30,6 +30,7 @@
  * SECTION:gioerror
  * @short_description: Error helper functions
  *
+ * Contains helper functions for reporting errors to the user.
  **/
 
 /**
diff --git a/gio/gioscheduler.c b/gio/gioscheduler.c
index 13a8cf477..46484af51 100644
--- a/gio/gioscheduler.c
+++ b/gio/gioscheduler.c
@@ -30,8 +30,8 @@
  * SECTION:gioscheduler
  * @short_description: I/O Scheduler
  * 
- * Schedules asynchronous I/O operations for integration into the main 
- * event loop (#GMainLoop).
+ * Schedules asynchronous I/O operations. #GIOScheduler integrates into the main 
+ * event loop (#GMainLoop) and may use threads if they are available.
  * 
  * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm>
  * Each I/O operation has a priority, and the scheduler uses the priorities
diff --git a/gio/gioscheduler.h b/gio/gioscheduler.h
index c6da94ddf..30b5ec6cd 100644
--- a/gio/gioscheduler.h
+++ b/gio/gioscheduler.h
@@ -50,7 +50,7 @@ typedef void (*GIOJobFunc) (GIOJob *job,
 
 /**
  * GIODataFunc:
- * @user_data:
+ * @user_data: data to pass to the I/O function.
  * 
  * I/O Data function.
  * 
diff --git a/gio/gloadableicon.c b/gio/gloadableicon.c
index e1f8a4350..16d9405ef 100644
--- a/gio/gloadableicon.c
+++ b/gio/gloadableicon.c
@@ -97,7 +97,7 @@ g_loadable_icon_base_init (gpointer g_class)
  * g_loadable_icon_load:
  * @icon: a #GLoadableIcon.
  * @size: an integer.
- * @type: 
+ * @type:  a location to store the type of the loaded icon, %NULL to ignore.
  * @cancellable: optional #GCancellable object, %NULL to ignore. 
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
@@ -155,7 +155,7 @@ g_loadable_icon_load_async (GLoadableIcon       *icon,
  * g_loadable_icon_load_finish:
  * @icon: a #GLoadableIcon.
  * @res: a #GAsyncResult.
- * @type:
+ * @type: a location to store the type of the loaded icon, %NULL to ignore.
  * @error: a #GError location to store the error occuring, or %NULL to 
  * ignore.
  * 
diff --git a/gio/gmemoryinputstream.c b/gio/gmemoryinputstream.c
index 5274ab5f1..ca895b9e9 100644
--- a/gio/gmemoryinputstream.c
+++ b/gio/gmemoryinputstream.c
@@ -165,9 +165,11 @@ g_memory_input_stream_init (GMemoryInputStream *stream)
 
 /**
  * g_memory_input_stream_set_free_data:
- * @stream:
- * @free_data:
+ * @stream: a #GMemoryInputStream.
+ * @free_data: a #gboolean. If %TRUE, frees the data within @stream.
  * 
+ * Sets if the data within the @stream should be freed when the stream 
+ * is freed. 
  **/
 void
 g_memory_input_stream_set_free_data (GMemoryInputStream *stream,
@@ -182,6 +184,8 @@ g_memory_input_stream_set_free_data (GMemoryInputStream *stream,
  * g_memory_input_stream_from_data:
  * @data: input data.
  * @len: length of the data.
+ *
+ * Creates a new #GMemoryInputStream with data in memory of a given size.
  * 
  * Returns: new #GInputStream read from @data of @len bytes.
  **/
@@ -228,9 +232,11 @@ g_memory_input_stream_read (GInputStream  *stream,
 
 /**
  * g_memory_input_stream_get_data:
- * @stream:
+ * @stream: a #GMemoryInputStream
  * 
- * Returns: 
+ * Gets a pointer to the data within the #GMemoryInputStream.
+ *
+ * Returns: a pointer to the memory in the @stream.
  **/
 const void *
 g_memory_input_stream_get_data (GMemoryInputStream *stream)
@@ -242,9 +248,12 @@ g_memory_input_stream_get_data (GMemoryInputStream *stream)
 
 /**
  * g_memory_input_stream_get_data_size:
- * @stream:
+ * @stream: a #GMemoryInputStream
  * 
- * Returns: 
+ * Gets the size of the data within the #GMemoryInputStream.
+ *
+ * Returns: a gsize with the size of the data in @stream, or -1
+ *     on error.
  **/
 gsize
 g_memory_input_stream_get_data_size (GMemoryInputStream *stream)
diff --git a/gio/gmemoryoutputstream.c b/gio/gmemoryoutputstream.c
index 8444b254c..85d33df2a 100644
--- a/gio/gmemoryoutputstream.c
+++ b/gio/gmemoryoutputstream.c
@@ -213,12 +213,12 @@ g_memory_output_stream_init (GMemoryOutputStream *stream)
  * Creates a new #GMemoryOutputStream. If @data is non-%NULL it will use
  * that for its internal storage otherwise it will create a new #GByteArray.
  * In both cases the internal #GByteArray can later be accessed through the 
- * "data" property.
+ * "data" property, or with g_memory_output_stream_get_data().
  *
  * Note: The new stream will not take ownership of the supplied
  * @data so you have to free it yourself after use or explicitly
  * ask for it be freed on close by setting the "free-array" 
- * property to $TRUE.
+ * property to %TRUE.
  *
  * Return value: A newly created #GMemoryOutputStream object.
  **/
@@ -239,9 +239,11 @@ g_memory_output_stream_new (GByteArray *data)
 
 /**
  * g_memory_output_stream_set_free_data:
- * @ostream:
- * @free_data:
+ * @ostream: a #GMemoryOutputStream.
+ * @free_data: a #gboolean. If %TRUE, frees the data within @stream.
  * 
+ * Sets if the data within the @stream should be freed when the stream 
+ * is freed. 
  **/
 void
 g_memory_output_stream_set_free_data (GMemoryOutputStream *ostream,
@@ -258,9 +260,10 @@ g_memory_output_stream_set_free_data (GMemoryOutputStream *ostream,
 
 /**
  * g_memory_output_stream_set_max_size:
- * @ostream:
- * @max_size:
- * 
+ * @ostream: a #GMemoryOutputStream.
+ * @max_size: a #guint to set as the maximum stream size.
+ *
+ * Sets a size limit on the data contained within the output stream.
  **/
 void
 g_memory_output_stream_set_max_size (GMemoryOutputStream *ostream,
@@ -372,7 +375,9 @@ g_memory_output_stream_get_property (GObject    *object,
 
 /**
  * g_memory_output_stream_get_data:
- * @ostream:
+ * @ostream: a #GMemoryOutputStream
+ *
+ * Gets any loaded data from the @ostream.
  * 
  * Returns: #GByteArray of the stream's data.
  **/
diff --git a/gio/goutputstream.c b/gio/goutputstream.c
index fcfc17795..f827c81a5 100644
--- a/gio/goutputstream.c
+++ b/gio/goutputstream.c
@@ -30,8 +30,8 @@
 /**
  * SECTION:goutputstream
  * @short_description: Base class for implementing streaming output
- * 
- * 
+ *
+ *
  *
  **/
 
diff --git a/gio/goutputstream.h b/gio/goutputstream.h
index 0d9f828e0..b617c7ef7 100644
--- a/gio/goutputstream.h
+++ b/gio/goutputstream.h
@@ -40,11 +40,11 @@ G_BEGIN_DECLS
 
 /**
  * GOutputStreamSpliceFlags:
- * @G_OUTPUT_STREAM_SPLICE_FLAGS_NONE:
- * @G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_SOURCE:
- * @G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_TARGET:
- * 
+ * @G_OUTPUT_STREAM_SPLICE_FLAGS_NONE: Do not close either stream.
+ * @G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_SOURCE: Close the source stream after the splice.
+ * @G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_TARGET: Close the target stream after the splice.
  * 
+ * GOutputStreamSpliceFlags determine how streams should be spliced.
  **/
 typedef enum {
   G_OUTPUT_STREAM_SPLICE_FLAGS_NONE = 0,
diff --git a/gio/gsimpleasyncresult.c b/gio/gsimpleasyncresult.c
index b3f62eb18..21dde27fd 100644
--- a/gio/gsimpleasyncresult.c
+++ b/gio/gsimpleasyncresult.c
@@ -653,7 +653,9 @@ g_simple_async_result_run_in_thread (GSimpleAsyncResult     *simple,
  * @format: a formatted error reporting string.
  * @...: a list of variables to fill in @format.
  * 
- * Reports an error in an idle function.
+ * Reports an error in an asynchronous function in an idle function by 
+ * directly setting the contents of the #GAsyncResult with the given error
+ * information.
  **/
 void
 g_simple_async_report_error_in_idle (GObject             *object,
@@ -683,13 +685,15 @@ g_simple_async_report_error_in_idle (GObject             *object,
 }
 
 /**
- * g_simple_async_report_error_in_idle:
+ * g_simple_async_report_gerror_in_idle:
  * @object: a #GObject.
  * @callback: a #GAsyncReadyCallback. 
  * @user_data: user data passed to @callback.
  * @error: the #GError to report
  * 
- * Reports an error in an idle function.
+ * Reports an error in an idle function. Similar to 
+ * g_simple_async_report_error_in_idle(), but takes a #GError rather 
+ * than building a new one.
  **/
 void
 g_simple_async_report_gerror_in_idle (GObject *object,