[brasero] More API documentation

[Philippe Rouquier <philippr src gnome org>]

commit caa77fa8d6aacccfbcd18b1aedd46ff75ac54ece
Author: Philippe Rouquier <bonfire-app wanadoo fr>
Date:   Sun Aug 9 21:04:07 2009 +0200

    More API documentation
    Fix header declarations

 libbrasero-burn/brasero-status.c       |   90 ++++++++++++++
 libbrasero-burn/brasero-track-data.c   |    3 +
 libbrasero-burn/brasero-track-disc.c   |    3 +
 libbrasero-burn/brasero-track-image.c  |    4 +-
 libbrasero-burn/brasero-track-stream.c |    3 +
 libbrasero-burn/brasero-track-type.c   |  203 +++++++++++++++++++++++++++++++-
 libbrasero-burn/brasero-track-type.h   |    3 +-
 7 files changed, 306 insertions(+), 3 deletions(-)
---
diff --git a/libbrasero-burn/brasero-status.c b/libbrasero-burn/brasero-status.c
index e9c3a22..ea7f007 100644
--- a/libbrasero-burn/brasero-status.c
+++ b/libbrasero-burn/brasero-status.c
@@ -43,12 +43,29 @@ struct _BraseroStatus {
 	gchar *current_action;
 };
 
+/**
+ * brasero_status_new:
+ *
+ * Creates a new #BraseroStatus structure.
+ * Free it with brasero_status_free ().
+ *
+ * Return value: a #BraseroStatus pointer.
+ **/
+
 BraseroStatus *
 brasero_status_new (void)
 {
 	return g_new0 (BraseroStatus, 1);
 }
 
+/**
+ * brasero_status_free:
+ * @status: a #BraseroStatus.
+ *
+ * Frees #BraseroStatus structure.
+ *
+ **/
+
 void
 brasero_status_free (BraseroStatus *status)
 {
@@ -61,6 +78,19 @@ brasero_status_free (BraseroStatus *status)
 	g_free (status);
 }
 
+/**
+ * brasero_status_get_result:
+ * @status: a #BraseroStatus.
+ *
+ * After an object (see brasero_burn_track_get_status ()) has
+ * been requested its status, this function returns that status.
+ *
+ * Return value: a #BraseroBurnResult.
+ * BRASERO_BURN_OK if the object is ready.
+ * BRASERO_BURN_NOT_READY if some time should be given to the object before it is ready.
+ * BRASERO_BURN_ERR if there is an error.
+ **/
+
 BraseroBurnResult
 brasero_status_get_result (BraseroStatus *status)
 {
@@ -68,6 +98,16 @@ brasero_status_get_result (BraseroStatus *status)
 	return status->res;
 }
 
+/**
+ * brasero_status_get_progress:
+ * @status: a #BraseroStatus.
+ *
+ * If brasero_status_get_result () returned BRASERO_BURN_NOT_READY,
+ * this function returns the progress regarding the operation completion.
+ *
+ * Return value: a #gdouble
+ **/
+
 gdouble
 brasero_status_get_progress (BraseroStatus *status)
 {
@@ -81,6 +121,16 @@ brasero_status_get_progress (BraseroStatus *status)
 	return status->progress;
 }
 
+/**
+ * brasero_status_get_error:
+ * @status: a #BraseroStatus.
+ *
+ * If brasero_status_get_result () returned BRASERO_BURN_ERR,
+ * this function returns the error.
+ *
+ * Return value: a #GError
+ **/
+
 GError *
 brasero_status_get_error (BraseroStatus *status)
 {
@@ -91,6 +141,17 @@ brasero_status_get_error (BraseroStatus *status)
 	return g_error_copy (status->error);
 }
 
+/**
+ * brasero_status_get_current_action:
+ * @status: a #BraseroStatus.
+ *
+ * If brasero_status_get_result () returned BRASERO_BURN_NOT_READY,
+ * this function returns a string describing the operation currently performed.
+ * Free the string when it is not needed anymore.
+ *
+ * Return value: a #gchar.
+ **/
+
 gchar *
 brasero_status_get_current_action (BraseroStatus *status)
 {
@@ -105,6 +166,14 @@ brasero_status_get_current_action (BraseroStatus *status)
 
 }
 
