glib r7172 - trunk/gio

[matthiasc svn gnome org]

Author: matthiasc
Date: Wed Jul  9 04:18:45 2008
New Revision: 7172
URL: http://svn.gnome.org/viewvc/glib?rev=7172&view=rev

Log:
Documentation improvements.


Modified:
   trunk/gio/ChangeLog
   trunk/gio/gmount.c
   trunk/gio/gvolume.c

Modified: trunk/gio/gmount.c
==============================================================================
--- trunk/gio/gmount.c	(original)
+++ trunk/gio/gmount.c	Wed Jul  9 04:18:45 2008
@@ -149,7 +149,9 @@
  * 
  * Gets the root directory on @mount.
  * 
- * Returns: a #GFile.
+ * Returns: a #GFile. 
+ *      The returned object should be unreffed with 
+ *      g_object_unref() when no longer needed.
  **/
 GFile *
 g_mount_get_root (GMount *mount)
@@ -169,8 +171,9 @@
  * 
  * Gets the name of @mount.
  * 
- * Returns: the name for the given @mount. The returned string should 
- * be freed when no longer needed.
+ * Returns: the name for the given @mount. 
+ *     The returned string should be freed with g_free()
+ *     when no longer needed.
  **/
 char *
 g_mount_get_name (GMount *mount)
@@ -191,6 +194,8 @@
  * Gets the icon for @mount.
  * 
  * Returns: a #GIcon.
+ *      The returned object should be unreffed with 
+ *      g_object_unref() when no longer needed.
  **/
 GIcon *
 g_mount_get_icon (GMount *mount)
@@ -214,6 +219,8 @@
  * available.
  * 
  * Returns: the UUID for @mount or %NULL if no UUID can be computed.
+ *     The returned string should be freed with g_free()
+ *     when no longer needed.
  **/
 char *
 g_mount_get_uuid (GMount *mount)
@@ -234,6 +241,8 @@
  * Gets the volume for the @mount.
  * 
  * Returns: a #GVolume or %NULL if @mount is not associated with a volume.
+ *      The returned object should be unreffed with 
+ *      g_object_unref() when no longer needed.
  **/
 GVolume *
 g_mount_get_volume (GMount *mount)
@@ -257,6 +266,8 @@
  * using that object to get the #GDrive.
  * 
  * Returns: a #GDrive or %NULL if @mount is not associated with a volume or a drive.
+ *      The returned object should be unreffed with 
+ *      g_object_unref() when no longer needed.
  **/
 GDrive *
 g_mount_get_drive (GMount *mount)
@@ -320,14 +331,14 @@
  * 
  * Unmounts a mount. This is an asynchronous operation, and is 
  * finished by calling g_mount_unmount_finish() with the @mount 
- * and #GAsyncResults data returned in the @callback.
+ * and #GAsyncResult data returned in the @callback.
  **/
 void
