[glib] Fix and update GI annotations for 'Volumes and Drives'

[Pavel Holejsovsky <pholejs src gnome org>]

commit f6b52322a2049dfb3873922a8f1417d8c44363b0
Author: Pavel Holejsovsky <pholejs src gnome org>
Date:   Fri Jan 7 14:52:29 2011 +0100

    Fix and update GI annotations for 'Volumes and Drives'
    
    Volumes and Drives GIO category contains: GVolumeMonitor, GVolume,
    GMount, GDrive, Unix Mounts.

 gio/gdrive.c      |   34 +++++++++++++++++++---------------
 gio/gmount.c      |   33 ++++++++++++++++++---------------
 gio/gunixmounts.c |   20 +++++++++++---------
 gio/gvolume.c     |   13 +++++++------
 4 files changed, 55 insertions(+), 45 deletions(-)
---
diff --git a/gio/gdrive.c b/gio/gdrive.c
index 5d6efdc..b4a6164 100644
--- a/gio/gdrive.c
+++ b/gio/gdrive.c
@@ -331,8 +331,8 @@ g_drive_can_poll_for_media (GDrive *drive)
  * g_drive_eject:
  * @drive: a #GDrive.
  * @flags: flags affecting the unmount if required for eject
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data to pass to @callback
  * 
  * Asynchronously ejects a drive.
