brasero r1827 - in trunk: . libbrasero-media

[philippr svn gnome org]

Author: philippr
Date: Sat Jan 24 14:28:23 2009
New Revision: 1827
URL: http://svn.gnome.org/viewvc/brasero?rev=1827&view=rev

Log:
2009-01-24  Philippe Rouquier  <ykw localhost localdomain>

	Some more documentation for API (should now be completed) and add some
	more g_return_(val_)_if_fail ().

	* libbrasero-media/brasero-drive.c (brasero_drive_get_gdrive),
	(brasero_drive_get_bus_target_lun_string), (brasero_drive_is_fake),
	(brasero_drive_is_door_open), (brasero_drive_can_use_exclusively),
	(brasero_drive_lock), (brasero_drive_unlock),
	(brasero_drive_get_display_name), (brasero_drive_get_device),
	(brasero_drive_get_block_device), (brasero_drive_get_udi),
	(brasero_drive_get_caps), (brasero_drive_can_write),
	(brasero_drive_probing), (brasero_drive_reprobe):
	* libbrasero-media/brasero-medium-monitor.c
	(brasero_medium_monitor_get_drive),
	(brasero_medium_monitor_is_probing),
	(brasero_medium_monitor_get_drives),
	(brasero_medium_monitor_get_media):
	* libbrasero-media/brasero-medium.c (brasero_medium_get_tooltip),
	(brasero_medium_get_type_string), (brasero_medium_get_status),
	(brasero_medium_get_last_data_track_space),
	(brasero_medium_get_track_num), (brasero_medium_get_track_space),
	(brasero_medium_get_track_address),
	(brasero_medium_get_next_writable_address),
	(brasero_medium_get_max_write_speed),
	(brasero_medium_get_write_speeds), (brasero_medium_get_data_size),
	(brasero_medium_get_free_space), (brasero_medium_get_capacity),
	(brasero_medium_can_be_written), (brasero_medium_can_be_rewritten),
	(brasero_medium_get_drive), (brasero_medium_get_CD_TEXT_title):
	* libbrasero-media/brasero-volume.c (brasero_volume_get_gvolume),
	(brasero_volume_is_mounted), (brasero_volume_get_mount_point),
	(brasero_volume_umount), (brasero_volume_mount),
	(brasero_volume_cancel_current_operation),
	(brasero_volume_get_icon), (brasero_volume_get_name):


Modified:
   trunk/ChangeLog
   trunk/libbrasero-media/brasero-drive.c
   trunk/libbrasero-media/brasero-medium-monitor.c
   trunk/libbrasero-media/brasero-medium.c
   trunk/libbrasero-media/brasero-volume.c

Modified: trunk/libbrasero-media/brasero-drive.c
==============================================================================
--- trunk/libbrasero-media/brasero-drive.c	(original)
+++ trunk/libbrasero-media/brasero-drive.c	Sat Jan 24 14:28:23 2009
@@ -120,6 +120,7 @@
 	GList *drives;
 	GList *iter;
 
+	g_return_val_if_fail (drive != NULL, NULL);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), NULL);
 
 	if (brasero_drive_is_fake (drive))
@@ -282,6 +283,7 @@
 {
 	BraseroDrivePrivate *priv;
 
+	g_return_val_if_fail (drive != NULL, NULL);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), NULL);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -308,6 +310,7 @@
 {
 	BraseroDrivePrivate *priv;
 
+	g_return_val_if_fail (drive != NULL, FALSE);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), FALSE);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -329,6 +332,7 @@
 	BraseroDeviceHandle *handle;
 	BraseroScsiMechStatusHdr hdr;
 
+	g_return_val_if_fail (drive != NULL, FALSE);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), FALSE);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -363,6 +367,7 @@
 	BraseroDeviceHandle *handle;
 	const gchar *device;
 
+	g_return_val_if_fail (drive != NULL, FALSE);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), FALSE);
 
 #if defined(HAVE_STRUCT_USCSI_CMD)
@@ -401,6 +406,7 @@
 	gboolean result;
 	gchar *failure;
 
+	g_return_val_if_fail (drive != NULL, FALSE);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), FALSE);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -453,6 +459,7 @@
 	DBusError error;
 	gboolean result;
 
+	g_return_val_if_fail (drive != NULL, FALSE);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), FALSE);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -490,6 +497,7 @@
 	BraseroHALWatch *watch;
 	LibHalContext *ctx;
 
