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

diff --git a/gio/ChangeLog b/gio/ChangeLog
index cc7162e..b1f825d 100644 (file)
--- a/gio/ChangeLog
+++ b/gio/ChangeLog
@@ -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

diff --git a/gio/gappinfo.c b/gio/gappinfo.c
index 70f3ec0..6b02a77 100644 (file)
--- 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 
  * <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,

diff --git a/gio/gfile.c b/gio/gfile.c
index bd4f603..e1f1208 100644 (file)
--- a/gio/gfile.c
+++ b/gio/gfile.c
@@ -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.
  **/

diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c
index f6f4230..d11b25b 100644 (file)
--- a/gio/gfileattribute.c
+++ b/gio/gfileattribute.c
@@ -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>

diff --git a/gio/gicon.c b/gio/gicon.c
index a6631a1..5a2f390 100644 (file)
--- 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 d3c9327..fbb4615 100644 (file)
--- 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 14b0ad0..d5f75c0 100644 (file)
--- 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 c215a07..61b7751 100644 (file)
--- 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 a48514c..8804882 100644 (file)
--- 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 91e7659..7d8576a 100644 (file)
--- 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)