luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 15:06:14 +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>
* *.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.
* @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
* <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.
**/
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,

81
gio/gfile.c
View File

@ -46,7 +46,7 @@
* virtual file system. #GFile<!-- -->s 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 #GFile<!-- -->s.
*
* 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.
**/

12
gio/gfileattribute.c
View File

@ -69,12 +69,12 @@
* <row><entry>"std"</entry><entry>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.</entry></row>
* <row><entry>"etag"</entry><entry>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.</entry></row>
* <row><entry>"etag"</entry><entry>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.</entry></row>
* <row><entry>"id"</entry><entry>The "Identification" namespace. This
* namespace is used by file managers and applications that list directories
* to check for loops and to uniquely identify files.</entry></row>

17
gio/gicon.c
View File

@ -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);

12
gio/gsimpleasyncresult.c
View File

@ -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).

7
gio/gthemedicon.c
View File

@ -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);

2
gio/gunixinputstream.c
View File

@ -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

2
gio/gunixoutputstream.c
View File

@ -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

26
gio/gunixvolume.c
View File

@ -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)