+	g_return_val_if_fail (drive != NULL, NULL);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), NULL);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -521,6 +529,7 @@
 {
 	BraseroDrivePrivate *priv;
 
+	g_return_val_if_fail (drive != NULL, NULL);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), NULL);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -542,6 +551,7 @@
 {
 	BraseroDrivePrivate *priv;
 
+	g_return_val_if_fail (drive != NULL, NULL);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), NULL);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -565,6 +575,8 @@
 	if (!drive)
 		return NULL;
 
+	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), NULL);
+
 	priv = BRASERO_DRIVE_PRIVATE (drive);
 	return priv->udi;
 }
@@ -609,6 +621,7 @@
 {
 	BraseroDrivePrivate *priv;
 
+	g_return_val_if_fail (drive != NULL, BRASERO_DRIVE_CAPS_NONE);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), BRASERO_DRIVE_CAPS_NONE);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -628,6 +641,7 @@
 {
 	BraseroDrivePrivate *priv;
 
+	g_return_val_if_fail (drive != NULL, FALSE);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), FALSE);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -725,6 +739,7 @@
 {
 	BraseroDrivePrivate *priv;
 
+	g_return_val_if_fail (drive != NULL, FALSE);
 	g_return_val_if_fail (BRASERO_IS_DRIVE (drive), FALSE);
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);
@@ -748,6 +763,7 @@
 	BraseroDrivePrivate *priv;
 	BraseroMedium *medium;
 
+	g_return_if_fail (drive != NULL);
 	g_return_if_fail (BRASERO_IS_DRIVE (drive));
 
 	priv = BRASERO_DRIVE_PRIVATE (drive);

Modified: trunk/libbrasero-media/brasero-medium-monitor.c
==============================================================================
--- trunk/libbrasero-media/brasero-medium-monitor.c	(original)
+++ trunk/libbrasero-media/brasero-medium-monitor.c	Sat Jan 24 14:28:23 2009
@@ -112,6 +112,9 @@
 	GSList *iter;
 	BraseroMediumMonitorPrivate *priv;
 
+	g_return_val_if_fail (monitor != NULL, NULL);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM_MONITOR (monitor), NULL);
+
 	priv = BRASERO_MEDIUM_MONITOR_PRIVATE (monitor);
 	for (iter = priv->drives; iter; iter = iter->next) {
 		BraseroDrive *drive;
@@ -142,6 +145,9 @@
 	GSList *iter;
 	BraseroMediumMonitorPrivate *priv;
 
+	g_return_val_if_fail (monitor != NULL, FALSE);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM_MONITOR (monitor), FALSE);
+
 	priv = BRASERO_MEDIUM_MONITOR_PRIVATE (monitor);
 
 	for (iter = priv->drives; iter; iter = iter->next) {
@@ -175,6 +181,9 @@
 	GSList *drives = NULL;
 	GSList *iter;
 
+	g_return_val_if_fail (monitor != NULL, NULL);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM_MONITOR (monitor), NULL);
+
 	priv = BRASERO_MEDIUM_MONITOR_PRIVATE (monitor);
 
 	for (iter = priv->drives; iter; iter = iter->next) {
@@ -221,6 +230,9 @@
 	GSList *list = NULL;
 	BraseroMediumMonitorPrivate *priv;
 
+	g_return_val_if_fail (monitor != NULL, NULL);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM_MONITOR (monitor), NULL);
+
 	priv = BRASERO_MEDIUM_MONITOR_PRIVATE (monitor);
 
 	for (iter = priv->drives; iter; iter = iter->next) {

Modified: trunk/libbrasero-media/brasero-medium.c
==============================================================================
--- trunk/libbrasero-media/brasero-medium.c	(original)
+++ trunk/libbrasero-media/brasero-medium.c	Sat Jan 24 14:28:23 2009
@@ -253,7 +253,7 @@
  *
  **/
 gchar *
-brasero_medium_get_tooltip (BraseroMedium *self)
+brasero_medium_get_tooltip (BraseroMedium *medium)
 {
 	BraseroMediumPrivate *priv;
 	BraseroDrive *drive;
@@ -262,12 +262,12 @@
 	gchar *label;
 	gchar *name;
 
-	g_return_val_if_fail (self != NULL, NULL);
-	g_return_val_if_fail (BRASERO_IS_MEDIUM (self), NULL);
+	g_return_val_if_fail (medium != NULL, NULL);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), NULL);
 
