Documentation updates

svn path=/trunk/; revision=6336

gio/ChangeLog

@@ -1,3 +1,12 @@
+2008-01-20  Matthias Clasen  <mclasen@redhat.com>
+
+	* gfile.c:
+	* gfilemonitor.[hc]:
+	* gmemoryinputstream.c:
+	* gmemoryoutputstream.c:
+	* gmountoperation.c:
+	* gthemedicon.c: Documentation updates
+
 2008-01-20  Murray Cumming  <murrayc@murrayc.com>
 
 	* gfile.c: documentation: Fixed more minor 

gio/gfile.c

@@ -1108,7 +1108,23 @@ g_file_find_enclosing_mount (GFile         *file,
   
   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 @@ g_file_find_enclosing_mount_async (GFile              *file,
 					 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;
   

gio/gfilemonitor.c

@@ -519,10 +519,10 @@ update_rate_limiter_timeout (GFileMonitor *monitor,
  * 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;

gio/gfilemonitor.h

@@ -109,7 +109,7 @@ void     g_file_monitor_set_rate_limit (GFileMonitor *monitor,
 
 /* For implementations */
 void g_file_monitor_emit_event (GFileMonitor      *monitor,
-				GFile             *file,
+				GFile             *child,
 				GFile             *other_file,
 				GFileMonitorEvent  event_type);
 

gio/gmemoryinputstream.c

@@ -185,6 +185,13 @@ g_memory_input_stream_init (GMemoryInputStream *stream)
                                               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 @@ g_memory_input_stream_new_from_data (const void     *data,
   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,

gio/gmemoryoutputstream.h

@@ -69,6 +69,18 @@ struct _GMemoryOutputStreamClass
   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;

gio/gmountoperation.c

@@ -620,8 +620,8 @@ g_mount_operation_set_choice (GMountOperation *op,
 
 /**
  * g_mount_operation_reply:
- * @op: a #GMountOperation.
- * @abort: boolean.
+ * @op: a #GMountOperation
+ * @result: a #GMountOperationResult
  * 
  * Emits the #GMountOperation::reply signal.
  **/

gio/gthemedicon.c

@@ -143,6 +143,28 @@ g_themed_icon_new_from_names (char **iconnames,
   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)
 {