luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-13 07:56:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Fixes unknown meaning in GAppLaunchContext docs. Clarify asynchronous ops.

Browse Source 
* 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
This commit is contained in:
Andrew Walton 2007-11-29 10:18:55 +00:00
parent 09471fec46
commit 0c867d3444
10 changed files with 123 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
gio/ChangeLog
View File

@ -1,3 +1,22 @@
2007-11-29 A. Walton,,, <anwalt01@ganyemede>
* 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 <mclasen@redhat.com> 2007-11-28 Matthias Clasen <mclasen@redhat.com>
* *.c: Coding style fixups * *.c: Coding style fixups

14
gio/gappinfo.c
View File

@ -522,11 +522,11 @@ g_app_launch_context_init (GAppLaunchContext *launch_context)
* @info: a #GAppInfo. * @info: a #GAppInfo.
* @files: a #GList of files. * @files: a #GList of files.
* *
* Gets the DISPLAY for a launched application. * Gets the display string for the display. This is used to ensure new
* TODO: can't find an implementation. DISPLAY as in X atom "DISPLAY"? * applications are started on the same display as the launching
* Environmental variable "DISPLAY"? * application.
* *
* Returns: a display string. * Returns: a display string for the display.
**/ **/
char * char *
g_app_launch_context_get_display (GAppLaunchContext *context, g_app_launch_context_get_display (GAppLaunchContext *context,
@ -558,7 +558,7 @@ g_app_launch_context_get_display (GAppLaunchContext *context,
* Notifications standard, at * Notifications standard, at
* <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"/>. * <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"/>.
* *
* Returns: a startup notifaction ID for the application, or %NULL if * Returns: a startup notification ID for the application, or %NULL if
* not supported. * not supported.
**/ **/
char * 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 * @startup_notify_id: a string containing the DESKTOP_STARTUP_ID
* of the launched application. * 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 void
g_app_launch_context_launch_failed (GAppLaunchContext *context, g_app_launch_context_launch_failed (GAppLaunchContext *context,

81
gio/gfile.c
View File

@ -46,7 +46,7 @@
* virtual file system. #GFile<!-- -->s are lightweight, immutable * virtual file system. #GFile<!-- -->s are lightweight, immutable
* objects that do no I/O upon creation. It is necessary to understand that * 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 * #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: * To construct a #GFile, you can use:
* g_file_new_for_path() if you have a path. * 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 * g_file_resolve_relative_path() to resolve a relative path between
* two #GFile<!-- -->s. * two #GFile<!-- -->s.
* *
* Many #GFile operations have both synchronous (or blocking) and * Many #GFile operations have both synchronous and asynchronous versions
* asynchronous (non-blocking) versions to suit your application. * to suit your application. Asynchronous versions of synchronous functions
* Asynchronous versions of synchronous functions simply have _async() * simply have _async() appended to their function names. The asynchronous
* appended to their function names. The asynchronous I/O functions * I/O functions call a #GAsyncReadyCallback which is then used to finalize
* call a #GAsyncReadyCallback which is then used to finalize the operation, * the operation, which is then passed to the function's matching _finish()
* which is then passed to the function's matching _finish() operation. * 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); 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 * Returns: a string containing the URI scheme for the given
* #GFile. The returned string should be freed with g_free() * #GFile. The returned string should be freed with g_free()
* when no longer needed. * when no longer needed.
**/ **/
char * char *
g_file_get_uri_scheme (GFile *file) g_file_get_uri_scheme (GFile *file)
{ {
@ -662,8 +671,8 @@ g_file_enumerate_children (GFile *file,
* @flags: a set of #GFileQueryInfoFlags. * @flags: a set of #GFileQueryInfoFlags.
* @io_priority: the io priority of the request. * @io_priority: the io priority of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore. * @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback. * @callback: a #GAsyncReadyCallback to call when the request is satisfied
* @user_data: a #gpointer. * @user_data: the data to pass to callback function
* *
* Asynchronously gets a #GFileEnumerator for the children of @file that * Asynchronously gets a #GFileEnumerator for the children of @file that
* match @attributes, where attributes is a #GFileAttributeInfo query * match @attributes, where attributes is a #GFileAttributeInfo query
@ -789,8 +798,8 @@ g_file_query_info (GFile *file,
* @flags: a set of #GFileQueryInfoFlags. * @flags: a set of #GFileQueryInfoFlags.
* @io_priority: the io priority of the request. * @io_priority: the io priority of the request.
* @cancellable: optional #GCancellable object, %NULL to ignore. * @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback. * @callback: a #GAsyncReadyCallback to call when the request is satisfied
* @user_data: a #gpointer. * @user_data: the data to pass to callback function
* *
* If @cancellable is not %NULL, then the operation can be cancelled by * If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation * 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. * Readies a file for appending data asynchronously.
* *
* For the synchronous version of this function, see g_file_append_to(). * 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 * If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation * 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 void
g_file_append_to_async (GFile *file, g_file_append_to_async (GFile *file,
@ -1255,7 +1266,12 @@ g_file_append_to_async (GFile *file,
* @res: #GAsyncResult * @res: #GAsyncResult
* @error: a #GError, or %NULL * @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. * Returns: a valid #GFileOutputStream or %NULL on error.
**/ **/
@ -1292,10 +1308,12 @@ g_file_append_to_finish (GFile *file,
* Creates a new file asynchronously. * Creates a new file asynchronously.
* *
* For the synchronous version of this function, see g_file_create(). * 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 * If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation * 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 void
g_file_create_async (GFile *file, g_file_create_async (GFile *file,
@ -1324,9 +1342,14 @@ g_file_create_async (GFile *file,
* @res: a #GAsyncResult. * @res: a #GAsyncResult.
* @error: a #GError, or %NULL * @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 * GFileOutputStream *
g_file_create_finish (GFile *file, 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. * %TRUE, this function will attempt to make a backup of the current file.
* *
* For the synchronous version of this function, see g_file_replace(). * 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 * If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation * 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 void
g_file_replace_async (GFile *file, g_file_replace_async (GFile *file,
@ -1400,9 +1425,12 @@ g_file_replace_async (GFile *file,
* @res: a #GAsyncResult. * @res: a #GAsyncResult.
* @error: a #GError, or %NULL * @error: a #GError, or %NULL
* *
* Finishes replacing the contents of the file started by * Finishes replacing the contents of the file. See g_file_replace_async().
* g_file_replace_async(). This is typically called within *
* a #GAsyncReadyCallback. * 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. * Returns: a #GFileOutputStream, or %NULL if an error has occured.
**/ **/
@ -2892,6 +2920,8 @@ g_file_mount_mountable (GFile *file,
* @file: input #GFile. * @file: input #GFile.
* @result: a #GAsyncResult. * @result: a #GAsyncResult.
* @error: a #GError, or %NULL * @error: a #GError, or %NULL
*
* Finishes a mount operation. See g_file_mount_mountable() for details.
* *
* Finish an asynchronous mount operation that was started * Finish an asynchronous mount operation that was started
* with g_file_mount_mountable(). * with g_file_mount_mountable().
@ -2925,6 +2955,8 @@ g_file_mount_mountable_finish (GFile *file,
* @cancellable: optional #GCancellable object, %NULL to ignore. * @cancellable: optional #GCancellable object, %NULL to ignore.
* @callback: a #GAsyncReadyCallback. * @callback: a #GAsyncReadyCallback.
* @user_data: a #gpointer. * @user_data: a #gpointer.
*
* Starts an asynchronous unmount operation.
* *
* Unmounts a mounted file. * Unmounts a mounted file.
* *
@ -2963,6 +2995,8 @@ g_file_unmount_mountable (GFile *file,
* @file: input #GFile. * @file: input #GFile.
* @result: a #GAsyncResult. * @result: a #GAsyncResult.
* @error: a #GError, or %NULL * @error: a #GError, or %NULL
*
* Finishes an unmount operation, see g_file_unmount_mountable() for details.
* *
* Finish an asynchronous unmount operation that was started * Finish an asynchronous unmount operation that was started
* with g_file_unmount_mountable(). * 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. * @new_etag: a location of a new entity tag for the document.
* @error: a #GError, or %NULL * @error: a #GError, or %NULL
* *
* Finishes an asynchronous replace of the given @file. Sets * Finishes an asynchronous replace of the given @file. See
* @new_etag to the new entity tag for the document, if present. * 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. * Returns: %TRUE on success, %FALSE on failure.
**/ **/

12
gio/gfileattribute.c
View File

@ -69,12 +69,12 @@
* <row><entry>"std"</entry><entry>The "Standard" namespace. General file * <row><entry>"std"</entry><entry>The "Standard" namespace. General file
* information that any application may need should be put in this namespace. Examples * information that any application may need should be put in this namespace. Examples
* include the file's name, type, and size.</entry></row> * include the file's name, type, and size.</entry></row>
* <row><entry>"etag"</entry><entry>The "Entity Tag" namespace. Remotely shared * <row><entry>"etag"</entry><entry>The "Entity Tag" namespace.
* files, like those on HTTP/1.1 file systems, use "entity tags" to quickly determine * GIO use "entity tags" to quickly determine if a file has been modified
* if a file has been modified. Entity tags are globally unique, and should * from the version on the file system. Entity tags are globally unique identifiers,
* always be sent with the current revision of a file. An example of a key * and should always be sent with the current revision of a file.
* in this namespace is "value", which contains the value of the current * An example of a key in this namespace is "value", which contains the value of the
* entity tag.</entry></row> * current entity tag.</entry></row>
* <row><entry>"id"</entry><entry>The "Identification" namespace. This * <row><entry>"id"</entry><entry>The "Identification" namespace. This
* namespace is used by file managers and applications that list directories * namespace is used by file managers and applications that list directories
* to check for loops and to uniquely identify files.</entry></row> * to check for loops and to uniquely identify files.</entry></row>

17
gio/gicon.c
View File

@ -27,6 +27,23 @@
#include "gioalias.h" #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_base_init (gpointer g_class);
static void g_icon_class_init (gpointer g_class, static void g_icon_class_init (gpointer g_class,
gpointer class_data); gpointer class_data);

12
gio/gsimpleasyncresult.c
View File

@ -61,6 +61,10 @@
* need better control of how asynchronous operations are completed, it is * need better control of how asynchronous operations are completed, it is
* important to understand this functionality. * 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 * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). If
* the result needs to be created for a #GError, use * 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. * 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: * g_simple_async_result_new:
* @source_object: a #GObject. * @source_object: a #GObject the asynchronous function was called with.
* @callback: a #GAsyncReadyCallback. * @callback: a #GAsyncReadyCallback.
* @user_data: user data passed to @callback. * @user_data: user data passed to @callback.
* @source_tag: * @source_tag: the asynchronous function.
* *
* Creates a #GSimpleAsyncResult. * Creates a #GSimpleAsyncResult.
* *
@ -323,7 +327,7 @@ g_simple_async_result_get_source_tag (GSimpleAsyncResult *simple)
* @simple: a #GSimpleAsyncResult. * @simple: a #GSimpleAsyncResult.
* @dest: a location to propegate the error to. * @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. * a given destination.
* *
* Returns: %TRUE if the error was propegated to @dest. %FALSE otherwise. * 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: * g_simple_async_report_error_in_idle:
* @object: * @object: a #GObject.
* @callback: a #GAsyncReadyCallback. * @callback: a #GAsyncReadyCallback.
* @user_data: user data passed to @callback. * @user_data: user data passed to @callback.
* @domain: a #GQuark containing the error domain (usually #G_IO_ERROR). * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR).

7
gio/gthemedicon.c
View File

@ -28,10 +28,13 @@
/** /**
* SECTION:gthemedicon * SECTION:gthemedicon
* @short_description: Themed Icons * @short_description: icon theming support
* @see_also: #GIcon, #GLoadableIcon * @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); static void g_themed_icon_icon_iface_init (GIconIface *iface);

2
gio/gunixinputstream.c
View File

@ -43,7 +43,7 @@
/** /**
* SECTION:gunixinputstream * SECTION:gunixinputstream
* @short_description: Unix Input Stream * @short_description: streaming input operations for Unix file descriptors
* @see_also: #GInputStream * @see_also: #GInputStream
* *
* #GUnixInputStream implements #GInputStream for reading from a * #GUnixInputStream implements #GInputStream for reading from a

2
gio/gunixoutputstream.c
View File

@ -43,7 +43,7 @@
/** /**
* SECTION:gunixoutputstream * SECTION:gunixoutputstream
* @short_description: Unix Output Stream * @short_description: streaming output operations for Unix file descriptors
* @see_also: #GOutputStream * @see_also: #GOutputStream
* *
* #GUnixOutputStream implements #GOutputStream for writing to a a * #GUnixOutputStream implements #GOutputStream for writing to a a

26
gio/gunixvolume.c
View File

@ -130,14 +130,6 @@ type_to_icon (GUnixMountType type)
return g_strdup (icon_name); return g_strdup (icon_name);
} }
/**
* g_unix_volume_new:
* @mount:
* @drive:
*
* Returns: a #GUnixVolume.
*
**/
GUnixVolume * GUnixVolume *
_g_unix_volume_new (GUnixMount *mount, _g_unix_volume_new (GUnixMount *mount,
GUnixDrive *drive) GUnixDrive *drive)
@ -189,11 +181,6 @@ _g_unix_volume_new (GUnixMount *mount,
return volume; return volume;
} }
/**
* g_unix_volume_unmounted:
* @volume:
*
**/
void void
_g_unix_volume_unmounted (GUnixVolume *volume) _g_unix_volume_unmounted (GUnixVolume *volume)
{ {
@ -205,12 +192,6 @@ _g_unix_volume_unmounted (GUnixVolume *volume)
} }
} }
/**
* g_unix_volume_unset_drive:
* @volume:
* @drive:
*
**/
void void
_g_unix_volume_unset_drive (GUnixVolume *volume, _g_unix_volume_unset_drive (GUnixVolume *volume,
GUnixDrive *drive) GUnixDrive *drive)
@ -247,13 +228,6 @@ g_unix_volume_get_name (GVolume *volume)
return g_strdup (unix_volume->name); return g_strdup (unix_volume->name);
} }
/**
* g_unix_volume_has_mountpoint:
* @volume:
* @mountpoint:
*
* Returns:
**/
gboolean gboolean
_g_unix_volume_has_mountpoint (GUnixVolume *volume, _g_unix_volume_has_mountpoint (GUnixVolume *volume,
const char *mountpoint) const char *mountpoint)