-	priv = BRASERO_MEDIUM_PRIVATE (self);
+	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
-	media = brasero_medium_get_status (BRASERO_MEDIUM (self));
+	media = brasero_medium_get_status (BRASERO_MEDIUM (medium));
 	if (media & BRASERO_MEDIUM_FILE) {
 		/* Translators: This is a fake drive, a file, and means that
 		 * when we're writing, we're writing to a file and create an
@@ -275,8 +275,8 @@
 		return g_strdup (_("Image File"));
 	}
 
-	type = brasero_medium_get_type_string (BRASERO_MEDIUM (self));
-	drive = brasero_medium_get_drive (BRASERO_MEDIUM (self));
+	type = brasero_medium_get_type_string (BRASERO_MEDIUM (medium));
+	drive = brasero_medium_get_drive (BRASERO_MEDIUM (medium));
 	name = brasero_drive_get_display_name (drive);
 
 	if (media & BRASERO_MEDIUM_BLANK) {
@@ -333,6 +333,9 @@
 {
 	BraseroMediumPrivate *priv;
 
+	g_return_val_if_fail (medium != NULL, NULL);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), NULL);
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 	return priv->type;
 }
@@ -354,6 +357,8 @@
 	if (!medium)
 		return BRASERO_MEDIUM_NONE;
 
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), BRASERO_MEDIUM_NONE);
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 	return priv->info;
 }
@@ -427,6 +432,9 @@
 	BraseroMediumPrivate *priv;
 	BraseroMediumTrack *track = NULL;
 
+	g_return_val_if_fail (medium != NULL, FALSE);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), FALSE);
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
 	for (iter = priv->tracks; iter; iter = iter->next) {
@@ -465,10 +473,13 @@
 guint
 brasero_medium_get_track_num (BraseroMedium *medium)
 {
-	guint retval = 0;
 	GSList *iter;
+	guint retval = 0;
 	BraseroMediumPrivate *priv;
 
+	g_return_val_if_fail (medium != NULL, 0);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), 0);
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 	for (iter = priv->tracks; iter; iter = iter->next) {
 		BraseroMediumTrack *current;
@@ -532,6 +543,9 @@
 	BraseroMediumPrivate *priv;
 	BraseroMediumTrack *track;
 
+	g_return_val_if_fail (medium != NULL, FALSE);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), FALSE);
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
 	track = brasero_medium_get_track (medium, num);
@@ -574,6 +588,9 @@
 	BraseroMediumPrivate *priv;
 	BraseroMediumTrack *track;
 
+	g_return_val_if_fail (medium != NULL, FALSE);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), FALSE);
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
 	track = brasero_medium_get_track (medium, num);
@@ -607,6 +624,9 @@
 {
 	BraseroMediumPrivate *priv;
 
+	g_return_val_if_fail (medium != NULL, 0);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), 0);
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
 	/* There is one exception to this with closed DVD+RW/DVD-RW restricted */
@@ -644,6 +664,9 @@
 {
 	BraseroMediumPrivate *priv;
 
+	g_return_val_if_fail (medium != NULL, 0);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), 0);
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 	return priv->max_wrt * 1000;
 }
@@ -666,6 +689,9 @@
 	guint max = 0;
 	guint i;
 
+	g_return_val_if_fail (medium != NULL, NULL);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), NULL);
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
 	if (!priv->wr_speeds)
@@ -725,6 +751,9 @@
 	BraseroMediumPrivate *priv;
 	BraseroMediumTrack *track = NULL;
 
