From 0c867d344461515213e6e04de9f072e43ea2e646 Mon Sep 17 00:00:00 2001 From: Andrew Walton Date: Thu, 29 Nov 2007 10:18:55 +0000 Subject: [PATCH] Fixes unknown meaning in GAppLaunchContext docs. Clarify asynchronous ops. * gappinfo.c: Fixes unknown meaning in GAppLaunchContext docs. * gfile.c: Clarify asynchronous ops. * gfileattribute.c: Fix entity tag docs. * gicon.c: * gthemedicon.c: Provides missing gtk-doc section, fixes API docs slighly. * gsimpleasyncresult.c: Fill in missing info in docs. * gunixinputstream.c: * gunixoutputstream.c: Be more expressive in short description. * gunixvolume.c: Remove gtk-doc stubs for non-public API. svn path=/trunk/; revision=5994 --- gio/ChangeLog | 19 ++++++++++ gio/gappinfo.c | 14 ++++--- gio/gfile.c | 81 ++++++++++++++++++++++++++++------------ gio/gfileattribute.c | 12 +++--- gio/gicon.c | 17 +++++++++ gio/gsimpleasyncresult.c | 12 ++++-- gio/gthemedicon.c | 7 +++- gio/gunixinputstream.c | 2 +- gio/gunixoutputstream.c | 2 +- gio/gunixvolume.c | 26 ------------- 10 files changed, 123 insertions(+), 69 deletions(-) diff --git a/gio/ChangeLog b/gio/ChangeLog index cc7162e99..b1f825df2 100644 --- a/gio/ChangeLog +++ b/gio/ChangeLog @@ -1,3 +1,22 @@ +2007-11-29 A. Walton,,, + + * gappinfo.c: + Fixes unknown meaning in GAppLaunchContext docs. + * gfile.c: + Clarify asynchronous ops. + * gfileattribute.c: + Fix entity tag docs. + * gicon.c: + * gthemedicon.c: + Provides missing gtk-doc section, fixes API docs slighly. + * gsimpleasyncresult.c: + Fill in missing info in docs. + * gunixinputstream.c: + * gunixoutputstream.c: + Be more expressive in short description. + * gunixvolume.c: + Remove gtk-doc stubs for non-public API. + 2007-11-28 Matthias Clasen * *.c: Coding style fixups diff --git a/gio/gappinfo.c b/gio/gappinfo.c index 70f3ec090..6b02a7780 100644 --- a/gio/gappinfo.c +++ b/gio/gappinfo.c @@ -522,11 +522,11 @@ g_app_launch_context_init (GAppLaunchContext *launch_context) * @info: a #GAppInfo. * @files: a #GList of files. * - * Gets the DISPLAY for a launched application. - * TODO: can't find an implementation. DISPLAY as in X atom "DISPLAY"? - * Environmental variable "DISPLAY"? + * Gets the display string for the display. This is used to ensure new + * applications are started on the same display as the launching + * application. * - * Returns: a display string. + * Returns: a display string for the display. **/ char * g_app_launch_context_get_display (GAppLaunchContext *context, @@ -558,7 +558,7 @@ g_app_launch_context_get_display (GAppLaunchContext *context, * Notifications standard, at * . * - * Returns: a startup notifaction ID for the application, or %NULL if + * Returns: a startup notification ID for the application, or %NULL if * not supported. **/ char * @@ -586,7 +586,9 @@ g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context, * @startup_notify_id: a string containing the DESKTOP_STARTUP_ID * of the launched application. * - * TODO: what does this do? Can't find it implemented anywhere. + * Called when an application has failed to launch, and cancels the + * application startup notification. + * **/ void g_app_launch_context_launch_failed (GAppLaunchContext *context, diff --git a/gio/gfile.c b/gio/gfile.c index bd4f6032d..e1f120800 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -46,7 +46,7 @@ * virtual file system. #GFiles are lightweight, immutable * objects that do no I/O upon creation. It is necessary to understand that * #GFile objects do not represent files, merely a handle to a file. All - * file I/O is implemented as streams (see #GInputStream and #GOutputStream). + * file I/O is implemented as streaming operations (see #GInputStream and #GOutputStream). * * To construct a #GFile, you can use: * g_file_new_for_path() if you have a path. @@ -58,12 +58,21 @@ * g_file_resolve_relative_path() to resolve a relative path between * two #GFiles. * - * Many #GFile operations have both synchronous (or blocking) and - * asynchronous (non-blocking) versions to suit your application. - * Asynchronous versions of synchronous functions simply have _async() - * appended to their function names. The asynchronous I/O functions - * call a #GAsyncReadyCallback which is then used to finalize the operation, - * which is then passed to the function's matching _finish() operation. + * Many #GFile operations have both synchronous and asynchronous versions + * to suit your application. Asynchronous versions of synchronous functions + * simply have _async() appended to their function names. The asynchronous + * I/O functions call a #GAsyncReadyCallback which is then used to finalize + * the operation, which is then passed to the function's matching _finish() + * operation. + * + * Some #GFile operations do not have synchronous analogs, as they may + * take a very long time to finish, and blocking may leave an application + * unusable. Notable cases include: + * g_file_mount_mountable() to mount a mountable file. + * g_file_unmount_mountable() to unmount a mountable file. + * g_file_eject_mountable() to eject a mountable file. + * + * **/ static void g_file_base_init (gpointer g_class); @@ -276,7 +285,7 @@ g_file_has_uri_scheme (GFile *file, * Returns: a string containing the URI scheme for the given * #GFile. The returned string should be freed with g_free() * when no longer needed. - **/ + **/ char * g_file_get_uri_scheme (GFile *file) { @@ -662,8 +671,8 @@ g_file_enumerate_children (GFile *file, * @flags: a set of #GFileQueryInfoFlags. * @io_priority: the io 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 gets a #GFileEnumerator for the children of @file that * match @attributes, where attributes is a #GFileAttributeInfo query @@ -789,8 +798,8 @@ g_file_query_info (GFile *file, * @flags: a set of #GFileQueryInfoFlags. * @io_priority: the io 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 * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation @@ -1223,10 +1232,12 @@ g_file_read_finish (GFile *file, * Readies a file for appending data asynchronously. * * For the synchronous version of this function, see g_file_append_to(). + * To finish this operation, see g_file_append_to_finish(). * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be set when + * g_file_append_to_finish() is called, and %NULL will be returned. **/ void g_file_append_to_async (GFile *file, @@ -1255,7 +1266,12 @@ g_file_append_to_async (GFile *file, * @res: #GAsyncResult * @error: a #GError, or %NULL * - * Finishes appending to a file started with g_file_append_to_async(). + * Finishes appending to a file. See g_file_append_to_async(). + * + * If @cancellable was not %NULL when g_file_append_to_async() was called, + * then the operation could have been be cancelled by triggering the cancellable + * object from another thread. If the operation was cancelled, the error + * %G_IO_ERROR_CANCELLED will be set in @error, and %NULL will be returned. * * Returns: a valid #GFileOutputStream or %NULL on error. **/ @@ -1292,10 +1308,12 @@ g_file_append_to_finish (GFile *file, * Creates a new file asynchronously. * * For the synchronous version of this function, see g_file_create(). + * To finish this operation, see g_file_create_finish(). * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL + * will be returned by g_file_create_finish(). **/ void g_file_create_async (GFile *file, @@ -1324,9 +1342,14 @@ g_file_create_async (GFile *file, * @res: a #GAsyncResult. * @error: a #GError, or %NULL * - * Finishes creating a file started with g_file_create_async(). + * Finishes creating a file. See g_file_create_async(). * - * Returns: a #GFileOutputStream. + * If @cancellable was not %NULL when g_file_create_async() was called, + * then the operation could have been be cancelled by triggering the cancellable + * object from another thread. If the operation was cancelled, the error + * %G_IO_ERROR_CANCELLED will be set in @error, and %NULL will be returned. + * + * Returns: a #GFileOutputStream or %NULL on error. **/ GFileOutputStream * g_file_create_finish (GFile *file, @@ -1364,10 +1387,12 @@ g_file_create_finish (GFile *file, * %TRUE, this function will attempt to make a backup of the current file. * * For the synchronous version of this function, see g_file_replace(). + * To finish this operation, see g_file_replace_finish(). * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and + * %NULL will be returned in g_file_replace_finish(). **/ void g_file_replace_async (GFile *file, @@ -1400,9 +1425,12 @@ g_file_replace_async (GFile *file, * @res: a #GAsyncResult. * @error: a #GError, or %NULL * - * Finishes replacing the contents of the file started by - * g_file_replace_async(). This is typically called within - * a #GAsyncReadyCallback. + * Finishes replacing the contents of the file. See g_file_replace_async(). + * + * If @cancellable was not %NULL when g_file_replace_async() was called, + * then the operation could have been be cancelled by triggering the cancellable + * object from another thread. If the operation was cancelled, the error + * %G_IO_ERROR_CANCELLED will be set in @error, and %NULL will be returned. * * Returns: a #GFileOutputStream, or %NULL if an error has occured. **/ @@ -2892,6 +2920,8 @@ g_file_mount_mountable (GFile *file, * @file: input #GFile. * @result: a #GAsyncResult. * @error: a #GError, or %NULL + * + * Finishes a mount operation. See g_file_mount_mountable() for details. * * Finish an asynchronous mount operation that was started * with g_file_mount_mountable(). @@ -2925,6 +2955,8 @@ g_file_mount_mountable_finish (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. * @user_data: a #gpointer. + * + * Starts an asynchronous unmount operation. * * Unmounts a mounted file. * @@ -2963,6 +2995,8 @@ g_file_unmount_mountable (GFile *file, * @file: input #GFile. * @result: a #GAsyncResult. * @error: a #GError, or %NULL + * + * Finishes an unmount operation, see g_file_unmount_mountable() for details. * * Finish an asynchronous unmount operation that was started * with g_file_unmount_mountable(). @@ -4616,8 +4650,9 @@ g_file_replace_contents_async (GFile *file, * @new_etag: a location of a new entity tag for the document. * @error: a #GError, or %NULL * - * Finishes an asynchronous replace of the given @file. Sets - * @new_etag to the new entity tag for the document, if present. + * Finishes an asynchronous replace of the given @file. See + * g_file_replace_contents_async(). Sets @new_etag to the new entity + * tag for the document, if present. * * Returns: %TRUE on success, %FALSE on failure. **/ diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c index f6f4230af..d11b25bfb 100644 --- a/gio/gfileattribute.c +++ b/gio/gfileattribute.c @@ -69,12 +69,12 @@ * "std"The "Standard" namespace. General file * information that any application may need should be put in this namespace. Examples * include the file's name, type, and size. - * "etag"The "Entity Tag" namespace. Remotely shared - * files, like those on HTTP/1.1 file systems, use "entity tags" to quickly determine - * if a file has been modified. Entity tags are globally unique, and should - * always be sent with the current revision of a file. An example of a key - * in this namespace is "value", which contains the value of the current - * entity tag. + * "etag"The "Entity Tag" namespace. + * GIO use "entity tags" to quickly determine if a file has been modified + * from the version on the file system. Entity tags are globally unique identifiers, + * and should always be sent with the current revision of a file. + * An example of a key in this namespace is "value", which contains the value of the + * current entity tag. * "id"The "Identification" namespace. This * namespace is used by file managers and applications that list directories * to check for loops and to uniquely identify files. diff --git a/gio/gicon.c b/gio/gicon.c index a6631a189..5a2f39080 100644 --- a/gio/gicon.c +++ b/gio/gicon.c @@ -27,6 +27,23 @@ #include "gioalias.h" +/** + * SECTION:gicon + * @short_description: base class for icons + * + * #GIcon is a base class for implementing more complex icon classes. It + * contains a very minimal interface for checking the equality of two icons + * and hashing of icons. + * + * #GIcon does not provide the actual pixmap for the icon as this is out + * of gio's scope, however implementations of #GIcon may contain the name + * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon). + * + * To obtain a hash of a #GIcon, see g_icon_hash(). + * + * To check if two #GIcons are equal, see g_icon_equal(). + **/ + static void g_icon_base_init (gpointer g_class); static void g_icon_class_init (gpointer g_class, gpointer class_data); diff --git a/gio/gsimpleasyncresult.c b/gio/gsimpleasyncresult.c index d3c932761..fbb4615d4 100644 --- a/gio/gsimpleasyncresult.c +++ b/gio/gsimpleasyncresult.c @@ -61,6 +61,10 @@ * need better control of how asynchronous operations are completed, it is * important to understand this functionality. * + * GSimpleAsyncResults are tagged with the calling function to ensure that + * asynchronous functions and their finishing functions are used together + * correctly. + * * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). If * the result needs to be created for a #GError, use * g_simple_async_result_new_from_error(). If a #GError is not available (e.g. @@ -167,10 +171,10 @@ g_simple_async_result_init (GSimpleAsyncResult *simple) /** * g_simple_async_result_new: - * @source_object: a #GObject. + * @source_object: a #GObject the asynchronous function was called with. * @callback: a #GAsyncReadyCallback. * @user_data: user data passed to @callback. - * @source_tag: + * @source_tag: the asynchronous function. * * Creates a #GSimpleAsyncResult. * @@ -323,7 +327,7 @@ g_simple_async_result_get_source_tag (GSimpleAsyncResult *simple) * @simple: a #GSimpleAsyncResult. * @dest: a location to propegate the error to. * - * Propegates an error from within the simple asynchronous result to + * Propagates an error from within the simple asynchronous result to * a given destination. * * Returns: %TRUE if the error was propegated to @dest. %FALSE otherwise. @@ -645,7 +649,7 @@ g_simple_async_result_run_in_thread (GSimpleAsyncResult *simple, /** * g_simple_async_report_error_in_idle: - * @object: + * @object: a #GObject. * @callback: a #GAsyncReadyCallback. * @user_data: user data passed to @callback. * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR). diff --git a/gio/gthemedicon.c b/gio/gthemedicon.c index 14b0ad052..d5f75c0bb 100644 --- a/gio/gthemedicon.c +++ b/gio/gthemedicon.c @@ -28,10 +28,13 @@ /** * SECTION:gthemedicon - * @short_description: Themed Icons + * @short_description: icon theming support * @see_also: #GIcon, #GLoadableIcon * - * #GThemedIcon is an implementation of #GIcon for themed icons. + * #GThemedIcon is an implementation of #GIcon that supports icon themes. + * #GThemedIcon contains a list of all of the icons present in an icon + * theme, so that icons can be looked up quickly. #GThemedIcon does + * not provide actual pixmaps for icons, just the icon names. **/ static void g_themed_icon_icon_iface_init (GIconIface *iface); diff --git a/gio/gunixinputstream.c b/gio/gunixinputstream.c index c215a07f9..61b77518a 100644 --- a/gio/gunixinputstream.c +++ b/gio/gunixinputstream.c @@ -43,7 +43,7 @@ /** * SECTION:gunixinputstream - * @short_description: Unix Input Stream + * @short_description: streaming input operations for Unix file descriptors * @see_also: #GInputStream * * #GUnixInputStream implements #GInputStream for reading from a diff --git a/gio/gunixoutputstream.c b/gio/gunixoutputstream.c index a48514c07..88048820e 100644 --- a/gio/gunixoutputstream.c +++ b/gio/gunixoutputstream.c @@ -43,7 +43,7 @@ /** * SECTION:gunixoutputstream - * @short_description: Unix Output Stream + * @short_description: streaming output operations for Unix file descriptors * @see_also: #GOutputStream * * #GUnixOutputStream implements #GOutputStream for writing to a a diff --git a/gio/gunixvolume.c b/gio/gunixvolume.c index 91e7659f7..7d8576a2e 100644 --- a/gio/gunixvolume.c +++ b/gio/gunixvolume.c @@ -130,14 +130,6 @@ type_to_icon (GUnixMountType type) return g_strdup (icon_name); } -/** - * g_unix_volume_new: - * @mount: - * @drive: - * - * Returns: a #GUnixVolume. - * - **/ GUnixVolume * _g_unix_volume_new (GUnixMount *mount, GUnixDrive *drive) @@ -189,11 +181,6 @@ _g_unix_volume_new (GUnixMount *mount, return volume; } -/** - * g_unix_volume_unmounted: - * @volume: - * - **/ void _g_unix_volume_unmounted (GUnixVolume *volume) { @@ -205,12 +192,6 @@ _g_unix_volume_unmounted (GUnixVolume *volume) } } -/** - * g_unix_volume_unset_drive: - * @volume: - * @drive: - * - **/ void _g_unix_volume_unset_drive (GUnixVolume *volume, GUnixDrive *drive) @@ -247,13 +228,6 @@ g_unix_volume_get_name (GVolume *volume) return g_strdup (unix_volume->name); } -/** - * g_unix_volume_has_mountpoint: - * @volume: - * @mountpoint: - * - * Returns: - **/ gboolean _g_unix_volume_has_mountpoint (GUnixVolume *volume, const char *mountpoint)