-g_mount_unmount (GMount *mount,
-                 GMountUnmountFlags flags,
-                 GCancellable *cancellable,
-                 GAsyncReadyCallback callback,
-                 gpointer user_data)
+g_mount_unmount (GMount              *mount,
+                 GMountUnmountFlags   flags,
+                 GCancellable        *cancellable,
+                 GAsyncReadyCallback  callback,
+                 gpointer             user_data)
 {
   GMountIface *iface;
 
@@ -364,7 +375,7 @@
  * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise.
  **/
 gboolean
-g_mount_unmount_finish (GMount       *mount,
+g_mount_unmount_finish (GMount        *mount,
                         GAsyncResult  *result,
                         GError       **error)
 {
@@ -395,14 +406,14 @@
  * 
  * Ejects a mount. This is an asynchronous operation, and is 
  * finished by calling g_mount_eject_finish() with the @mount 
- * and #GAsyncResults data returned in the @callback.
+ * and #GAsyncResult data returned in the @callback.
  **/
 void
-g_mount_eject (GMount *mount,
-               GMountUnmountFlags flags,
-               GCancellable *cancellable,
-               GAsyncReadyCallback callback,
-               gpointer user_data)
+g_mount_eject (GMount              *mount,
+               GMountUnmountFlags   flags,
+               GCancellable        *cancellable,
+               GAsyncReadyCallback  callback,
+               gpointer             user_data)
 {
   GMountIface *iface;
 
@@ -439,7 +450,7 @@
  * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise.
  **/
 gboolean
-g_mount_eject_finish (GMount       *mount,
+g_mount_eject_finish (GMount        *mount,
                       GAsyncResult  *result,
                       GError       **error)
 {
@@ -479,12 +490,12 @@
  * unmounted.
  **/
 void
-g_mount_remount (GMount *mount,
-                 GMountMountFlags flags,
-                 GMountOperation *mount_operation,
-                 GCancellable *cancellable,
-                 GAsyncReadyCallback callback,
-                 gpointer user_data)
+g_mount_remount (GMount              *mount,
+                 GMountMountFlags     flags,
+                 GMountOperation     *mount_operation,
+                 GCancellable        *cancellable,
+                 GAsyncReadyCallback  callback,
+                 gpointer             user_data)
 {
   GMountIface *iface;
 
@@ -521,7 +532,7 @@
  * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise.
  **/
 gboolean
-g_mount_remount_finish (GMount       *mount,
+g_mount_remount_finish (GMount        *mount,
                         GAsyncResult  *result,
                         GError       **error)
 {

Modified: trunk/gio/gvolume.c
==============================================================================
--- trunk/gio/gvolume.c	(original)
+++ trunk/gio/gvolume.c	Wed Jul  9 04:18:45 2008
@@ -159,7 +159,7 @@
  * Gets the name of @volume.
  * 
  * Returns: the name for the given @volume. The returned string should 
- * be freed when no longer needed.
+ * be freed with g_free() when no longer needed.
  **/
 char *
 g_volume_get_name (GVolume *volume)
@@ -180,6 +180,8 @@
  * Gets the icon for @volume.
  * 
  * Returns: a #GIcon.
+ *     The returned object should be unreffed with g_object_unref()
+ *     when no longer needed.
  **/
 GIcon *
 g_volume_get_icon (GVolume *volume)
@@ -203,6 +205,8 @@
  * available.
  * 
  * Returns: the UUID for @volume or %NULL if no UUID can be computed.
+ *     The returned string should be freed with g_free() 
+ *     when no longer needed.
  **/
 char *
 g_volume_get_uuid (GVolume *volume)
@@ -223,6 +227,8 @@
  * Gets the drive for the @volume.
  * 
  * Returns: a #GDrive or %NULL if @volume is not associated with a drive.
+ *     The returned object should be unreffed with g_object_unref()
+ *     when no longer needed.
  **/
 GDrive *
 g_volume_get_drive (GVolume *volume)
@@ -243,6 +249,8 @@
  * Gets the mount for the @volume.
  * 
  * Returns: a #GMount or %NULL if @volume isn't mounted.
+ *     The returned object should be unreffed with g_object_unref()
+ *     when no longer needed.
  **/
 GMount *
 g_volume_get_mount (GVolume *volume)
@@ -334,12 +342,14 @@
  * @mount_operation: a #GMountOperation or %NULL to avoid user interaction.
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback, or %NULL.
- * @user_data: a #gpointer.
+ * @user_data: user data that gets passed to @callback
  * 
- * Mounts a volume.
+ * Mounts a volume. This is an asynchronous operation, and is
+ * finished by calling g_volume_mount_finish() with the @volume
+ * and #GAsyncResult returned in the @callback.
  **/
 void
-g_volume_mount (GVolume    *volume,
+g_volume_mount (GVolume             *volume,
 		GMountMountFlags     flags,
                 GMountOperation     *mount_operation,
                 GCancellable        *cancellable,
@@ -366,18 +376,19 @@
 
 /**
  * g_volume_mount_finish:
- * @volume: pointer to a #GVolume.
- * @result: a #GAsyncResult.
- * @error: a #GError.
+ * @volume: a #GVolume
+ * @result: a #GAsyncResult
+ * @error: a #GError location to store an error, or %NULL to ignore
  * 
- * Finishes mounting a volume.
+ * Finishes mounting a volume. If any errors occured during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
  * 
  * Returns: %TRUE, %FALSE if operation failed.
  **/
 gboolean
-g_volume_mount_finish (GVolume  *volume,
-                       GAsyncResult      *result,
-                       GError           **error)
+g_volume_mount_finish (GVolume       *volume,
+                       GAsyncResult  *result,
+                       GError       **error)
 {
   GVolumeIface *iface;
 
@@ -401,12 +412,14 @@
  * @flags: flags affecting the unmount if required for eject
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback, or %NULL.
- * @user_data: a #gpointer.
+ * @user_data: user data that gets passed to @callback
  * 
- * Ejects a volume.
+ * Ejects a volume. This is an asynchronous operation, and is
+ * finished by calling g_volume_eject_finish() with the @volume
+ * and #GAsyncResult returned in the @callback.
  **/
 void
-g_volume_eject (GVolume    *volume,
+g_volume_eject (GVolume             *volume,
 		GMountUnmountFlags   flags,
                 GCancellable        *cancellable,
                 GAsyncReadyCallback  callback,
@@ -434,16 +447,17 @@
  * g_volume_eject_finish:
  * @volume: pointer to a #GVolume.
  * @result: a #GAsyncResult.
- * @error: a #GError.
+ * @error: a #GError location to store an error, or %NULL to ignore
  * 
- * Finishes ejecting a volume.
+ * Finishes ejecting a volume. If any errors occured during the operation,
+ * @error will be set to contain the errors and %FALSE will be returned.
  * 
  * Returns: %TRUE, %FALSE if operation failed.
  **/
 gboolean
-g_volume_eject_finish (GVolume  *volume,
-                       GAsyncResult      *result,
-                       GError           **error)
+g_volume_eject_finish (GVolume       *volume,
+                       GAsyncResult  *result,
+                       GError       **error)
 {
   GVolumeIface *iface;