+	g_return_if_fail (medium != NULL);
+	g_return_if_fail (BRASERO_IS_MEDIUM (medium));
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
 	if (!priv->tracks) {
@@ -774,6 +803,9 @@
 	BraseroMediumPrivate *priv;
 	BraseroMediumTrack *track = NULL;
 
+	g_return_if_fail (medium != NULL);
+	g_return_if_fail (BRASERO_IS_MEDIUM (medium));
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
 	if (!priv->tracks) {
@@ -852,6 +884,9 @@
 {
 	BraseroMediumPrivate *priv;
 
+	g_return_if_fail (medium != NULL);
+	g_return_if_fail (BRASERO_IS_MEDIUM (medium));
+
 	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
 	if (priv->info & BRASERO_MEDIUM_REWRITABLE) {
@@ -3528,12 +3563,15 @@
  *
  **/
 gboolean
-brasero_medium_can_be_written (BraseroMedium *self)
+brasero_medium_can_be_written (BraseroMedium *medium)
 {
 	BraseroMediumPrivate *priv;
 	BraseroDriveCaps caps;
 
-	priv = BRASERO_MEDIUM_PRIVATE (self);
+	g_return_val_if_fail (medium != NULL, FALSE);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), FALSE);
+
+	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
 	if (!(priv->info & BRASERO_MEDIUM_REWRITABLE)
 	&&   (priv->info & BRASERO_MEDIUM_CLOSED))
@@ -3584,12 +3622,15 @@
  *
  **/
 gboolean
-brasero_medium_can_be_rewritten (BraseroMedium *self)
+brasero_medium_can_be_rewritten (BraseroMedium *medium)
 {
 	BraseroMediumPrivate *priv;
 	BraseroDriveCaps caps;
 
-	priv = BRASERO_MEDIUM_PRIVATE (self);
+	g_return_val_if_fail (medium != NULL, FALSE);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), FALSE);
+
+	priv = BRASERO_MEDIUM_PRIVATE (medium);
 
 	if (!(priv->info & BRASERO_MEDIUM_REWRITABLE)
 	||   (priv->info & BRASERO_MEDIUM_FILE))
@@ -3624,14 +3665,16 @@
  *
  **/
 BraseroDrive *
-brasero_medium_get_drive (BraseroMedium *self)
+brasero_medium_get_drive (BraseroMedium *medium)
 {
 	BraseroMediumPrivate *priv;
 
-	if (!self)
+	if (!medium)
 		return NULL;
 
-	priv = BRASERO_MEDIUM_PRIVATE (self);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), NULL);
+
+	priv = BRASERO_MEDIUM_PRIVATE (medium);
 	return priv->drive;
 }
 
@@ -3645,12 +3688,15 @@
  *
  **/
 const gchar *
-brasero_medium_get_CD_TEXT_title (BraseroMedium *self)
+brasero_medium_get_CD_TEXT_title (BraseroMedium *medium)
 {
 	BraseroMediumPrivate *priv;
 
-	priv = BRASERO_MEDIUM_PRIVATE (self);
-	return priv->CD_TEXT_title;;
+	g_return_val_if_fail (medium != NULL, NULL);
+	g_return_val_if_fail (BRASERO_IS_MEDIUM (medium), NULL);
+
+	priv = BRASERO_MEDIUM_PRIVATE (medium);
+	return priv->CD_TEXT_title;
 
 }
 

Modified: trunk/libbrasero-media/brasero-volume.c
==============================================================================
--- trunk/libbrasero-media/brasero-volume.c	(original)
+++ trunk/libbrasero-media/brasero-volume.c	Sat Jan 24 14:28:23 2009
@@ -53,20 +53,32 @@
 
 G_DEFINE_TYPE (BraseroVolume, brasero_volume, BRASERO_TYPE_MEDIUM);
 
+/**
+ * brasero_volume_get_gvolume:
+ * @volume: #BraseroVolume
+ *
+ * Gets the corresponding #GVolume for @Medium.
+ *
+ * Return value: a #GVolume *.
+ *
+ **/
 GVolume *
