From: A. Walton Date: Sun, 9 Dec 2007 15:51:12 +0000 (+0000) Subject: More documentation cleanup and filling in missing information, bringing X-Git-Tag: GLIB_2_15_1~178 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=ab69ee2945af25672ad4bb48ae6ab5b87f0e06e2;p=platform%2Fupstream%2Fglib.git More documentation cleanup and filling in missing information, bringing 2007-12-09 A. Walton * 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 --- diff --git a/gio/ChangeLog b/gio/ChangeLog index 0e2a34c..0d42765 100644 --- a/gio/ChangeLog +++ b/gio/ChangeLog @@ -1,3 +1,23 @@ +2007-12-09 A. Walton + + * 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 [gio compiles and links on win32, not sure how much already works] diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c index 121ff33..1849fbd 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 #GAppInfos. **/ GList * g_app_info_get_all (void) diff --git a/gio/gdrive.c b/gio/gdrive.c index 5d851e3..41e5171 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 #GVolumes on the given @drive. - * 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 7d09653..f81339c 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 99cdac0..f9a9cbc 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 #GFiles * * 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 I/O priority * 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 I/O priority * 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 I/O priority * 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 I/O priority * 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 I/O priority * 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 5872b8d..67dce7a 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 d9492be..31bb1e1 100644 --- a/gio/gfileattribute.c +++ b/gio/gfileattribute.c @@ -61,7 +61,7 @@ * * * - * GFileAttributes Namespaces + * GFileAttributes Default Namespaces * * NamspaceDescription * @@ -110,8 +110,12 @@ *
* * + * 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. + * + * * * * GFileAttributes Built-in Keys and Value Types diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c index 3b8b84b..7b96cd7 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 #GFiles, 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 #GFileInfos, 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 io priority * 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 #GFileInfos. **/ GList * g_file_enumerator_next_files_finish (GFileEnumerator *enumerator, @@ -366,9 +381,15 @@ close_async_callback_wrapper (GObject *source_object, * @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 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 df2d31b..194275d 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 13a8cf4..46484af 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. * * I/O priority * Each I/O operation has a priority, and the scheduler uses the priorities diff --git a/gio/gioscheduler.h b/gio/gioscheduler.h index c6da94d..30b5ec6 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 e1f8a43..16d9405 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 5274ab5..ca895b9 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 8444b25..85d33df 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 fcfc177..f827c81 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 0d9f828..b617c7e 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 b3f62eb..21dde27 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,