glib r6336 - in trunk: docs/reference docs/reference/gio gio

[matthiasc svn gnome org]

Author: matthiasc
Date: Mon Jan 21 03:49:20 2008
New Revision: 6336
URL: http://svn.gnome.org/viewvc/glib?rev=6336&view=rev

Log:
Documentation updates


Modified:
   trunk/docs/reference/ChangeLog
   trunk/docs/reference/gio/gio-sections.txt
   trunk/gio/ChangeLog
   trunk/gio/gfile.c
   trunk/gio/gfilemonitor.c
   trunk/gio/gfilemonitor.h
   trunk/gio/gmemoryinputstream.c
   trunk/gio/gmemoryoutputstream.h
   trunk/gio/gmountoperation.c
   trunk/gio/gthemedicon.c

Modified: trunk/docs/reference/gio/gio-sections.txt
==============================================================================
--- trunk/docs/reference/gio/gio-sections.txt	(original)
+++ trunk/docs/reference/gio/gio-sections.txt	Mon Jan 21 03:49:20 2008
@@ -67,8 +67,11 @@
 g_file_query_info
 g_file_query_info_async
 g_file_query_info_finish
+g_file_query_exists
 g_file_query_filesystem_info
 g_file_find_enclosing_mount
+g_file_find_enclosing_mount_async
+g_file_find_enclosing_mount_finish
 g_file_enumerate_children
 g_file_enumerate_children_async
 g_file_enumerate_children_finish
@@ -349,6 +352,7 @@
 GThemedIcon
 g_themed_icon_new
 g_themed_icon_new_from_names
+g_themed_icon_new_with_default_fallbacks
 <SUBSECTION Standard>
 GThemedIconClass
 G_THEMED_ICON
@@ -672,6 +676,7 @@
 <SECTION>
 <FILE>gmemoryoutputstream</FILE>
 <TITLE>GMemoryOutputStream</TITLE>
+GReallocFunc
 GMemoryOutputStream
 g_memory_output_stream_new
 g_memory_output_stream_get_data
@@ -1030,6 +1035,7 @@
 GAskPasswordFlags
 GPasswordSave
 GMountOperation
+GMountOperationResult
 g_mount_operation_new
 g_mount_operation_get_username
 g_mount_operation_set_username
@@ -1094,6 +1100,7 @@
 g_unix_mount_guess_icon
 g_unix_mount_guess_name
 g_unix_mount_guess_can_eject
+g_unix_mount_guess_should_display
 g_unix_mount_point_free
 g_unix_mount_point_compare
 g_unix_mount_point_get_mount_path

Modified: trunk/gio/gfile.c
==============================================================================
--- trunk/gio/gfile.c	(original)
+++ trunk/gio/gfile.c	Mon Jan 21 03:49:20 2008
@@ -1108,7 +1108,23 @@
   
   return (* iface->find_enclosing_mount) (file, cancellable, error);
 }
-
+/**
+ * g_file_find_enclosing_mount_async:
+ * @file: a #GFile
+ * @io_priority: the <link linkend="io-priority">I/O priority</link> 
+ *     of the request.
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
+ *
+ * Asynchronously gets the mount for the file.
+ *
+ * For more details, see g_file_find_enclosing_mount() which is
+ * the synchronous version of this call.
+ *
+ * When the operation is finished, @callback will be called. You can then call
+ * g_file_find_enclosing_mount_finish() to get the result of the operation.
+ */
 void
 g_file_find_enclosing_mount_async (GFile              *file,
 				   int                   io_priority,
@@ -1128,10 +1144,21 @@
 					 user_data);
 }
 
+/**
+ * g_file_find_enclosing_mount_finish:
+ * @file: a #GFile
+ * @res: a #GAsyncResult
+ * @error: a #GError
+ * 
+ * Finishes an asynchronous find mount request. 
+ * See g_file_find_enclosing_mount_async().
+ * 
+ * Returns: #GMount for given @file or %NULL on error.
+ **/
 GMount *
