Clean up some docs

svn path=/trunk/; revision=5966

gio/ChangeLog

@@ -1,3 +1,20 @@
+2007-11-27  Matthias Clasen  <mclasen@redhat.com>
+
+	* gpollfilemonitor.c:
+	* gunixmounts.c:
+	* gvfs.c:
+	* gfile.c:
+	* gdesktopappinfo.c:
+	* gwin32appinfo.c:
+	* gvolume.c:
+	* glocalvfs.c:
+	* gvolumemonitor.c:
+	* gdatainputstream.c:
+	* gdatainputstream.h:
+	* gdataoutputstream.c:
+	* gdataoutputstream.h:
+	* gfileinfo.h: Doc cleanups
+
 2007-11-28  Andre Klapper  <a9016009@gmx.de>
 
 	* gdesktopappinfo.c: Fix a typo.

gio/gdatainputstream.c

@@ -170,7 +170,7 @@ g_data_input_stream_set_byte_order (GDataInputStream *stream,
  * 
  * Gets the byte order for the data input stream.
  * 
- * Returns the @stream's current #GDataStreamByteOrder. 
+ * Returns: the @stream's current #GDataStreamByteOrder. 
  **/
 GDataStreamByteOrder
 g_data_input_stream_get_byte_order (GDataInputStream *stream)
@@ -256,9 +256,8 @@ read_data (GDataInputStream *stream,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
  * 
- * In order to get the correct byte order for this read operation, 
+ * Reads an unsigned 8-bit/1-byte value from @stream.
- * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order().
+ *
- * 
  * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 
  * if an error occured.
  **/
@@ -284,10 +283,12 @@ g_data_input_stream_read_byte (GDataInputStream        *stream,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
  * 
+ * Reads a 16-bit/2-byte value from @stream.
+ *
  * In order to get the correct byte order for this read operation, 
  * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order().
  * 
- * Returns a signed 16-bit/2-byte value read from @stream or %0 if 
+ * Returns: a signed 16-bit/2-byte value read from @stream or %0 if 
  * an error occured.
  **/
 gint16
@@ -326,10 +327,12 @@ g_data_input_stream_read_int16 (GDataInputStream        *stream,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
  *
+ * Reads an unsigned 16-bit/2-byte value from @stream.
+ *
  * In order to get the correct byte order for this read operation, 
  * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order(). 
  * 
- * Returns an unsigned 16-bit/2-byte value read from the @stream or %0 if 
+ * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if 
  * an error occured. 
  **/
 guint16
@@ -368,6 +371,8 @@ g_data_input_stream_read_uint16 (GDataInputStream        *stream,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
  * 
+ * Reads a signed 32-bit/4-byte value from @stream.
+ *
  * In order to get the correct byte order for this read operation, 
  * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order().
  *
@@ -375,7 +380,7 @@ g_data_input_stream_read_uint16 (GDataInputStream        *stream,
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  *   
- * Returns a signed 32-bit/4-byte value read from the @stream or %0 if 
+ * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if 
  * an error occured. 
  **/
 gint32
@@ -414,6 +419,8 @@ g_data_input_stream_read_int32 (GDataInputStream        *stream,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
  * 
+ * Reads an unsigned 32-bit/4-byte value from @stream.
+ *
  * In order to get the correct byte order for this read operation, 
  * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order().
  *
@@ -421,7 +428,7 @@ g_data_input_stream_read_int32 (GDataInputStream        *stream,
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
- * Returns an unsigned 32-bit/4-byte value read from the @stream or %0 if 
+ * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if 
  * an error occured. 
  **/
 guint32
@@ -460,6 +467,8 @@ g_data_input_stream_read_uint32 (GDataInputStream        *stream,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
  * 
+ * Reads a 64-bit/8-byte value from @stream.
+ *
  * In order to get the correct byte order for this read operation, 
  * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order().
  *
@@ -467,7 +476,7 @@ g_data_input_stream_read_uint32 (GDataInputStream        *stream,
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
- * Returns a signed 64-bit/8-byte value read from @stream or %0 if 
+ * Returns: a signed 64-bit/8-byte value read from @stream or %0 if 
  * an error occured.  
  **/
 gint64
@@ -506,6 +515,8 @@ g_data_input_stream_read_int64 (GDataInputStream        *stream,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
  * 
+ * Reads an unsigned 64-bit/8-byte value from @stream.
+ *
  * In order to get the correct byte order for this read operation, 
  * see g_data_stream_get_byte_order().
  *
@@ -513,7 +524,7 @@ g_data_input_stream_read_int64 (GDataInputStream        *stream,
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
- * Returns an unsigned 64-bit/8-byte read from @stream or %0 if 
+ * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if 
  * an error occured. 
  **/
 guint64
@@ -657,7 +668,7 @@ scan_for_newline (GDataInputStream *stream,
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. 
  * 
- * Returns a string with the line that was read in. Set @length to 
+ * Returns: a string with the line that was read in. Set @length to 
  * a #gsize to get the length of the read line. Returns %NULL on an error.
  **/
 char *
@@ -774,9 +785,12 @@ scan_for_chars (GDataInputStream *stream,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: #GError for error reporting.
  * 
- * Returns a string with the data that was read before encountering any of
+ * Reads a string from the data input stream, up to the first 
- * the stop characters. Set @length to a #gsize to get the length of the
+ * occurrance of any of the stop characters.
- * read line. This function will return %NULL on an error.
+ *
+ * Returns: a string with the data that was read before encountering 
+ * any of the stop characters. Set @length to a #gsize to get the length 
+ * of the string. This function will return %NULL on an error.
  **/
 char *
 g_data_input_stream_read_until (GDataInputStream        *stream,

gio/gdatainputstream.h

@@ -104,7 +104,7 @@ GDataInputStream*  g_data_input_stream_new        (GInputStream *base_stream);
 void                   g_data_input_stream_set_byte_order   (GDataInputStream        *stream,
 							     GDataStreamByteOrder     order);
 GDataStreamByteOrder   g_data_input_stream_get_byte_order   (GDataInputStream        *stream);
-void                   g_data_input_stream_set_newline_type (GDataInputStream        *data_stream,
+void                   g_data_input_stream_set_newline_type (GDataInputStream        *stream,
 							     GDataStreamNewlineType   type);
 GDataStreamNewlineType g_data_input_stream_get_newline_type (GDataInputStream        *stream);
 guchar                 g_data_input_stream_read_byte        (GDataInputStream        *stream,

gio/gdataoutputstream.c

@@ -181,7 +181,7 @@ g_data_output_stream_get_byte_order (GDataOutputStream *stream)
 
 /**
  * g_data_output_stream_put_byte:
- * @data_stream: a #GDataOutputStream.
+ * @stream: a #GDataOutputStream.
  * @data: a #guchar.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError, %NULL to ignore.
@@ -191,16 +191,16 @@ g_data_output_stream_get_byte_order (GDataOutputStream *stream)
  * Returns: %TRUE if @data was successfully added to the @stream.
  **/
 gboolean
-g_data_output_stream_put_byte (GDataOutputStream     *data_stream,
+g_data_output_stream_put_byte (GDataOutputStream     *stream,
 			       guchar                 data,
 			       GCancellable          *cancellable,
 			       GError               **error)
 {
   gsize bytes_written;
   
-  g_return_val_if_fail (G_IS_DATA_OUTPUT_STREAM (data_stream), FALSE);
+  g_return_val_if_fail (G_IS_DATA_OUTPUT_STREAM (stream), FALSE);
 
-  return g_output_stream_write_all (G_OUTPUT_STREAM (data_stream),
+  return g_output_stream_write_all (G_OUTPUT_STREAM (stream),
 				    &data, 1,
 				    &bytes_written,
 				    cancellable, error);

gio/gdataoutputstream.h

@@ -71,13 +71,13 @@ struct _GDataOutputStreamClass
 GType          g_data_output_stream_get_type   (void) G_GNUC_CONST;
 GDataOutputStream*  g_data_output_stream_new        (GOutputStream *base_stream);
 
-void                 g_data_output_stream_set_byte_order (GDataOutputStream     *data_stream,
+void                 g_data_output_stream_set_byte_order (GDataOutputStream     *stream,
 							  GDataStreamByteOrder   order);
 GDataStreamByteOrder g_data_output_stream_get_byte_order (GDataOutputStream     *stream);
-void                 g_data_output_stream_set_expand_buffer (GDataOutputStream     *data_stream,
+void                 g_data_output_stream_set_expand_buffer (GDataOutputStream     *stream,
 							     gboolean               expand_buffer);
 
-gboolean             g_data_output_stream_put_byte       (GDataOutputStream     *data_stream,
+gboolean             g_data_output_stream_put_byte       (GDataOutputStream     *stream,
 							  guchar                 data,
 							  GCancellable          *cancellable,
 							  GError               **error);

gio/gdesktopappinfo.c

@@ -1486,6 +1486,8 @@ app_info_in_list (GAppInfo *info, GList *l)
  * g_app_info_get_all_for_type:
  * @content_type:
  * 
+ * Gets a list of all #GAppInfo s for a given content type.
+ *
  * Returns: #GList of #GAppInfo s for given @content_type.
  **/
 GList *
@@ -1520,10 +1522,14 @@ g_app_info_get_all_for_type (const char *content_type)
 
 
 /**
- * g_app_info-get_default_for_type:
+ * g_app_info_get_default_for_type:
  * @content_type:
  * @must_support_uris:
  * 
+ * Gets the #GAppInfo that correspond to a given content type.
+ * If @must_support_uris is true, the #GAppInfo is expected to 
+ * support URIs. 
+ *
  * Returns: #GAppInfo for given @content_type.
  **/
 GAppInfo *

gio/gfile.c

@@ -3670,7 +3670,7 @@ g_file_real_set_attributes_finish (GFile                      *file,
  * fails, but the returned object might not support any I/O
  * operation if the @path is malformed.
  * 
- * Returns a new #GFile for the given @path. 
+ * Returns: a new #GFile for the given @path. 
  **/
 GFile *
 g_file_new_for_path (const char *path)
@@ -3689,7 +3689,7 @@ g_file_new_for_path (const char *path)
  * might not support any I/O operation if the @uri
  * is malformed or if the uri type is not supported.
  * 
- * Returns a #GFile for the given @uri.
+ * Returns: a #GFile for the given @uri.
  **/ 
 GFile *
 g_file_new_for_uri (const char *uri)
@@ -3709,7 +3709,7 @@ g_file_new_for_uri (const char *uri)
  * but the returned object might not support any I/O
  * operation if the @parse_name cannot be parsed by #GVfs.
  * 
- * Returns a new #GFile.
+ * Returns: a new #GFile.
  **/
 GFile *
 g_file_parse_name (const char *parse_name)
@@ -3750,7 +3750,7 @@ has_valid_scheme (const char *uri)
  * Attempts to generate a #GFile with the given line from
  * the command line argument. 
  * 
- * Returns a new #GFile. 
+ * Returns: a new #GFile. 
  **/
 GFile *
 g_file_new_for_commandline_arg (const char *arg)

gio/gfileattribute.c

@@ -747,7 +747,7 @@ g_file_attribute_info_list_new (void)
  * 
  * Makes a duplicate of a file attribute info list.
  * 
- * Returns a duplicate of the given @list. 
+ * Returns: a copy of the given @list. 
  **/
 GFileAttributeInfoList *
 g_file_attribute_info_list_dup (GFileAttributeInfoList *list)

gio/gfileinfo.h

@@ -57,9 +57,11 @@ typedef struct _GFileAttributeMatcher GFileAttributeMatcher;
  * @G_FILE_TYPE_UNKNOWN: File's type is unknown.
  * @G_FILE_TYPE_REGULAR: File handle represents a regular file.
  * @G_FILE_TYPE_DIRECTORY: File handle represents a directory.
- * @G_FILE_TYPE_SYMBOLIC_LINK: File handle represents a symbolic link (Unix systems)
+ * @G_FILE_TYPE_SYMBOLIC_LINK: File handle represents a symbolic link 
- * @G_FILE_TYPE_SPECIAL: File is a "special" file, such as a socket, fifo, blockdev,  or chardev.
+ *    (Unix systems).
- * @G_FILE_TYPE_SHORTCUT: File is a shortcut (Windows systems)
+ * @G_FILE_TYPE_SPECIAL: File is a "special" file, such as a socket, fifo, 
+ *    block device, or character device.
+ * @G_FILE_TYPE_SHORTCUT: File is a shortcut (Windows systems).
  * @G_FILE_TYPE_MOUNTABLE: File is a mountable location.
  * 
  * Indicates the file's on-disk type.
@@ -187,7 +189,8 @@ typedef enum {
  * G_FILE_ATTRIBUTE_STD_SYMLINK_TARGET:
  * 
  * A key in the "std" namespace for getting the symlink target, if the file
- * is a symlink. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+ * is a symlink. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
  **/
 #define G_FILE_ATTRIBUTE_STD_SYMLINK_TARGET "std:symlink_target" /* byte string */
 
@@ -204,21 +207,26 @@ typedef enum {
  * 
  * A key in the "std" namespace for setting the sort order of a file. 
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32.
- * An example use would be in file managers, which would use this key to set 
+ * An example use would be in file managers, which would use this key 
- * the order files are displayed.
+ * to set the order files are displayed.
  **/
 #define G_FILE_ATTRIBUTE_STD_SORT_ORDER "std:sort_order"         /* int32  */
 
 /* Entity tags, used to avoid missing updates on save */
+
 /**
  * G_FILE_ATTRIBUTE_ETAG_VALUE:
  * 
  * A key in the "etag" namespace for getting the value of the file's
- * entity tag. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * entity tag. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_STRING.
  **/
 #define G_FILE_ATTRIBUTE_ETAG_VALUE "etag:value"                 /* string */
 
-/* File identifier, for e.g. avoiding loops when doing recursive directory scanning */
+/* File identifier, for e.g. avoiding loops when doing recursive 
+ * directory scanning 
+ */
+
 /**
  * G_FILE_ATTRIBUTE_ID_FILE:
  * 
@@ -244,60 +252,62 @@ typedef enum {
 /**
  * G_FILE_ATTRIBUTE_ACCESS_CAN_READ:
  * 
- * A key in the "access" namespace for getting read privilidges. 
+ * A key in the "access" namespace for getting read privileges. 
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This key will be true if the user is able to read the file.
+ * This attribute will be %TRUE if the user is able to read the file.
  **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_READ "access:can_read"       /* boolean */
 
 /**
  * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE:
  * 
- * A key in the "access" namespace for getting write privilidges.
+ * A key in the "access" namespace for getting write privileges.
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This key will be true if the user is able to write to the file.
+ * This attribute will be %TRUE if the user is able to write to the file.
  **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE "access:can_write"     /* boolean */
 
 /**
  * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE:
  * 
- * A key in the "access" namespace for getting execution privilidges.
+ * A key in the "access" namespace for getting execution privileges.
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This key will be true if the user is able to execute the file.
+ * This attribute will be %TRUE if the user is able to execute the file.
  **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE "access:can_execute" /* boolean */
 
 /**
  * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE:
  * 
- * A key in the "access" namespace for checking deletion privilidges.
+ * A key in the "access" namespace for checking deletion privileges.
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This key will be true if the user is able to delete the file.
+ * This attribute will be %TRUE if the user is able to delete the file.
  **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE "access:can_delete"   /* boolean */
 
 /**
  * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH:
  * 
- * A key in the "access" namespace for checking trashing privilidges.
+ * A key in the "access" namespace for checking trashing privileges.
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This key will be true if the user is able to send the file to the 
+ * This attribute will be %TRUE if the user is able to send the file to 
- * virtual file system trash location.
+ * the virtual file system trash location.
  **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH "access:can_trash"     /* boolean */
 
 /**
  * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME:
  * 
- * A key in the "access" namespace for checking renaming privilidges.
+ * A key in the "access" namespace for checking renaming privileges.
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
- * This key will be true if the user is able to rename the file.
+ * This attribute will be %TRUE if the user is able to rename the file.
  **/
 #define G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME "access:can_rename"   /* boolean */ 
+
 /* TODO: Should we have special version for directories? can_enumerate, etc */
 
 /* Mountable attributes */
+
 /**
  * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT:
  * 
@@ -340,13 +350,13 @@ typedef enum {
 
 /* Time attributes */
 
-  /* The last time the file content or an attribute was modified */
 /**
  * G_FILE_ATTRIBUTE_TIME_MODIFIED:
  * 
  * A key in the "time" namespace for getting the time the file was last
- * modified. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, 
+ * modified. Corresponding #GFileAttributeType is 
- * and contains the UNIX time since the file was modified.
+ * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the 
+ * file was modified.
  **/
 #define G_FILE_ATTRIBUTE_TIME_MODIFIED "time:modified"           /* uint64 */
 
@@ -359,15 +369,17 @@ typedef enum {
  * %G_FILE_ATTRIBUTE_TYPE_UINT32.
  **/
 #define G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC "time:modified_usec" /* uint32 */
-  /* The last time the file was read */
+
 /**
  * G_FILE_ATTRIBUTE_TIME_ACCESS:
  * 
  * A key in the "time" namespace for getting the time the file was last
- * accessed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, 
+ * accessed. Corresponding #GFileAttributeType is 
- * and contains the UNIX time since the file was last accessed.
+ * %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the 
+ * file was last accessed.
  **/
 #define G_FILE_ATTRIBUTE_TIME_ACCESS "time:access"               /* uint64 */
+
 /**
  * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC:
  * 
@@ -377,15 +389,18 @@ typedef enum {
  * %G_FILE_ATTRIBUTE_TYPE_UINT32.
  **/
 #define G_FILE_ATTRIBUTE_TIME_ACCESS_USEC "time:access_usec"     /* uint32 */
-  /* The last time a file attribute was changed (e.g. unix ctime) */
+
 /**
  * G_FILE_ATTRIBUTE_TIME_CHANGED:
  * 
  * A key in the "time" namespace for getting the time the file was last
  * changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, 
  * and contains the UNIX time since the file was last changed.
+ *
+ * This corresponds to the traditional UNIX ctime.
  **/
 #define G_FILE_ATTRIBUTE_TIME_CHANGED "time:changed"             /* uint64 */
+
 /**
  * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC:
  * 
@@ -395,13 +410,15 @@ typedef enum {
  * %G_FILE_ATTRIBUTE_TYPE_UINT32. 
  **/
 #define G_FILE_ATTRIBUTE_TIME_CHANGED_USEC "time:changed_usec"   /* uint32 */
-  /* When the file was originally created (e.g. ntfs ctime) */
+
 /**
  * G_FILE_ATTRIBUTE_TIME_CREATED:
  * 
  * A key in the "time" namespace for getting the time the file was created.
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, 
  * and contains the UNIX time since the file was created.
+ *
+ * This corresponds to the NTFS ctime.
  **/
 #define G_FILE_ATTRIBUTE_TIME_CREATED "time:created"             /* uint64 */
 
@@ -416,16 +433,17 @@ typedef enum {
 #define G_FILE_ATTRIBUTE_TIME_CREATED_USEC "time:created_usec"   /* uint32 */
 
 /* Unix specific attributes */
+
 /**
  * G_FILE_ATTRIBUTE_UNIX_DEVICE:
  * 
  * A key in the "unix" namespace for getting the device id of the device the 
- * file is located on (see man stat(2)). This attribute is only available 
+ * file is located on (see stat() documentation). This attribute is only 
- * for UNIX file systems. Corresponding #GFileAttributeType is 
+ * available for UNIX file systems. Corresponding #GFileAttributeType is 
  * %G_FILE_ATTRIBUTE_TYPE_UINT32. 
- * 
  **/
 #define G_FILE_ATTRIBUTE_UNIX_DEVICE "unix:device"               /* uint32 */
+
 /**
  * G_FILE_ATTRIBUTE_UNIX_INODE:
  * 
@@ -434,24 +452,27 @@ typedef enum {
  * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
  **/
 #define G_FILE_ATTRIBUTE_UNIX_INODE "unix:inode"                 /* uint64 */
+
 /**
  * G_FILE_ATTRIBUTE_UNIX_MODE:
  * 
- * A key in the "unix" namespace for getting the mode of the file (e.g. whether the file 
+ * A key in the "unix" namespace for getting the mode of the file
- * is a regular file, symlink, etc). See man lstat(2). This attribute is only available 
+ * (e.g. whether the file is a regular file, symlink, etc). See lstat() 
- * for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * documentation. This attribute is only available for UNIX file systems. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
  **/
 #define G_FILE_ATTRIBUTE_UNIX_MODE "unix:mode"                   /* uint32 */
 
 /**
  * G_FILE_ATTRIBUTE_UNIX_NLINK:
  * 
- * A key in the "unix" namespace for getting the number of hard links for a 
+ * A key in the "unix" namespace for getting the number of hard links 
- * file. See man lstat(2). This attribute is only available for UNIX file systems. 
+ * for a file. See lstat() documentation. This attribute is only available 
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * for UNIX file systems. Corresponding #GFileAttributeType is 
- * 
+ * %G_FILE_ATTRIBUTE_TYPE_UINT32.
  **/
 #define G_FILE_ATTRIBUTE_UNIX_NLINK "unix:nlink"                 /* uint32 */
+
 /**
  * G_FILE_ATTRIBUTE_UNIX_UID:
  * 
@@ -460,6 +481,7 @@ typedef enum {
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
  **/
 #define G_FILE_ATTRIBUTE_UNIX_UID "unix:uid"                     /* uint32 */
+
 /**
  * G_FILE_ATTRIBUTE_UNIX_GID:
  * 
@@ -468,27 +490,31 @@ typedef enum {
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
  **/
 #define G_FILE_ATTRIBUTE_UNIX_GID "unix:gid"                     /* uint32 */
+
 /**
  * G_FILE_ATTRIBUTE_UNIX_RDEV:
  * 
- * A key in the "unix" namespace for getting the device ID for the file (if it 
+ * A key in the "unix" namespace for getting the device ID for the file 
- * is a special file). See man lstat(2). This attribute is only available for 
+ * (if it is a special file). See lstat() documentation. This attribute 
- * UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
+ * is only available for UNIX file systems. Corresponding #GFileAttributeType 
+ * is %G_FILE_ATTRIBUTE_TYPE_UINT32.
  **/
 #define G_FILE_ATTRIBUTE_UNIX_RDEV "unix:rdev"                   /* uint32 */
+
 /**
  * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE:
  * 
- * A key in the "unix" namespace for getting the block size for the file system.
+ * A key in the "unix" namespace for getting the block size for the file 
- * This attribute is only available for UNIX file systems. 
+ * system. This attribute is only available for UNIX file systems. 
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
  **/
 #define G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE "unix:block_size"       /* uint32 */
+
 /**
  * G_FILE_ATTRIBUTE_UNIX_BLOCKS:
  * 
- * A key in the "unix" namespace for getting the number of blocks allocated for the file.
+ * A key in the "unix" namespace for getting the number of blocks allocated 
- * This attribute is only available for UNIX file systems. 
+ * for the file. This attribute is only available for UNIX file systems. 
  * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
  **/
 #define G_FILE_ATTRIBUTE_UNIX_BLOCKS "unix:blocks"               /* uint64 */
@@ -496,45 +522,52 @@ typedef enum {
 /**
  * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT:
  * 
- * A key in the "unix" namespace for checking if the file represents a unix mount point.
+ * A key in the "unix" namespace for checking if the file represents a 
- * Returns %TRUE if the file is a unix mount point. This attribute is only available for 
+ * UNIX mount point. This attribute is %TRUE if the file is a UNIX mount 
- * UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * point. This attribute is only available for UNIX file systems. 
+ * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
  **/
 #define G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT "unix:is_mountpoint" /* boolean */
 
 /* DOS specific attributes */
+
 /**
  * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE:
  * 
- * A key in the "dos" namespace for checking if the file's archive flag is set.
+ * A key in the "dos" namespace for checking if the file's archive flag 
- * Returns %TRUE if the archive flag is set. This attribute is only available for 
+ * is set. This attribute is %TRUE if the archive flag is set. This attribute 
- * DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * is only available for DOS file systems. Corresponding #GFileAttributeType 
+ * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
  **/
 #define G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE "dos:is_archive"         /* boolean */
 
 /**
  * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM:
  * 
- * A key in the "dos" namespace for checking if the file's backup flag is set.
+ * A key in the "dos" namespace for checking if the file's backup flag 
- * Returns %TRUE if the backup flag is set. This attribute is only available for 
+ * is set. This attribute is %TRUE if the backup flag is set. This attribute 
- * DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * is only available for DOS file systems. Corresponding #GFileAttributeType 
+ * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
  **/
 #define G_FILE_ATTRIBUTE_DOS_IS_SYSTEM "dos:is_system"           /* boolean */
 
 /* Owner attributes */
+
 /**
  * G_FILE_ATTRIBUTE_OWNER_USER:
  * 
- * A key in the "owner" namespace for getting the user name of the file's owner.
+ * A key in the "owner" namespace for getting the user name of the 
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * file's owner. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_STRING.
  **/
 #define G_FILE_ATTRIBUTE_OWNER_USER "owner:user"                 /* string */
 
 /**
  * G_FILE_ATTRIBUTE_OWNER_USER_REAL:
  * 
- * A key in the "owner" namespace for getting the real name of the user that owns the file.
+ * A key in the "owner" namespace for getting the real name of the 
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * user that owns the file. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_STRING.
  **/
 #define G_FILE_ATTRIBUTE_OWNER_USER_REAL "owner:user_real"       /* string */
 
@@ -551,16 +584,17 @@ typedef enum {
 /**
  * G_FILE_ATTRIBUTE_THUMBNAIL_PATH:
  * 
- * A key in the "thumbnail" namespace for getting the path to the thumbnail image.
+ * A key in the "thumbnail" namespace for getting the path to the thumbnail 
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+ * image. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
  **/
 #define G_FILE_ATTRIBUTE_THUMBNAIL_PATH "thumbnail:path"         /* bytestring */
 /**
  * G_FILE_ATTRIBUTE_THUMBNAIL_THUMNAILING_FAILED:
  * 
  * A key in the "thumbnail" namespace for checking if thumbnailing failed. 
- * Is set to %TRUE if thumbnailing failed. Corresponding #GFileAttributeType 
+ * This attribute is %TRUE if thumbnailing failed. Corresponding 
- * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. 
+ * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. 
  **/
 #define G_FILE_ATTRIBUTE_THUMBNAILING_FAILED "thumbnail:failed"         /* boolean */
 
@@ -569,17 +603,18 @@ typedef enum {
 /**
  * G_FILE_ATTRIBUTE_FS_SIZE:
  * 
- * A key in the "fs" namespace for getting the size of the file system, used in
+ * A key in the "fs" namespace for getting the size of the file system, 
- * g_file_get_filesystem_info(). Corresponding #GFileAttributeType is 
+ * used in g_file_get_filesystem_info(). Corresponding #GFileAttributeType 
- * %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * is %G_FILE_ATTRIBUTE_TYPE_UINT64.
  **/
 #define G_FILE_ATTRIBUTE_FS_SIZE "fs:size"                       /* uint64 */
 
 /**
  * G_FILE_ATTRIBUTE_FS_FREE:
  * 
- * A key in the "fs" namespace for getting the free space left on the file system.
+ * A key in the "fs" namespace for getting the free space left on the 
- * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
+ * file system. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_UINT64.
  **/
 #define G_FILE_ATTRIBUTE_FS_FREE "fs:free"                       /* uint64 */
 
@@ -595,8 +630,8 @@ typedef enum {
  * G_FILE_ATTRIBUTE_FS_READONLY:
  * 
  * A key in the "fs" namespace for checking if the file system is read only.
- * Is set to %TRUE if the file system is read only. Corresponding #GFileAttributeType is 
+ * Is set to %TRUE if the file system is read only. Corresponding 
- * %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
  **/
 #define G_FILE_ATTRIBUTE_FS_READONLY "fs:readonly"               /* boolean */
 
@@ -604,7 +639,8 @@ typedef enum {
  * G_FILE_ATTRIBUTE_GVFS_BACKEND:
  * 
  * A key in the "gvfs" namespace that gets the name of the current
- * GVFS backend in use. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
+ * GVFS backend in use. Corresponding #GFileAttributeType is 
+ * %G_FILE_ATTRIBUTE_TYPE_STRING.
  **/
 #define G_FILE_ATTRIBUTE_GVFS_BACKEND "gvfs:backend"             /* string */
 

gio/glocalvfs.c

@@ -54,8 +54,10 @@ g_local_vfs_init (GLocalVfs *vfs)
 
 /**
  * g_local_vfs_new:
- * 
+ *
- * Returns a new #GVfs handle.
+ * Returns a new #GVfs handle for a local vfs.
+ *
+ * Returns: a new #GVfs handle.
  **/
 GVfs *
 g_local_vfs_new (void)

gio/gpollfilemonitor.c

@@ -196,7 +196,7 @@ got_initial_info (GObject *source_object,
  * 
  * Polls @file for changes.
  * 
- * Returns a new #GFileMonitor for the given #GFile. 
+ * Returns: a new #GFileMonitor for the given #GFile. 
  **/
 GFileMonitor*
 g_poll_file_monitor_new (GFile *file)

gio/gunixmounts.c

@@ -906,10 +906,10 @@ get_mount_points_timestamp (void)
  * g_get_unix_mounts:
  * @time_read: guint64 to contain a timestamp.
  * 
- * Gets a #GList of strings containing the unix mounts. If @time_read
+ * Gets a #GList of strings containing the unix mounts. 
- * is set, it will be filled with the mount timestamp, 
+ * If @time_read is set, it will be filled with the mount 
- * allowing for checking if the mounts have changed with 
+ * timestamp, allowing for checking if the mounts have changed 
- * g_unix_mounts_changed_since().
+ * with g_unix_mounts_changed_since().
  * 
  * Returns: a #GList of the UNIX mounts. 
  **/
@@ -967,7 +967,7 @@ g_get_unix_mount_at (const char *mount_path,
  * allowing for checking if the mounts have changed with 
  * g_unix_mounts_points_changed_since().
  * 
- * Returns a #GList of the UNIX mountpoints. 
+ * Returns: a #GList of the UNIX mountpoints. 
  **/
 GList *
 g_get_unix_mount_points (guint64 *time_read)
@@ -984,7 +984,7 @@ g_get_unix_mount_points (guint64 *time_read)
  * 
  * Checks if the unix mounts have changed since a given unix time.
  * 
- * Returns %TRUE if the mounts have changed since @time. 
+ * Returns: %TRUE if the mounts have changed since @time. 
  **/
 gboolean
 g_unix_mounts_changed_since (guint64 time)
@@ -998,7 +998,7 @@ g_unix_mounts_changed_since (guint64 time)
  * 
  * Checks if the unix mount points have changed since a given unix time.
  * 
- * Returns %TRUE if the mount points have changed since @time. 
+ * Returns: %TRUE if the mount points have changed since @time. 
  **/
 gboolean
 g_unix_mount_points_changed_since (guint64 time)
@@ -1199,7 +1199,7 @@ strcmp_null (const char *str1,
  * 
  * Compares two unix mounts.
  * 
- * Returns 1, 0 or -1 if @mount1 is greater than, equal to,
+ * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
  * or less than @mount2, respectively. 
  **/
 gint
@@ -1316,7 +1316,7 @@ g_unix_mount_is_system_internal (GUnixMount *mount_entry)
  * 
  * Compares two unix mount points.
  * 
- * Returns 1, 0 or -1 if @mount1 is greater than, equal to,
+ * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
  * or less than @mount2, respectively.
  **/
 gint

gio/gvfs.c

@@ -124,7 +124,7 @@ g_vfs_get_file_for_uri (GVfs *vfs,
  * g_vfs_get_supported_uri_schemes:
  * @vfs: a #GVfs.
  * 
- * Gets a list of URI schemes supported by GVFS. 
+ * Gets a list of URI schemes supported by @vfs.
  * 
  * Returns: a list of strings.
  **/
@@ -149,7 +149,7 @@ g_vfs_get_supported_uri_schemes (GVfs *vfs)
  * not support any I/O operations if the @parse_name cannot 
  * be parsed by the #GVfs module.
  * 
- * Returns a #GFile for the given @parse_name.
+ * Returns: a #GFile for the given @parse_name.
  **/
 GFile *
 g_vfs_parse_name (GVfs *vfs,

gio/gvolume.c

@@ -123,7 +123,7 @@ g_volume_base_init (gpointer g_class)
  * 
  * Gets the root directory on @volume.
  * 
- * Returns a #GFile.
+ * Returns: a #GFile.
  **/
 GFile *
 g_volume_get_root (GVolume *volume)
@@ -143,7 +143,7 @@ g_volume_get_root (GVolume *volume)
  * 
  * Gets the name of @volume.
  * 
- * Returns the name for the given @volume. The returned string should 
+ * Returns: the name for the given @volume. The returned string should 
  * be freed when no longer needed.
  **/
 char *
@@ -204,7 +204,7 @@ g_volume_get_drive (GVolume *volume)
  * 
  * Checks if @volume can be mounted.
  * 
- * Returns %TRUE if the @volume can be unmounted.
+ * Returns: %TRUE if the @volume can be unmounted.
  **/
 gboolean
 g_volume_can_unmount (GVolume *volume)
@@ -224,7 +224,7 @@ g_volume_can_unmount (GVolume *volume)
  * 
  * Checks if @volume can be ejected.
  * 
- * Returns %TRUE if the @volume can be ejected.
+ * Returns: %TRUE if the @volume can be ejected.
  **/
 gboolean
 g_volume_can_eject (GVolume *volume)

gio/gvolumemonitor.c

@@ -149,7 +149,7 @@ g_volume_monitor_init (GVolumeMonitor *monitor)
  * 
  * Gets a list of volumes mounted on the computer.
  * 
- * Returns a #GList of mounted #GVolumes.
+ * Returns: a #GList of mounted #GVolumes.
  **/
 GList *
 g_volume_monitor_get_mounted_volumes  (GVolumeMonitor *volume_monitor)

gio/gwin32appinfo.c

@@ -490,13 +490,6 @@ app_info_in_list (GAppInfo *info, GList *l)
   return FALSE;
 }
 
-/**
- * g_app_info_get_all_for_type:
- * @content_type:
- * 
- * Returns a #GList of #GAppInfo for a given @content_type.
- * 
- **/
 GList *
 g_app_info_get_all_for_type (const char *content_type)
 {
@@ -580,16 +573,6 @@ g_app_info_get_all_for_type (const char *content_type)
   return g_list_reverse (infos);
 }
 
-/**
- * g_app_info_get_default_for_type:
- * @content_type:
- * @must_support_uris:
- * 
- * Returns the default #GAppInfo for the given @content_type. If 
- * @must_support_uris is true, the #GAppInfo is expected to support
- * URIs. 
- * 
- **/
 GAppInfo *
 g_app_info_get_default_for_type (const char *content_type,
 				 gboolean must_support_uris)
@@ -615,11 +598,6 @@ g_app_info_get_default_for_type (const char *content_type,
   return NULL;
 }
 
-/**
- * g_app_info_get_default_for_uri_scheme:
- * @uri_scheme:
- * 
- **/
 GAppInfo *
 g_app_info_get_default_for_uri_scheme (const char *uri_scheme)
 {
@@ -627,10 +605,6 @@ g_app_info_get_default_for_uri_scheme (const char *uri_scheme)
   return NULL;
 }
 
-/**
- * g_app_info_get_all:
- * 
- **/
 GList *
 g_app_info_get_all (void)
 {