+/**
+ * brasero_status_set_completed:
+ * @status: a #BraseroStatus.
+ *
+ * Sets the status for a request to BRASERO_BURN_OK.
+ *
+ **/
+
 void
 brasero_status_set_completed (BraseroStatus *status)
 {
@@ -113,6 +182,18 @@ brasero_status_set_completed (BraseroStatus *status)
 	status->progress = 1.0;
 }
 
+/**
+ * brasero_status_set_not_ready:
+ * @status: a #BraseroStatus.
+ * @progress: a #gdouble or -1.0.
+ * @current_action: a #gchar or NULL.
+ *
+ * Sets the status for a request to BRASERO_BURN_NOT_READY.
+ * Allows to set a string describing the operation currently performed
+ * as well as the progress regarding the operation completion.
+ *
+ **/
+
 void
 brasero_status_set_not_ready (BraseroStatus *status,
 			      gdouble progress,
@@ -127,6 +208,15 @@ brasero_status_set_not_ready (BraseroStatus *status,
 	status->current_action = g_strdup (current_action);
 }
 
+/**
+ * brasero_status_set_error:
+ * @status: a #BraseroStatus.
+ * @error: a #GError or NULL.
+ *
+ * Sets the status for a request to BRASERO_BURN_ERR.
+ *
+ **/
+
 void
 brasero_status_set_error (BraseroStatus *status,
 			  GError *error)
diff --git a/libbrasero-burn/brasero-track-data.c b/libbrasero-burn/brasero-track-data.c
index f47561f..e31cd3e 100644
--- a/libbrasero-burn/brasero-track-data.c
+++ b/libbrasero-burn/brasero-track-data.c
@@ -614,6 +614,9 @@ brasero_track_data_class_init (BraseroTrackDataClass *klass)
  * brasero_track_data_new:
  *
  * Creates a new #BraseroTrackData.
+ * 
+ *This type of tracks is used to create a disc image
+ * from or burn a selection of files.
  *
  * Return value: a #BraseroTrackData
  **/
diff --git a/libbrasero-burn/brasero-track-disc.c b/libbrasero-burn/brasero-track-disc.c
index 23ffe9b..e10d7b9 100644
--- a/libbrasero-burn/brasero-track-disc.c
+++ b/libbrasero-burn/brasero-track-disc.c
@@ -302,6 +302,9 @@ brasero_track_disc_class_init (BraseroTrackDiscClass *klass)
  *
  * Creates a new #BraseroTrackDisc object.
  *
+ * This type of tracks is used to copy media either
+ * to a disc image file or to another medium.
+ *
  * Return value: a #BraseroTrackDisc.
  **/
 
diff --git a/libbrasero-burn/brasero-track-image.c b/libbrasero-burn/brasero-track-image.c
index 9be677d..4fbd69f 100644
--- a/libbrasero-burn/brasero-track-image.c
+++ b/libbrasero-burn/brasero-track-image.c
@@ -367,7 +367,9 @@ brasero_track_image_class_init (BraseroTrackImageClass *klass)
 /**
  * brasero_track_image_new:
  *
- *  Creates a new #BraseroTrackImage object.
+ * Creates a new #BraseroTrackImage object.
+ *
+ * This type of tracks is used to burn disc images.
  *
  * Return value: a #BraseroTrackImage object.
  **/
diff --git a/libbrasero-burn/brasero-track-stream.c b/libbrasero-burn/brasero-track-stream.c
index 9ea4687..4916377 100644
--- a/libbrasero-burn/brasero-track-stream.c
+++ b/libbrasero-burn/brasero-track-stream.c
@@ -462,6 +462,9 @@ brasero_track_stream_class_init (BraseroTrackStreamClass *klass)
  *
  *  Creates a new #BraseroTrackStream object.
  *
+ * This type of tracks is used to burn audio or
+ * video files.
+ *
  * Return value: a #BraseroTrackStream object.
  **/
 
diff --git a/libbrasero-burn/brasero-track-type.c b/libbrasero-burn/brasero-track-type.c
index 35b0423..c03349e 100644
--- a/libbrasero-burn/brasero-track-type.c
+++ b/libbrasero-burn/brasero-track-type.c
@@ -39,12 +39,29 @@
 #include "brasero-track-type.h"
 #include "brasero-track-type-private.h"
 
+/**
+ * brasero_track_type_new:
+ *
+ * Creates a new #BraseroTrackType structure.
+ * Free it with brasero_track_type_free ().
+ *
+ * Return value: a #BraseroTrackType pointer.
+ **/
+
 BraseroTrackType *
 brasero_track_type_new (void)
 {
 	return g_new0 (BraseroTrackType, 1);
 }
 
+/**
+ * brasero_track_type_free:
+ * @type: a #BraseroTrackType.
+ *
+ * Frees #BraseroTrackType structure.
+ *
+ **/
+
 void
 brasero_track_type_free (BraseroTrackType *type)
 {
@@ -54,6 +71,17 @@ brasero_track_type_free (BraseroTrackType *type)
 	g_free (type);
 }
 
+/**
+ * brasero_track_type_get_image_format:
+ * @type: a #BraseroTrackType.
+ *
+ * Returns the format of an image when
+ * brasero_track_type_get_has_image () returned
+ * TRUE.
+ *
+ * Return value: a #BraseroImageFormat
+ **/
+
 BraseroImageFormat
 brasero_track_type_get_image_format (const BraseroTrackType *type) 
 {
@@ -65,6 +93,17 @@ brasero_track_type_get_image_format (const BraseroTrackType *type)
 	return type->subtype.img_format;
 }
 
+/**
+ * brasero_track_type_get_data_fs:
+ * @type: a #BraseroTrackType.
+ *
+ * Returns the parameters for the image generation
+ * when brasero_track_type_get_has_data () returned
+ * TRUE.
+ *
+ * Return value: a #BraseroImageFS
+ **/
+
 BraseroImageFS
 brasero_track_type_get_data_fs (const BraseroTrackType *type) 
 {
@@ -76,6 +115,17 @@ brasero_track_type_get_data_fs (const BraseroTrackType *type)
 	return type->subtype.fs_type;
 }
 
+/**
+ * brasero_track_type_get_stream_format:
+ * @type: a #BraseroTrackType.
+ *
+ * Returns the format for a stream (song or video)
+ * when brasero_track_type_get_has_stream () returned
+ * TRUE.
+ *
+ * Return value: a #BraseroStreamFormat
+ **/
+
 BraseroStreamFormat
 brasero_track_type_get_stream_format (const BraseroTrackType *type) 
 {
@@ -87,6 +137,17 @@ brasero_track_type_get_stream_format (const BraseroTrackType *type)
 	return type->subtype.stream_format;
 }
 
+/**
+ * brasero_track_type_get_medium_type:
+ * @type: a #BraseroTrackType.
+ *
+ * Returns the medium type
+ * when brasero_track_type_get_has_medium () returned
+ * TRUE.
+ *
+ * Return value: a #BraseroMedia
+ **/
+
 BraseroMedia
 brasero_track_type_get_medium_type (const BraseroTrackType *type) 
 {
@@ -98,6 +159,16 @@ brasero_track_type_get_medium_type (const BraseroTrackType *type)
 	return type->subtype.media;
 }
 
+/**
+ * brasero_track_type_set_image_format:
+ * @type: a #BraseroTrackType.
+ * @format: a #BraseroImageFormat
+ *
+ * Sets the #BraseroImageFormat. Must be called
+ * after brasero_track_type_set_has_image ().
+ *
+ **/
+
 void
 brasero_track_type_set_image_format (BraseroTrackType *type,
 				     BraseroImageFormat format) 
@@ -110,6 +181,16 @@ brasero_track_type_set_image_format (BraseroTrackType *type,
 	type->subtype.img_format = format;
 }
 
+/**
+ * brasero_track_type_set_data_fs:
+ * @type: a #BraseroTrackType.
+ * @fs_type: a #BraseroImageFS
+ *
+ * Sets the #BraseroImageFS. Must be called
+ * after brasero_track_type_set_has_data ().
+ *
+ **/
+
 void
 brasero_track_type_set_data_fs (BraseroTrackType *type,
 				BraseroImageFS fs_type) 
@@ -122,9 +203,19 @@ brasero_track_type_set_data_fs (BraseroTrackType *type,
 	type->subtype.fs_type = fs_type;
 }
 
+/**
+ * brasero_track_type_set_stream_format:
+ * @type: a #BraseroTrackType.
+ * @format: a #BraseroImageFormat
+ *
+ * Sets the #BraseroStreamFormat. Must be called
+ * after brasero_track_type_set_has_stream ().
+ *
+ **/
+
 void
 brasero_track_type_set_stream_format (BraseroTrackType *type,
-				      BraseroImageFormat format) 
+				      BraseroStreamFormat format) 
 {
 	g_return_if_fail (type != NULL);
 
@@ -134,6 +225,16 @@ brasero_track_type_set_stream_format (BraseroTrackType *type,
 	type->subtype.stream_format = format;
 }
 
+/**
+ * brasero_track_type_set_medium_type:
+ * @type: a #BraseroTrackType.
+ * @media: a #BraseroMedia
+ *
+ * Sets the #BraseroMedia. Must be called
+ * after brasero_track_type_set_has_medium ().
+ *
+ **/
+
 void
 brasero_track_type_set_medium_type (BraseroTrackType *type,
 				    BraseroMedia media) 
@@ -146,6 +247,15 @@ brasero_track_type_set_medium_type (BraseroTrackType *type,
 	type->subtype.media = media;
 }
 
+/**
+ * brasero_track_type_is_empty:
+ * @type: a #BraseroTrackType.
+ *
+ * Returns TRUE if no type was set.
+ *
+ * Return value: a #gboolean
+ **/
+
 gboolean
 brasero_track_type_is_empty (const BraseroTrackType *type)
 {
@@ -154,6 +264,15 @@ brasero_track_type_is_empty (const BraseroTrackType *type)
 	return (type->type == BRASERO_TRACK_TYPE_NONE);
 }
 
+/**
+ * brasero_track_type_get_has_data:
+ * @type: a #BraseroTrackType.
+ *
+ * Returns TRUE if DATA type (see brasero_track_data_new ()) was set.
+ *
+ * Return value: a #gboolean
+ **/
+
 gboolean
 brasero_track_type_get_has_data (const BraseroTrackType *type)
 {
@@ -162,6 +281,15 @@ brasero_track_type_get_has_data (const BraseroTrackType *type)
 	return type->type == BRASERO_TRACK_TYPE_DATA;
 }
 
+/**
+ * brasero_track_type_get_has_image:
+ * @type: a #BraseroTrackType.
+ *
+ * Returns TRUE if IMAGE type (see brasero_track_image_new ()) was set.
+ *
+ * Return value: a #gboolean
+ **/
+
 gboolean
 brasero_track_type_get_has_image (const BraseroTrackType *type)
 {
@@ -170,6 +298,15 @@ brasero_track_type_get_has_image (const BraseroTrackType *type)
 	return type->type == BRASERO_TRACK_TYPE_IMAGE;
 }
 
+/**
+ * brasero_track_type_get_has_image:
+ * @type: a #BraseroTrackType.
+ *
+ * Returns TRUE if IMAGE type (see brasero_track_stream_new ()) was set.
+ *
+ * Return value: a #gboolean
+ **/
+
 gboolean
 brasero_track_type_get_has_stream (const BraseroTrackType *type)
 {
@@ -178,6 +315,15 @@ brasero_track_type_get_has_stream (const BraseroTrackType *type)
 	return type->type == BRASERO_TRACK_TYPE_STREAM;
 }
 
+/**
+ * brasero_track_type_get_has_medium:
+ * @type: a #BraseroTrackType.
+ *
+ * Returns TRUE if MEDIUM type (see brasero_track_disc_new ()) was set.
+ *
+ * Return value: a #gboolean
+ **/
+
 gboolean
 brasero_track_type_get_has_medium (const BraseroTrackType *type)
 {
@@ -186,6 +332,14 @@ brasero_track_type_get_has_medium (const BraseroTrackType *type)
 	return type->type == BRASERO_TRACK_TYPE_DISC;
 }
 
+/**
+ * brasero_track_type_set_has_data:
+ * @type: a #BraseroTrackType.
+ *
+ * Set DATA type for @type.
+ *
+ **/
+
 void
 brasero_track_type_set_has_data (BraseroTrackType *type)
 {
@@ -194,6 +348,14 @@ brasero_track_type_set_has_data (BraseroTrackType *type)
 	type->type = BRASERO_TRACK_TYPE_DATA;
 }
 
+/**
+ * brasero_track_type_set_has_image:
+ * @type: a #BraseroTrackType.
+ *
+ * Set IMAGE type for @type.
+ *
+ **/
+
 void
 brasero_track_type_set_has_image (BraseroTrackType *type)
 {
@@ -202,6 +364,14 @@ brasero_track_type_set_has_image (BraseroTrackType *type)
 	type->type = BRASERO_TRACK_TYPE_IMAGE;
 }
 
+/**
+ * brasero_track_type_set_has_stream:
+ * @type: a #BraseroTrackType.
+ *
+ * Set STREAM type for @type
+ *
+ **/
+
 void
 brasero_track_type_set_has_stream (BraseroTrackType *type)
 {
@@ -210,6 +380,14 @@ brasero_track_type_set_has_stream (BraseroTrackType *type)
 	type->type = BRASERO_TRACK_TYPE_STREAM;
 }
 
+/**
+ * brasero_track_type_set_has_medium:
+ * @type: a #BraseroTrackType.
+ *
+ * Set MEDIUM type for @type.
+ *
+ **/
+
 void
 brasero_track_type_set_has_medium (BraseroTrackType *type)
 {
@@ -218,6 +396,17 @@ brasero_track_type_set_has_medium (BraseroTrackType *type)
 	type->type = BRASERO_TRACK_TYPE_DISC;
 }
 
+/**
+ * brasero_track_type_equal:
+ * @type_A: a #BraseroTrackType.
+ * @type_B: a #BraseroTrackType.
+ *
+ * Returns TRUE if @type_A and @type_B represents
+ * the same type and subtype.
+ *
+ * Return value: a #gboolean
+ **/
+
 gboolean
 brasero_track_type_equal (const BraseroTrackType *type_A,
 			  const BraseroTrackType *type_B)
@@ -256,6 +445,18 @@ brasero_track_type_equal (const BraseroTrackType *type_A,
 	return TRUE;
 }
 
+/**
+ * brasero_track_type_match:
+ * @type_A: a #BraseroTrackType.
+ * @type_B: a #BraseroTrackType.
+ *
+ * Returns TRUE if @type_A and @type_B match.
+ *
+ * (Used internally)
+ *
+ * Return value: a #gboolean
+ **/
+
 gboolean
 brasero_track_type_match (const BraseroTrackType *type_A,
 			  const BraseroTrackType *type_B)
diff --git a/libbrasero-burn/brasero-track-type.h b/libbrasero-burn/brasero-track-type.h
index 66ecbe4..0c51554 100644
--- a/libbrasero-burn/brasero-track-type.h
+++ b/libbrasero-burn/brasero-track-type.h
@@ -34,6 +34,7 @@
 #include <glib.h>
 
 #include <brasero-enums.h>
+#include <brasero-media.h>
 
 G_BEGIN_DECLS
 
@@ -85,7 +86,7 @@ brasero_track_type_get_data_fs (const BraseroTrackType *type);
 
 void
 brasero_track_type_set_stream_format (BraseroTrackType *type,
-				      BraseroImageFormat format);
+				      BraseroStreamFormat format);
 void
 brasero_track_type_set_image_format (BraseroTrackType *type,
 				     BraseroImageFormat format);