diff --git a/gio/ChangeLog b/gio/ChangeLog index 16534755b..6e39be5d0 100644 --- a/gio/ChangeLog +++ b/gio/ChangeLog @@ -1,3 +1,8 @@ +2008-07-08 Matthias Clasen + + * gvolume.c: + * gmount.c: Documentation improvements. + 2008-07-08 Matthias Clasen * gio.symbols: diff --git a/gio/gmount.c b/gio/gmount.c index e304dd376..1870b8824 100644 --- a/gio/gmount.c +++ b/gio/gmount.c @@ -149,7 +149,9 @@ g_mount_base_init (gpointer g_class) * * 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 @@ g_mount_get_root (GMount *mount) * * 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 @@ g_mount_get_name (GMount *mount) * 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 @@ g_mount_get_icon (GMount *mount) * 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 @@ g_mount_get_uuid (GMount *mount) * 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 @@ g_mount_get_volume (GMount *mount) * 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 @@ g_mount_can_eject (GMount *mount) * * 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 @@ g_mount_unmount (GMount *mount, * 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 @@ g_mount_unmount_finish (GMount *mount, * * 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 @@ g_mount_eject (GMount *mount, * 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 @@ g_mount_eject_finish (GMount *mount, * 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 @@ g_mount_remount (GMount *mount, * 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) { diff --git a/gio/gvolume.c b/gio/gvolume.c index 64229b88f..5f56bb7fa 100644 --- a/gio/gvolume.c +++ b/gio/gvolume.c @@ -159,7 +159,7 @@ g_volume_base_init (gpointer g_class) * 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 @@ g_volume_get_name (GVolume *volume) * 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 @@ g_volume_get_icon (GVolume *volume) * 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 @@ g_volume_get_uuid (GVolume *volume) * 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 @@ g_volume_get_drive (GVolume *volume) * 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 @@ g_volume_should_automount (GVolume *volume) * @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 (GVolume *volume, /** * 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 @@ g_volume_mount_finish (GVolume *volume, * @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 (GVolume *volume, * 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;