-brasero_volume_get_gvolume (BraseroVolume *self)
+brasero_volume_get_gvolume (BraseroVolume *volume)
 {
 	const gchar *volume_path = NULL;
 	BraseroVolumePrivate *priv;
 	GVolumeMonitor *monitor;
-	GVolume *volume = NULL;
+	GVolume *gvolume = NULL;
 	BraseroDrive *drive;
 	GList *volumes;
 	GList *iter;
 
-	priv = BRASERO_VOLUME_PRIVATE (self);
+	g_return_val_if_fail (volume != NULL, NULL);
+	g_return_val_if_fail (BRASERO_IS_VOLUME (volume), NULL);
 
-	drive = brasero_medium_get_drive (BRASERO_MEDIUM (self));
+	priv = BRASERO_VOLUME_PRIVATE (volume);
+
+	drive = brasero_medium_get_drive (BRASERO_MEDIUM (volume));
 
 #if defined(HAVE_STRUCT_USCSI_CMD)
 	volume_path = brasero_drive_get_block_device (drive);
@@ -90,7 +102,7 @@
 
 		BRASERO_MEDIA_LOG ("Found volume %s", device_path);
 		if (!strcmp (device_path, volume_path)) {
-			volume = tmp;
+			gvolume = tmp;
 			g_free (device_path);
 			g_object_ref (volume);
 			break;
@@ -101,17 +113,29 @@
 	g_list_foreach (volumes, (GFunc) g_object_unref, NULL);
 	g_list_free (volumes);
 
-	if (!volume)
+	if (!gvolume)
 		BRASERO_MEDIA_LOG ("No volume found for medium");
 
-	return volume;
+	return gvolume;
 }
 
+/**
+ * brasero_volume_is_mounted:
+ * @volume: #BraseroVolume
+ *
+ * Returns whether the volume is currently mounted.
+ *
+ * Return value: a #gboolean. TRUE if it is mounted.
+ *
+ **/
 gboolean
 brasero_volume_is_mounted (BraseroVolume *volume)
 {
 	gchar *path;
 
+	g_return_val_if_fail (volume != NULL, FALSE);
+	g_return_val_if_fail (BRASERO_IS_VOLUME (volume), FALSE);
+
 	/* NOTE: that's the surest way to know if a drive is really mounted. For
 	 * GIO a blank medium can be mounted to burn:/// which is not really 
 	 * what we're interested in. So the mount path must be also local. */
@@ -124,6 +148,16 @@
 	return FALSE;
 }
 
+/**
+ * brasero_volume_get_mount_point:
+ * @volume: #BraseroVolume
+ * @error: #GError **
+ *
+ * Returns the path for mount point for @volume.
+ *
+ * Return value: a #gchar *
+ *
+ **/
 gchar *
 brasero_volume_get_mount_point (BraseroVolume *volume,
 				GError **error)
@@ -134,6 +168,9 @@
 	GMount *mount;
 	GFile *root;
 
+	g_return_val_if_fail (volume != NULL, NULL);
+	g_return_val_if_fail (BRASERO_IS_VOLUME (volume), NULL);
+
 	priv = BRASERO_VOLUME_PRIVATE (volume);
 
 	gvolume = brasero_volume_get_gvolume (volume);
@@ -163,6 +200,18 @@
 	return local_path;
 }
 
+/**
+ * brasero_volume_umount:
+ * @volume: #BraseroVolume
+ * @wait: #gboolean
+ * @error: #GError **
+ *
+ * Unmount @volume. If wait is set to TRUE, then block (in a GMainLoop) until
+ * the operation finishes.
+ *
+ * Return value: a #gboolean. TRUE if the operation succeeded.
+ *
+ **/
 gboolean
 brasero_volume_umount (BraseroVolume *volume,
 		       gboolean wait,
@@ -175,6 +224,8 @@
 	if (!volume)
 		return TRUE;
 
+	g_return_val_if_fail (BRASERO_IS_VOLUME (volume), FALSE);
+
 	priv = BRASERO_VOLUME_PRIVATE (volume);
 
 	gvolume = brasero_volume_get_gvolume (volume);
@@ -190,6 +241,21 @@
 	return result;
 }
 
+/**
+ * brasero_volume_mount:
+ * @volume: #BraseroVolume *
+ * @parent_window: #GtkWindow *
+ * @wait: #gboolean
+ * @error: #GError **
+ *
+ * Mount @volume. If wait is set to TRUE, then block (in a GMainLoop) until
+ * the operation finishes.
+ * @parent_window is used if an authentification is needed. Then the authentification
+ * dialog will be set modal.
+ *
+ * Return value: a #gboolean. TRUE if the operation succeeded.
+ *
+ **/
 gboolean
 brasero_volume_mount (BraseroVolume *volume,
 		      GtkWindow *parent_window,
@@ -203,6 +269,8 @@
 	if (!volume)
 		return TRUE;
 
+	g_return_val_if_fail (BRASERO_IS_VOLUME (volume), FALSE);
+
 	priv = BRASERO_VOLUME_PRIVATE (volume);
 
 	gvolume = brasero_volume_get_gvolume (volume);
@@ -219,57 +287,90 @@
 	return result;
 }
 
+/**
+ * brasero_volume_cancel_current_operation:
+ * @volume: #BraseroVolume *
+ *
+ * Cancels all operations currently running for @volume
+ *
+ **/
 void
-brasero_volume_cancel_current_operation (BraseroVolume *self)
+brasero_volume_cancel_current_operation (BraseroVolume *volume)
 {
 	BraseroVolumePrivate *priv;
 
-	priv = BRASERO_VOLUME_PRIVATE (self);	
+	g_return_if_fail (volume != NULL);
+	g_return_if_fail (BRASERO_IS_VOLUME (volume));
+
+	priv = BRASERO_VOLUME_PRIVATE (volume);	
 	g_cancellable_cancel (priv->cancel);
 }
 
