GNOME.org
 

[brasero] Started to work on libbrasero-burn GObject introspection

commit b3a4b1a6b6bb248f0f08409cc237d60458fab6f7
Author: Philippe Rouquier <bonfire-app wanadoo fr>
Date:   Sat Sep 12 15:35:32 2009 +0200

    Started to work on libbrasero-burn GObject introspection
    Also in the mean time, improve API documentation

 libbrasero-burn/Makefile.am          |   27 +++++++++++++++++++++-
 libbrasero-burn/brasero-session.c    |   33 +++++++++++++-------------
 libbrasero-burn/brasero-track-data.c |   42 +++++++++++++++++-----------------
 libbrasero-burn/brasero-track-data.h |    9 +++++++
 libbrasero-burn/burn-basics.c        |   25 ++++++++++++++++++-
 5 files changed, 96 insertions(+), 40 deletions(-)
---
diff --git a/libbrasero-burn/Makefile.am b/libbrasero-burn/Makefile.am
index 8162a24..275afc2 100644
--- a/libbrasero-burn/Makefile.am
+++ b/libbrasero-burn/Makefile.am
@@ -205,8 +205,33 @@ EXTRA_DIST =			\
 	libbrasero-marshal.list
 #	libbrasero-burn.symbols
 
+girdir = $(INTROSPECTION_GIRDIR)
+gir_DATA = BraseroBurn-1.0.gir
+
+typelibsdir = $(INTROSPECTION_TYPELIBDIR)
+typelibs_DATA = BraseroBurn-1.0.typelib
+
+BraseroBurn-1.0.gir: libbrasero-burn.la $(INTROSPECTION_SCANNER)
+	$(INTROSPECTION_SCANNER) -v --namespace=BraseroBurn --nsversion=1.0 \
+	    -I$(top_builddir)/libbrasero-media	\
+            --include=Gtk-2.0 \
+            --add-include-path=$(top_builddir)/libbrasero-media	\
+	    --include=BraseroMedia-1.0 \
+	    --library=brasero-burn \
+	    --libtool="$(LIBTOOL)" \
+            --output $@ \
+            --pkg=gtk+-2.0  \
+	    --strip-prefix=Brasero	\
+            $(libbraseroburninclude_HEADERS)	\
+	    *.c	    
+	    
+BraseroBurn-1.0.typelib: $(gir_DATA) $(INTROSPECTION_COMPILER)
+	$(INTROSPECTION_COMPILER) $(gir_DATA) -o $(typelibs_DATA) --includedir=$(top_builddir)/libbrasero-media
+
 CLEANFILES =			\
-	$(RECMARSHALFILES)
+	$(RECMARSHALFILES)  \
+	$(gir_DATA)         \
+	$(typelibs_DATA)
 
 
 -include $(top_srcdir)/git.mk
diff --git a/libbrasero-burn/brasero-session.c b/libbrasero-burn/brasero-session.c
index 2697986..c2a844f 100644
--- a/libbrasero-burn/brasero-session.c
+++ b/libbrasero-burn/brasero-session.c
@@ -302,9 +302,9 @@ brasero_burn_session_get_strict_support (BraseroBurnSession *session)
 
 /**
  * brasero_burn_session_add_track:
- * @session: a #BraseroBurnSession
- * @new_track: a #BraseroTrack or NULL
- * @sibling: a #BraseroTrack or NULL
+ * @session: a #BraseroBurnSession.
+ * @new_track: (allow-none): a #BraseroTrack or NULL.
+ * @sibling: (allow-none): a #BraseroTrack or NULL.
  *
  * Inserts a new track after @sibling or appended if @sibling is NULL. If @track is NULL then all tracks
  * already in @session will be removed.
@@ -383,9 +383,9 @@ brasero_burn_session_add_track (BraseroBurnSession *self,
 
 /**
  * brasero_burn_session_move_track:
- * @session: a #BraseroBurnSession
- * @track: a #BraseroTrack
- * @sibling: a #BraseroTrack or NULL
+ * @session: a #BraseroBurnSession.
+ * @track: a #BraseroTrack.
+ * @sibling: (allow-none): a #BraseroTrack or NULL.
  *
  * Moves @track after @sibling; if @sibling is NULL then it is appended.
  *
@@ -477,7 +477,8 @@ brasero_burn_session_remove_track (BraseroBurnSession *session,
  *
  * Returns the list of #BraseroTrack added to @session.
  *
- * Return value: a #GSList or #BraseroTrack object. Do not unref the objects in the list nor destroy the list.
+ * Return value: (element-type BraseroBurn.Track) (transfer none): a #GSList or #BraseroTrack object. Do not unref the objects in the list nor destroy the list.
+ *
  **/
 
 GSList *