@@ -407,9 +407,10 @@ g_drive_eject_finish (GDrive        *drive,
  * g_drive_eject_with_operation:
  * @drive: a #GDrive.
  * @flags: flags affecting the unmount if required for eject
- * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
+ *     user interaction.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data passed to @callback.
  *
  * Ejects a drive. This is an asynchronous operation, and is
@@ -491,8 +492,8 @@ g_drive_eject_with_operation_finish (GDrive        *drive,
 /**
  * g_drive_poll_for_media:
  * @drive: a #GDrive.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data to pass to @callback
  * 
  * Asynchronously polls @drive to see if media has been inserted or removed.
@@ -594,8 +595,9 @@ g_drive_get_identifier (GDrive     *drive,
  * Use g_drive_get_identifer() to obtain the identifiers
  * themselves.
  *
- * Returns: (transfer full): a %NULL-terminated array of strings containing
- *     kinds of identifiers. Use g_strfreev() to free.
+ * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
+ *     array of strings containing kinds of identifiers. Use g_strfreev()
+ *     to free.
  */
 char **
 g_drive_enumerate_identifiers (GDrive *drive)
@@ -691,9 +693,10 @@ g_drive_can_start_degraded (GDrive *drive)
  * g_drive_start:
  * @drive: a #GDrive.
  * @flags: flags affecting the start operation.
- * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
+ *     user interaction.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data to pass to @callback
  *
  * Asynchronously starts a drive.
@@ -793,9 +796,10 @@ g_drive_can_stop (GDrive *drive)
  * g_drive_stop:
  * @drive: a #GDrive.
  * @flags: flags affecting the unmount if required for stopping.
- * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
+ *     user interaction.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data to pass to @callback
  *
  * Asynchronously stops a drive.
diff --git a/gio/gmount.c b/gio/gmount.c
index 983a9fe..4868fad 100644
--- a/gio/gmount.c
+++ b/gio/gmount.c
@@ -329,8 +329,8 @@ g_mount_can_eject (GMount *mount)
  * g_mount_unmount:
  * @mount: a #GMount.
  * @flags: flags affecting the operation
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data passed to @callback.
  * 
  * Unmounts a mount. This is an asynchronous operation, and is 
@@ -408,8 +408,8 @@ g_mount_unmount_finish (GMount        *mount,
  * g_mount_eject:
  * @mount: a #GMount.
  * @flags: flags affecting the unmount if required for eject
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data passed to @callback.
  * 
  * Ejects a mount. This is an asynchronous operation, and is 
@@ -486,9 +486,10 @@ g_mount_eject_finish (GMount        *mount,
  * g_mount_unmount_with_operation:
  * @mount: a #GMount.
  * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
+ *     user interaction.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data passed to @callback.
  *
  * Unmounts a mount. This is an asynchronous operation, and is
@@ -573,9 +574,10 @@ g_mount_unmount_with_operation_finish (GMount        *mount,
  * g_mount_eject_with_operation:
  * @mount: a #GMount.
  * @flags: flags affecting the unmount if required for eject
- * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
+ *     user interaction.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data passed to @callback.
  *
  * Ejects a mount. This is an asynchronous operation, and is
@@ -658,9 +660,10 @@ g_mount_eject_with_operation_finish (GMount        *mount,
  * g_mount_remount:
  * @mount: a #GMount.
  * @flags: flags affecting the operation
- * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid
+ *     user interaction.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data passed to @callback.
  * 
  * Remounts a mount. This is an asynchronous operation, and is 
@@ -741,7 +744,7 @@ g_mount_remount_finish (GMount        *mount,
  * @mount: a #GMount
  * @force_rescan: Whether to force a rescan of the content. 
  *     Otherwise a cached result will be used if available
- * @cancellable: optional #GCancellable object, %NULL to ignore
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
  * @callback: a #GAsyncReadyCallback
  * @user_data: user data passed to @callback
  * 
@@ -831,7 +834,7 @@ g_mount_guess_content_type_finish (GMount        *mount,
  * @mount: a #GMount
  * @force_rescan: Whether to force a rescan of the content.
  *     Otherwise a cached result will be used if available
- * @cancellable: optional #GCancellable object, %NULL to ignore
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
  * @error: a #GError location to store the error occuring, or %NULL to
  *     ignore
  *
diff --git a/gio/gunixmounts.c b/gio/gunixmounts.c
index f110351..054bfe7 100644
--- a/gio/gunixmounts.c
+++ b/gio/gunixmounts.c
@@ -1075,15 +1075,16 @@ get_mount_points_timestamp (void)
 }
 
 /**
- * g_unix_mounts_get:
- * @time_read: (allow-none): guint64 to contain a timestamp, or %NULL
+ * g_unix_mounts_get: (skip)
+ * @time_read: (out) (allow-none): guint64 to contain a timestamp, or %NULL
  *
  * Gets a #GList of #GUnixMountEntry containing the unix mounts.
  * If @time_read is set, it will be filled with the mount
  * timestamp, allowing for checking if the mounts have changed
  * with g_unix_mounts_changed_since().
  *
- * Returns: (element-type utf8) (transfer full): a #GList of the UNIX mounts.
+ * Returns: (element-type GUnixMountEntry) (transfer full):
+ *     a #GList of the UNIX mounts.
  **/
 GList *
 g_unix_mounts_get (guint64 *time_read)
@@ -1095,15 +1096,15 @@ g_unix_mounts_get (guint64 *time_read)
 }
 
 /**
- * g_unix_mount_at:
+ * g_unix_mount_at: (skip)
  * @mount_path: path for a possible unix mount.
- * @time_read: guint64 to contain a timestamp.
+ * @time_read: (out) (allow-none): guint64 to contain a timestamp.
  * 
  * Gets a #GUnixMountEntry for a given mount path. If @time_read
  * is set, it will be filled with a unix timestamp for checking
  * if the mounts have changed since with g_unix_mounts_changed_since().
  * 
- * Returns: (transfer full): a #GUnixMount. 
+ * Returns: (transfer full): a #GUnixMountEntry.
  **/
 GUnixMountEntry *
 g_unix_mount_at (const char *mount_path,
@@ -1130,15 +1131,16 @@ g_unix_mount_at (const char *mount_path,
 }
 
 /**
- * g_unix_mount_points_get:
- * @time_read: (allow-none): guint64 to contain a timestamp.
+ * g_unix_mount_points_get: (skip)
+ * @time_read: (out) (allow-none): guint64 to contain a timestamp.
  *
  * Gets a #GList of #GUnixMountPoint containing the unix mount points.
  * If @time_read is set, it will be filled with the mount timestamp,
  * allowing for checking if the mounts have changed with
  * g_unix_mounts_points_changed_since().
  *
- * Returns: (element-type utf8) (transfer full): a #GList of the UNIX mountpoints.
+ * Returns: (element-type GUnixMountPoint) (transfer full):
+ *     a #GList of the UNIX mountpoints.
  **/
 GList *
 g_unix_mount_points_get (guint64 *time_read)
diff --git a/gio/gvolume.c b/gio/gvolume.c
index df1b78d..8e96288 100644
--- a/gio/gvolume.c
+++ b/gio/gvolume.c
@@ -301,8 +301,8 @@ g_volume_should_automount (GVolume *volume)
  * @volume: a #GVolume.
  * @flags: flags affecting the operation
  * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data that gets passed to @callback
  * 
  * Mounts a volume. This is an asynchronous operation, and is
@@ -378,8 +378,8 @@ g_volume_mount_finish (GVolume       *volume,
  * g_volume_eject:
  * @volume: a #GVolume.
  * @flags: flags affecting the unmount if required for eject
- * @cancellable: optional #GCancellable object, %NULL to ignore.
- * @callback: a #GAsyncReadyCallback, or %NULL.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data that gets passed to @callback
  * 
  * Ejects a volume. This is an asynchronous operation, and is
@@ -451,8 +451,9 @@ g_volume_eject_finish (GVolume       *volume,
  * g_volume_eject_with_operation:
  * @volume: a #GVolume.
  * @flags: flags affecting the unmount if required for eject
- * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @mount_operation: (allow-none): a #GMountOperation or %NULL to
+ *     avoid user interaction.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback, or %NULL.
  * @user_data: user data passed to @callback.
  *