summaryrefslogtreecommitdiff
path: root/gio
diff options
context:
space:
mode:
Diffstat (limited to 'gio')
-rw-r--r--gio/ChangeLog20
-rw-r--r--gio/gdesktopappinfo.c12
-rw-r--r--gio/gdrive.c15
-rw-r--r--gio/gdrive.h2
-rw-r--r--gio/gfile.c105
-rw-r--r--gio/gfile.h15
-rw-r--r--gio/gfileattribute.c6
-rw-r--r--gio/gfileenumerator.c53
-rw-r--r--gio/gioerror.c1
-rw-r--r--gio/gioscheduler.c4
-rw-r--r--gio/gioscheduler.h2
-rw-r--r--gio/gloadableicon.c4
-rw-r--r--gio/gmemoryinputstream.c21
-rw-r--r--gio/gmemoryoutputstream.c21
-rw-r--r--gio/goutputstream.c4
-rw-r--r--gio/goutputstream.h8
-rw-r--r--gio/gsimpleasyncresult.c10
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,
View Lorry Controller Status