@@ -758,7 +759,7 @@ brasero_burn_session_set_burner (BraseroBurnSession *self,
  *
  * Returns the #BraseroDrive that should be used to burn the session contents.
  *
- * Return value: a #BraseroDrive or NULL. Do not unref after use.
+ * Return value: (transfer none) (allow-none): a #BraseroDrive or NULL. Do not unref after use.
  **/
 
 BraseroDrive *
@@ -874,9 +875,9 @@ brasero_burn_session_get_output_type (BraseroBurnSession *self,
 
 /**
  * brasero_burn_session_get_output:
- * @session: a #BraseroBurnSession
- * @image: a #gchar or NULL
- * @toc: a #gchar or NULL
+ * @session: a #BraseroBurnSession.
+ * @image: (allow-none) (out): a #gchar to store the image path or NULL.
+ * @toc: (allow-none) (out): a #gchar to store the toc path or NULL.
  *
  * When the contents of @session should be written to a
  * file then this function returns the image path (and if
@@ -1128,10 +1129,10 @@ brasero_burn_session_set_image_output_format (BraseroBurnSession *self,
 
 /**
  * brasero_burn_session_set_image_output_full:
- * @session: a #BraseroBurnSession
- * @format: a #BraseroImageFormat
- * @image: a #gchar or NULL
- * @toc: a #gchar or NULL
+ * @session: a #BraseroBurnSession.
+ * @format: a #BraseroImageFormat.
+ * @image: (allow-none): a #gchar or NULL.
+ * @toc: (allow-none): a #gchar or NULL.
  *
  * When the contents of @session should be written to a
  * file, this function sets the different parameters of this
@@ -1562,7 +1563,7 @@ brasero_burn_session_get_flags (BraseroBurnSession *self)
 /**
  * brasero_burn_session_set_label:
  * @session: a #BraseroBurnSession
- * @label: a #gchar
+ * @label: (allow-none): a #gchar or %NULL
  *
  * Sets the label for @session.
  *
diff --git a/libbrasero-burn/brasero-track-data.c b/libbrasero-burn/brasero-track-data.c
index 217c6f9..c97f936 100644
--- a/libbrasero-burn/brasero-track-data.c
+++ b/libbrasero-burn/brasero-track-data.c
@@ -126,9 +126,9 @@ brasero_track_data_set_source_real (BraseroTrackData *track,
 
 /**
  * brasero_track_data_set_source:
- * @track: a #BraseroTrackData
- * @grafts: a #GSList of #BraseroGraftPt
- * @unreadable: a #GSList of URIS as strings
+ * @track: a #BraseroTrackData.
+ * @grafts: (element-type BraseroBurn.GraftPt) (in) (transfer full): a #GSList of #BraseroGraftPt.
+ * @unreadable: (element-type utf8) (allow-none) (in) (transfer full): a #GSList of URIS as strings or %NULL.
  *
  * Sets the lists of grafts points (@grafts) and excluded
  * URIs (@unreadable) to be used to create an image.
@@ -335,14 +335,14 @@ brasero_track_data_get_fs_real (BraseroTrackData *track)
 }
 
 /**
- * brasero_track_data_get_fs:
+ * brasero_track_data_get_grafts:
  * @track: a #BraseroTrackData
  *
  * Returns a list of #BraseroGraftPt.
  *
  * Do not free after usage as @track retains ownership.
  *
- * Return value: a #GSList of #BraseroGraftPt or NULL if empty.
+ * Return value: (transfer none) (element-type BraseroBurn.GraftPt) (allow-none): a #GSList of #BraseroGraftPt or %NULL if empty.
  **/
 
 GSList *
@@ -367,16 +367,16 @@ brasero_track_data_get_grafts_real (BraseroTrackData *track)
 
 /**
  * brasero_track_data_get_excluded:
- * @track: a #BraseroTrackData
- * @copy: a #gboolean
+ * @track: a #BraseroTrackData.
+ * @copy: a #gboolean.
  *
  * Returns a list of URIs which must not be included in
  * the image to be created.
- * If @copy is TRUE then the @list is a copy and must
- * be freed once it is not needed anymore. If FALSE,
+ * If @copy is %TRUE then the @list is a copy and must
+ * be freed once it is not needed anymore. If %FALSE,
  * do not free after usage as @track retains ownership.
  *
- * Return value: a #GSList of #gchar * or NULL if no
+ * Return value: (transfer full) (element-type utf8) (allow-none): a #GSList of #gchar * or %NULL if no
  * URI should be excluded.
  **/
 
@@ -417,13 +417,13 @@ brasero_track_data_get_excluded_real (BraseroTrackData *track)
 
 /**
  * brasero_track_data_get_paths:
- * @track: a #BraseroTrackData
- * @use_joliet: a #gboolean
- * @grafts_path: a #gchar
- * @excluded_path: a #gchar
- * @emptydir: a #gchar
- * @videodir: a #gchar or NULL
- * @error: a #GError
+ * @track: a #BraseroTrackData.
+ * @use_joliet: a #gboolean.
+ * @grafts_path: a #gchar.
+ * @excluded_path: a #gchar.
+ * @emptydir: a #gchar.
+ * @videodir: (allow-none): a #gchar or %NULL.
+ * @error: a #GError.
  *
  * Write in @grafts_path (a path to a file) the graft points,
  * in @excluded_path (a path to a file) the list of paths to
@@ -472,13 +472,13 @@ brasero_track_data_get_paths (BraseroTrackData *track,
 
 /**
  * brasero_track_data_get_file_num:
- * @track: a #BraseroTrackData
- * @file_num: a #guint64
+ * @track: a #BraseroTrackData.
+ * @file_num: (allow-none) (out): a #guint64 or %NULL.
  *
  * Sets the number of files (not directories) in @file_num.
  *
- * Return value: a #BraseroBurnResult. TRUE if @file_num
- * was set, FALSE otherwise.
+ * Return value: a #BraseroBurnResult. %TRUE if @file_num
+ * was set, %FALSE otherwise.
  **/
 
 BraseroBurnResult
diff --git a/libbrasero-burn/brasero-track-data.h b/libbrasero-burn/brasero-track-data.h
index 6c90a21..a44bf24 100644
--- a/libbrasero-burn/brasero-track-data.h
+++ b/libbrasero-burn/brasero-track-data.h
@@ -65,6 +65,15 @@ struct _BraseroTrackDataClass
 	BraseroTrackClass parent_class;
 
 	/* virtual functions */
+
+	/**
+	 * set_source:
+	 * @track: a #BraseroTrackData.
+	 * @grafts: (element-type BraseroBurn.GraftPt) (transfer full): a #GSList of #BraseroGraftPt.
+	 * @unreadable: (element-type utf8) (transfer full) (allow-none): a #GSList of URIs (as strings) or %NULL.
+	 *
+	 * Return value: a #BraseroBurnResult
+	 **/
 	BraseroBurnResult	(*set_source)		(BraseroTrackData *track,
 							 GSList *grafts,
 							 GSList *unreadable);
diff --git a/libbrasero-burn/burn-basics.c b/libbrasero-burn/burn-basics.c
index f2da09a..91f2c80 100644
--- a/libbrasero-burn/burn-basics.c
+++ b/libbrasero-burn/burn-basics.c
@@ -208,6 +208,18 @@ brasero_caps_list_dump (void)
 	g_object_unref (self);
 }
 
+/**
+ * brasero_burn_library_start:
+ * @argc: an #int.
+ * @argv: a #char **.
+ *
+ * Starts the library. This function must be called
+ * before using any of the functions.
+ *
+ * Rename to: init
+ *
+ **/
+
 gboolean
 brasero_burn_library_start (int *argc,
                             char **argv [])
@@ -229,7 +241,7 @@ brasero_burn_library_start (int *argc,
 	g_setenv ("DBUS_SESSION_BUS_ADDRESS", "autolaunch:", TRUE);
 #endif
 
-	/* Initialize external libraries (threads... */
+	/* Initialize external libraries (threads...) */
 	if (!g_thread_supported ())
 		g_thread_init (NULL);
 
@@ -281,7 +293,7 @@ brasero_burn_caps_get_default ()
  * This function returns the list of plugins that 
  * are available to libbrasero-burn.
  *
- * Returns: a #GSList that must be destroyed when not needed and each object unreffed.
+ * Returns: (element-type GObject.Object) (transfer full):a #GSList that must be destroyed when not needed and each object unreffed.
  **/
 
 GSList *
@@ -291,6 +303,15 @@ brasero_burn_library_get_plugins_list (void)
 	return brasero_plugin_manager_get_plugins_list (plugin_manager);
 }
 
+/**
+ * brasero_burn_library_stop:
+ *
+ * Stop the library. Don't use any of the functions or
+ * objects afterwards
+ *
+ * Rename to: deinit
+ *
+ **/
 void
 brasero_burn_library_stop (void)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]