+/**
+ * brasero_volume_get_icon:
+ * @volume: #BraseroVolume *
+ *
+ * Returns a GIcon pointer for the volume.
+ *
+ * Return value: a #GIcon*
+ *
+ **/
 GIcon *
-brasero_volume_get_icon (BraseroVolume *self)
+brasero_volume_get_icon (BraseroVolume *volume)
 {
-	GVolume *volume;
+	GVolume *gvolume;
 	GMount *mount;
 	GIcon *icon;
 
-	if (!self)
+	if (!volume)
 		return g_themed_icon_new_with_default_fallbacks ("drive-optical");
 
-	if (brasero_medium_get_status (BRASERO_MEDIUM (self)) == BRASERO_MEDIUM_FILE)
+	g_return_val_if_fail (BRASERO_IS_VOLUME (volume), NULL);
+
+	if (brasero_medium_get_status (BRASERO_MEDIUM (volume)) == BRASERO_MEDIUM_FILE)
 		return g_themed_icon_new_with_default_fallbacks ("iso-image-new");
 
-	volume = brasero_volume_get_gvolume (self);
-	if (!volume)
+	gvolume = brasero_volume_get_gvolume (volume);
+	if (!gvolume)
 		return g_themed_icon_new_with_default_fallbacks ("drive-optical");
 
-	mount = g_volume_get_mount (volume);
+	mount = g_volume_get_mount (gvolume);
 	if (mount) {
 		icon = g_mount_get_icon (mount);
 		g_object_unref (mount);
 	}
 	else
-		icon = g_volume_get_icon (volume);
+		icon = g_volume_get_icon (gvolume);
 
-	g_object_unref (volume);
+	g_object_unref (gvolume);
 
 	return icon;
 }
 
+/**
+ * brasero_volume_get_name:
+ * @volume: #BraseroVolume *
+ *
+ * Returns a string that can be displayed to represent the volumeÂ
+ *
+ * Return value: a #gchar *. Free when not needed anymore.
+ *
+ **/
 gchar *
-brasero_volume_get_name (BraseroVolume *self)
+brasero_volume_get_name (BraseroVolume *volume)
 {
 	BraseroVolumePrivate *priv;
 	BraseroMedia media;
 	const gchar *type;
-	GVolume *volume;
+	GVolume *gvolume;
 	gchar *name;
 
-	priv = BRASERO_VOLUME_PRIVATE (self);
+	g_return_val_if_fail (volume != NULL, NULL);
+	g_return_val_if_fail (BRASERO_IS_VOLUME (volume), NULL);
 
-	media = brasero_medium_get_status (BRASERO_MEDIUM (self));
+	priv = BRASERO_VOLUME_PRIVATE (volume);
+
+	media = brasero_medium_get_status (BRASERO_MEDIUM (volume));
 	if (media & BRASERO_MEDIUM_FILE) {
 		/* Translators: This is a fake drive, a file, and means that
 		 * when we're writing, we're writing to a file and create an
@@ -280,24 +381,24 @@
 	if (media & BRASERO_MEDIUM_HAS_AUDIO) {
 		const gchar *audio_name;
 
-		audio_name = brasero_medium_get_CD_TEXT_title (BRASERO_MEDIUM (self));
+		audio_name = brasero_medium_get_CD_TEXT_title (BRASERO_MEDIUM (volume));
 		if (audio_name)
 			return g_strdup (audio_name);
 	}
 
-	volume = brasero_volume_get_gvolume (self);
-	if (!volume)
+	gvolume = brasero_volume_get_gvolume (volume);
+	if (!gvolume)
 		goto last_chance;
 
-	name = g_volume_get_name (volume);
-	g_object_unref (volume);
+	name = g_volume_get_name (gvolume);
+	g_object_unref (gvolume);
 
 	if (name)
 		return name;
 
 last_chance:
 
-	type = brasero_medium_get_type_string (BRASERO_MEDIUM (self));
+	type = brasero_medium_get_type_string (BRASERO_MEDIUM (volume));
 	name = NULL;
 	if (media & BRASERO_MEDIUM_BLANK) {
 		/* NOTE for translators: the first %s is the disc type. */
@@ -358,6 +459,10 @@
 	object_class->finalize = brasero_volume_finalize;
 }
 
+/**
+ * This is private API defined in brasero-drive.c
+ */
+
 BraseroVolume *
 brasero_volume_new (BraseroDrive *drive,
 		    const gchar *udi)