GNOME.org
 

[brasero] Some more API documentation

commit 6bb85dc1e3a41000f7e8eb75c6fc2e5eae653191
Author: Philippe Rouquier <bonfire-app wanadoo fr>
Date:   Sat Aug 8 20:16:36 2009 +0200

    Some more API documentation

 .../libbrasero-burn/libbrasero-burn-sections.txt   |   11 +--
 libbrasero-burn/brasero-burn.c                     |   96 +++++++++++++++++++-
 libbrasero-burn/brasero-burn.h                     |    2 +-
 libbrasero-burn/brasero-session-span.c             |   61 +++++++++++++
 libbrasero-burn/brasero-track.h                    |    8 --
 5 files changed, 158 insertions(+), 20 deletions(-)
---
diff --git a/docs/reference/libbrasero-burn/libbrasero-burn-sections.txt b/docs/reference/libbrasero-burn/libbrasero-burn-sections.txt
index ae0b86b..6833c7e 100644
--- a/docs/reference/libbrasero-burn/libbrasero-burn-sections.txt
+++ b/docs/reference/libbrasero-burn/libbrasero-burn-sections.txt
@@ -84,6 +84,7 @@ BRASERO_SUM_DIALOG_GET_CLASS
 <FILE>brasero-session</FILE>
 <TITLE>BraseroBurnSession</TITLE>
 BraseroBurnSession
+BraseroBurnSessionClass
 brasero_burn_session_new
 brasero_burn_session_add_track
 brasero_burn_session_move_track
@@ -106,10 +107,6 @@ brasero_burn_session_remove_flag
 brasero_burn_session_get_flags
 brasero_burn_session_set_tmpdir
 brasero_burn_session_get_tmpdir
-brasero_burn_session_push_settings
-brasero_burn_session_pop_settings
-brasero_burn_session_push_tracks
-brasero_burn_session_pop_tracks
 brasero_burn_session_get_burn_flags
 brasero_burn_session_get_blank_flags
 brasero_burn_session_can_blank
@@ -119,12 +116,6 @@ brasero_burn_session_output_supported
 brasero_burn_session_get_required_media_type
 brasero_burn_session_get_possible_output_formats
 brasero_burn_session_get_default_output_format
-brasero_burn_session_get_log_path
-brasero_burn_session_set_log_path
-brasero_burn_session_start
-brasero_burn_session_stop
-brasero_burn_session_logv
-brasero_burn_session_log
 brasero_burn_session_get_label
 brasero_burn_session_set_label
 brasero_burn_session_set_rate
diff --git a/libbrasero-burn/brasero-burn.c b/libbrasero-burn/brasero-burn.c
index 571d34e..8a66d68 100644
--- a/libbrasero-burn/brasero-burn.c
+++ b/libbrasero-burn/brasero-burn.c
@@ -161,6 +161,14 @@ brasero_burn_powermanagement (BraseroBurn *self,
 		brasero_uninhibit_suspend (priv->appcookie); 
 }
 