-g_file_find_enclosing_mount_finish (GFile              *file,
-				    GAsyncResult         *res,
-				    GError            **error)
+g_file_find_enclosing_mount_finish (GFile         *file,
+				    GAsyncResult  *res,
+				    GError       **error)
 {
   GFileIface *iface;
   

Modified: trunk/gio/gfilemonitor.c
==============================================================================
--- trunk/gio/gfilemonitor.c	(original)
+++ trunk/gio/gfilemonitor.c	Mon Jan 21 03:49:20 2008
@@ -519,10 +519,10 @@
  * implementations only.
  **/
 void
-g_file_monitor_emit_event (GFileMonitor *monitor,
-			   GFile *child,
-			   GFile *other_file,
-			   GFileMonitorEvent event_type)
+g_file_monitor_emit_event (GFileMonitor      *monitor,
+			   GFile             *child,
+			   GFile             *other_file,
+			   GFileMonitorEvent  event_type)
 {
   guint32 time_now, since_last;
   gboolean emit_now;

Modified: trunk/gio/gfilemonitor.h
==============================================================================
--- trunk/gio/gfilemonitor.h	(original)
+++ trunk/gio/gfilemonitor.h	Mon Jan 21 03:49:20 2008
@@ -109,7 +109,7 @@
 
 /* For implementations */
 void g_file_monitor_emit_event (GFileMonitor      *monitor,
-				GFile             *file,
+				GFile             *child,
 				GFile             *other_file,
 				GFileMonitorEvent  event_type);
 

Modified: trunk/gio/gmemoryinputstream.c
==============================================================================
--- trunk/gio/gmemoryinputstream.c	(original)
+++ trunk/gio/gmemoryinputstream.c	Mon Jan 21 03:49:20 2008
@@ -185,6 +185,13 @@
                                               GMemoryInputStreamPrivate);
 }
 
+/**
+ * g_memory_input_stream_new:
+ *
+ * Creates a new empty #GMemoryInputStream. 
+ *
+ * Returns: a new #GInputStream
+ */
 GInputStream *
 g_memory_input_stream_new (void)
 {
@@ -220,6 +227,15 @@
   return stream;
 }
 
+/**
+ * g_memory_input_stream_add_data:
+ * @stream: a #GMemoryInputStream
+ * @data: input data
+ * @len: length of the data, may be -1 if @data is a nul-terminated string
+ * @destroy: function that is called to free @data, or %NULL
+ *
+ * Appends @data to data that can be read from the input stream
+ */
 void
 g_memory_input_stream_add_data (GMemoryInputStream *stream,
                                 const void         *data,

Modified: trunk/gio/gmemoryoutputstream.h
==============================================================================
--- trunk/gio/gmemoryoutputstream.h	(original)
+++ trunk/gio/gmemoryoutputstream.h	Mon Jan 21 03:49:20 2008
@@ -69,6 +69,18 @@
   void (*_g_reserved5) (void);
 };
 
+/**
+ * GReallocFunc:
+ * @data: memory block to reallocate
+ * @size: size to reallocate @data to
+ *
+ * Changes the size of the memory block pointed to by @data to
+ * @size bytes. 
+ *
+ * The function should have the same semantics as realloc().
+ *
+ * Returns: a pointer to the reallocated memory
+ */
 typedef gpointer (*GReallocFunc) (gpointer data, gsize size);
 
 GType          g_memory_output_stream_get_type (void) G_GNUC_CONST;

Modified: trunk/gio/gmountoperation.c
==============================================================================
--- trunk/gio/gmountoperation.c	(original)
+++ trunk/gio/gmountoperation.c	Mon Jan 21 03:49:20 2008
@@ -620,8 +620,8 @@
 
 /**
  * g_mount_operation_reply:
- * @op: a #GMountOperation.
- * @abort: boolean.
+ * @op: a #GMountOperation
+ * @result: a #GMountOperationResult
  * 
  * Emits the #GMountOperation::reply signal.
  **/

Modified: trunk/gio/gthemedicon.c
==============================================================================
--- trunk/gio/gthemedicon.c	(original)
+++ trunk/gio/gthemedicon.c	Mon Jan 21 03:49:20 2008
@@ -143,6 +143,28 @@
   return G_ICON (themed);
 }
 
+/**
+ * g_themed_icon_new_with_default_fallbacks:
+ * @iconname: a string containing an icon name
+ *
+ * Creates a new themed icon for @iconname, and all the names
+ * that can be created by shortening @iconname at '-' characters.
+ * 
+ * In the following example, @icon1 and @icon2 are equivalent:
+ * |[
+ * const char *names[] = { 
+ *   "gnome-dev-cdrom-audio",
+ *   "gnome-dev-cdrom",
+ *   "gnome-dev",
+ *   "gnome"
+ * };
+ *
+ * icon1 = g_themed_icon_new_from_names (names, 4);
+ * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");
+ * ]|
+ *
+ * Returns: a new #GThemedIcon.
+ */
 GIcon *
 g_themed_icon_new_with_default_fallbacks (const char *iconname)
 {