+/**
+ * brasero_burn_new:
+ *
+ *  Creates a new #BraseroBurn object.
+ *
+ * Return value: a #BraseroBurn object.
+ **/
+
 BraseroBurn *
 brasero_burn_new ()
 {
@@ -1181,6 +1189,20 @@ brasero_burn_action_changed (BraseroTask *task,
 	brasero_burn_action_changed_real (burn, action);
 }
 
+/**
+ * brasero_burn_get_action_string:
+ * @burn: a #BraseroBurn
+ * @action: a #BraseroBurnAction
+ * @string: a #gchar **
+ *
+ * This function returns the current action (in @string)  of
+ * an ongoing operation performed by @burn.
+ * @action is used to set a default string in case there was
+ * no string set by the backend to describe the current
+ * operation.
+ *
+ **/
+
 void
 brasero_burn_get_action_string (BraseroBurn *burn,
 				BraseroBurnAction action,
@@ -1200,6 +1222,24 @@ brasero_burn_get_action_string (BraseroBurn *burn,
 							    string);
 }
 
+/**
+ * brasero_burn_status:
+ * @burn: a #BraseroBurn
+ * @media: a #BraseroMedia or NULL
+ * @isosize: a #goffset or NULL
+ * @written: a #goffset or NULL
+ * @rate: a #guint64 or NULL
+ *
+ * Returns various information about the current operation 
+ * in @media (the current media type being burnt),
+ * @isosize (the size of the data being burnt), @written (the
+ * number of bytes having been written so far) and @rate
+ * (the speed at which data are written).
+ *
+ * Return value: a #BraseroBurnResult. BRASERO_BURN_OK if there is
+ * an ongoing operation; BRASERO_BURN_NOT_READY otherwise.
+ **/
+
 BraseroBurnResult
 brasero_burn_status (BraseroBurn *burn,
 		     BraseroMedia *media,
@@ -1692,7 +1732,7 @@ start:
 	return BRASERO_BURN_ERR;
 }
 
-/* FIXME: for the moment we don't allow for mixed CD type */
+/* FIXME: at the moment we don't allow for mixed CD type */
 static BraseroBurnResult
 brasero_burn_run_tasks (BraseroBurn *burn,
 			gboolean erase_allowed,
@@ -2256,6 +2296,20 @@ brasero_burn_record_session (BraseroBurn *burn,
 	return result;
 }
 
+/**
+ * brasero_burn_check:
+ * @burn: a #BraseroBurn
+ * @session: a #BraseroBurnSession
+ * @error: a #GError
+ *
+ * Checks the integrity of a medium according to the parameters
+ * set in @session. The medium must be inserted in the #BraseroDrive
+ * set as the source of a #BraseroTrackDisc track inserted in @session.
+ *
+ * Return value: a #BraseroBurnResult. The result of the operation. 
+ * BRASERO_BURN_OK if it was successful.
+ **/
+
 BraseroBurnResult
 brasero_burn_check (BraseroBurn *self,
 		    BraseroBurnSession *session,
@@ -2515,6 +2569,19 @@ again:
 	return BRASERO_BURN_OK;
 }
 
+/**
+ * brasero_burn_record:
+ * @burn: a #BraseroBurn
+ * @session: a #BraseroBurnSession
+ * @error: a #GError
+ *
+ * Burns or creates a disc image according to the parameters
+ * set in @session.
+ *
+ * Return value: a #BraseroBurnResult. The result of the operation. 
+ * BRASERO_BURN_OK if it was successful.
+ **/
+
 BraseroBurnResult 
 brasero_burn_record (BraseroBurn *burn,
 		     BraseroBurnSession *session,
@@ -2668,6 +2735,20 @@ brasero_burn_blank_real (BraseroBurn *burn, GError **error)
 	return result;
 }
 
+/**
+ * brasero_burn_blank:
+ * @burn: a #BraseroBurn
+ * @session: a #BraseroBurnSession
+ * @error: a #GError
+ *
+ * Blanks a medium according to the parameters
+ * set in @session. The medium must be inserted in the #BraseroDrive
+ * set with brasero_burn_session_set_burner ().
+ *
+ * Return value: a #BraseroBurnResult. The result of the operation. 
+ * BRASERO_BURN_OK if it was successful.
+ **/
+
 BraseroBurnResult
 brasero_burn_blank (BraseroBurn *burn,
 		    BraseroBurnSession *session,
@@ -2735,6 +2816,19 @@ end:
 	return result;
 }
 
+/**
+ * brasero_burn_cancel:
+ * @burn: a #BraseroBurn
+ * @protect: a #gboolean
+ *
+ * Cancels any ongoing operation. If @protect is TRUE then
+ * cancellation will not take place for a "critical" task, a task whose interruption
+ * could damage the medium or the drive.
+ *
+ * Return value: a #BraseroBurnResult. The result of the operation. 
+ * BRASERO_BURN_OK if it was successful.
+ **/
+
 BraseroBurnResult
 brasero_burn_cancel (BraseroBurn *burn, gboolean protect)
 {
diff --git a/libbrasero-burn/brasero-burn.h b/libbrasero-burn/brasero-burn.h
index e04fbbf..741b47c 100644
--- a/libbrasero-burn/brasero-burn.h
+++ b/libbrasero-burn/brasero-burn.h
@@ -107,7 +107,7 @@ brasero_burn_cancel (BraseroBurn *burn,
 
 BraseroBurnResult
 brasero_burn_status (BraseroBurn *burn,
-		     BraseroMedia *info,
+		     BraseroMedia *media,
 		     goffset *isosize,
 		     goffset *written,
 		     guint64 *rate);
diff --git a/libbrasero-burn/brasero-session-span.c b/libbrasero-burn/brasero-session-span.c
index 6c35d95..976e101 100644
--- a/libbrasero-burn/brasero-session-span.c
+++ b/libbrasero-burn/brasero-session-span.c
@@ -82,6 +82,17 @@ brasero_session_span_get_available_medium_space (BraseroSessionSpan *session)
 	return available_blocks;
 }
 
+/**
+ * brasero_session_span_again:
+ * @session: a #BraseroSessionSpan
+ *
+ * Checks whether some data were not included during calls to brasero_session_span_next ().
+ *
+ * Return value: a #BraseroBurnResult. BRASERO_BURN_OK if there is not anymore data.
+ * BRASERO_BURN_RETRY if the operation was successful and a new #BraseroTrackDataCfg was created.
+ * BRASERO_BURN_ERR otherwise.
+ **/
+
 BraseroBurnResult
 brasero_session_span_again (BraseroSessionSpan *session)
 {
@@ -116,6 +127,19 @@ brasero_session_span_again (BraseroSessionSpan *session)
 	return (tracks != NULL)? BRASERO_BURN_RETRY:BRASERO_BURN_OK;
 }
 
+/**
+ * brasero_session_span_possible:
+ * @session: a #BraseroSessionSpan
+ *
+ * Checks if a new #BraseroTrackData can be created from the files remaining in the tree 
+ * after calls to brasero_session_span_next (). The maximum size of the data will be the one
+ * of the medium inserted in the #BraseroDrive set for @session (see brasero_burn_session_set_burner ()).
+ *
+ * Return value: a #BraseroBurnResult. BRASERO_BURN_OK if there is not anymore data.
+ * BRASERO_BURN_RETRY if the operation was successful and a new #BraseroTrackDataCfg was created.
+ * BRASERO_BURN_ERR otherwise.
+ **/
+
 BraseroBurnResult
 brasero_session_span_possible (BraseroSessionSpan *session)
 {
@@ -165,6 +189,16 @@ brasero_session_span_possible (BraseroSessionSpan *session)
 	return BRASERO_BURN_RETRY;
 }
 
+/**
+ * brasero_session_span_start:
+ * @session: a #BraseroSessionSpan
+ *
+ * Get the object ready for spanning a #BraseroBurnSession object. This function
+ * must be called before brasero_session_span_next ().
+ *
+ * Return value: a #BraseroBurnResult. BRASERO_BURN_OK if successful.
+ **/
+
 BraseroBurnResult
 brasero_session_span_start (BraseroSessionSpan *session)
 {
@@ -183,6 +217,17 @@ brasero_session_span_start (BraseroSessionSpan *session)
 	return BRASERO_BURN_OK;
 }
 
+/**
+ * brasero_session_span_next:
+ * @session: a #BraseroSessionSpan
+ *
+ * Sets the next batch of data to be burnt onto the medium inserted in the #BraseroDrive
+ * set for @session (see brasero_burn_session_set_burner ()). Its free space or it capacity
+ * will be used as the maximum amount of data to be burnt.
+ *
+ * Return value: a #BraseroBurnResult. BRASERO_BURN_OK if successful.
+ **/
+
 BraseroBurnResult
 brasero_session_span_next (BraseroSessionSpan *session)
 {
@@ -280,6 +325,14 @@ brasero_session_span_next (BraseroSessionSpan *session)
 	return (pushed? BRASERO_BURN_RETRY:BRASERO_BURN_ERR);
 }
 
+/**
+ * brasero_session_span_stop:
+ * @session: a #BraseroSessionSpan
+ *
+ * Ends and cleans a spanning operation started with brasero_session_span_start ().
+ *
+ **/
+
 void
 brasero_session_span_stop (BraseroSessionSpan *session)
 {
@@ -325,6 +378,14 @@ brasero_session_span_class_init (BraseroSessionSpanClass *klass)
 	object_class->finalize = brasero_session_span_finalize;
 }
 
+/**
+ * brasero_session_span_new:
+ *
+ * Creates a new #BraseroSessionSpan object.
+ *
+ * Return value: a #BraseroSessionSpan object
+ **/
+
 BraseroSessionSpan *
 brasero_session_span_new (void)
 {
diff --git a/libbrasero-burn/brasero-track.h b/libbrasero-burn/brasero-track.h
index 30f1015..bd5212c 100644
--- a/libbrasero-burn/brasero-track.h
+++ b/libbrasero-burn/brasero-track.h
@@ -81,10 +81,6 @@ struct _BraseroTrack
 
 GType brasero_track_get_type (void) G_GNUC_CONST;
 
-/**
- *
- */
-
 void
 brasero_track_changed (BraseroTrack *track);
 
@@ -130,10 +126,6 @@ brasero_track_get_checksum (BraseroTrack *track);
 BraseroChecksumType
 brasero_track_get_checksum_type (BraseroTrack *track);
 
-/**
- *
- */
-
 BraseroBurnResult
 brasero_track_tag_add (BraseroTrack *track,
 		       const gchar *tag,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]