[brasero] Gobject introspection support for libbrasero-media. Some API doc improvements.

[Philippe Rouquier <philippr src gnome org>]

commit 9888131236f2da6ac5bd832a9e2ad940a70635c4
Author: Philippe Rouquier <bonfire-app wanadoo fr>
Date:   Fri Sep 11 21:24:34 2009 +0200

    Gobject introspection support for libbrasero-media. Some API doc improvements.

 configure.in                                |    4 ++++
 libbrasero-media/Makefile.am                |   25 +++++++++++++++++++++++--
 libbrasero-media/brasero-drive.c            |    2 +-
 libbrasero-media/brasero-media.c            |    6 ++++--
 libbrasero-media/brasero-medium-monitor.c   |    4 ++--
 libbrasero-media/brasero-medium-selection.c |    1 -
 libbrasero-media/brasero-medium-selection.h |    6 ++++++
 libbrasero-media/brasero-medium.c           |    2 +-
 libbrasero-media/brasero-medium.h           |   12 ++++++++++++
 9 files changed, 53 insertions(+), 9 deletions(-)
---
diff --git a/configure.in b/configure.in
index 4923bf5..9a74265 100644
--- a/configure.in
+++ b/configure.in
@@ -421,6 +421,10 @@ if test x"$enable_inotify" = "xyes"; then
 fi
 AM_CONDITIONAL(BUILD_INOTIFY, test x"$enable_inotify" = "xyes")
 
+dnl ****** GObject Introspection **********************
+
+GOBJECT_INTROSPECTION_CHECK(0.6.3)
+
 dnl ****** Update mime, desktop and icon caches *******
 AC_ARG_ENABLE(caches,
 			AS_HELP_STRING([--enable-caches],[Run update-* to update mime, desktop and icon caches when installing [[default=yes]]]),
diff --git a/libbrasero-media/Makefile.am b/libbrasero-media/Makefile.am
index d7c37f9..d8d9ad5 100644
--- a/libbrasero-media/Makefile.am
+++ b/libbrasero-media/Makefile.am
@@ -149,12 +149,33 @@ if HAVE_USCSI_H
 libbrasero_media_la_SOURCES += scsi-uscsi.c
 endif
 
+girdir = $(INTROSPECTION_GIRDIR)
+gir_DATA = BraseroMedia-1.0.gir
+
+typelibsdir = $(INTROSPECTION_TYPELIBDIR)
+typelibs_DATA = BraseroMedia-1.0.typelib
+
+BraseroMedia-1.0.gir: libbrasero-media.la $(INTROSPECTION_SCANNER)
+	$(INTROSPECTION_SCANNER) -v --namespace=BraseroMedia --nsversion=1.0 \
+            --include=Gtk-2.0 \
+	    --library=brasero-media \
+	    --libtool="$(LIBTOOL)" \
+            --output $@ \
+            --pkg=gtk+-2.0  \
+	    --strip-prefix=Brasero	\
+            $(libbraseromediainclude_HEADERS)	\
+	    *.c	    
+	    
+BraseroMedia-1.0.typelib: $(gir_DATA) $(INTROSPECTION_COMPILER)
+	$(INTROSPECTION_COMPILER) $(gir_DATA) -o $(typelibs_DATA)
+
 EXTRA_DIST =			\
 	libbrasero-marshal.list
 #	libbrasero-media.symbols
 
 CLEANFILES =			\
-	$(RECMARSHALFILES)
-	
+	$(RECMARSHALFILES)  \
+	$(gir_DATA)         \
+	$(typelibs_DATA)
 
 -include $(top_srcdir)/git.mk
diff --git a/libbrasero-media/brasero-drive.c b/libbrasero-media/brasero-drive.c
index d73ad54..8e494c9 100644
--- a/libbrasero-media/brasero-drive.c
+++ b/libbrasero-media/brasero-drive.c
@@ -702,7 +702,7 @@ brasero_drive_get_udi (BraseroDrive *drive)
  * Gets the medium currently inserted in the drive. If there is no medium or if
  * the medium is not probed yet then it returns NULL.
  *
- * Return value: a #BraseroMedium object or NULL. No need to unref after use.
+ * Return value: (transfer none): a #BraseroMedium object or NULL. No need to unref after use.
  **/
 BraseroMedium *
 brasero_drive_get_medium (BraseroDrive *drive)
diff --git a/libbrasero-media/brasero-media.c b/libbrasero-media/brasero-media.c
index b288269..7ef2837 100644
--- a/libbrasero-media/brasero-media.c
+++ b/libbrasero-media/brasero-media.c
@@ -511,12 +511,13 @@ brasero_media_message (const gchar *location,
 static BraseroMediumMonitor *default_monitor = NULL;
 
 /**
- * brasero_media_start:
+ * brasero_media_library_start:
  *
  * Initialize the library.
  *
  * You should call this function before using any other from the library.
  *
+ * Rename to: init
  **/
 void
 brasero_media_library_start (void)
@@ -558,10 +559,11 @@ brasero_media_library_start (void)
 }
 
 /**
- * brasero_media_stop:
+ * brasero_media_library_stop:
  *
  * De-initialize the library once you do not need the library anymore.
  *
+ * Rename to: deinit
  **/
 void
 brasero_media_library_stop (void)
diff --git a/libbrasero-media/brasero-medium-monitor.c b/libbrasero-media/brasero-medium-monitor.c
index 7f41605..11e0204 100644
--- a/libbrasero-media/brasero-medium-monitor.c
+++ b/libbrasero-media/brasero-medium-monitor.c
@@ -157,7 +157,7 @@ brasero_medium_monitor_is_probing (BraseroMediumMonitor *monitor)
  *
  * Gets the list of available drives that are of the given type.
  *
- * Return value: a #GSList or NULL
+ * Return value: (element-type BraseroMedia.Drive) (transfer full): a #GSList of  #BraseroDrive or NULL. The list must be freed and the element unreffed when finished.
  **/
 GSList *
 brasero_medium_monitor_get_drives (BraseroMediumMonitor *monitor,
@@ -206,7 +206,7 @@ brasero_medium_monitor_get_drives (BraseroMediumMonitor *monitor,
  *
  * Obtains the list of available media that are of the given type.
  *
- * Return value: a #GSList or NULL
+ * Return value: (element-type BraseroMedia.Medium) (transfer full): a #GSList of  #BraseroMedium or NULL. The list must be freed and the element unreffed when finished.
  **/
 GSList *
 brasero_medium_monitor_get_media (BraseroMediumMonitor *monitor,
diff --git a/libbrasero-media/brasero-medium-selection.c b/libbrasero-media/brasero-medium-selection.c
index ca01a0f..c8a3da1 100644
--- a/libbrasero-media/brasero-medium-selection.c
+++ b/libbrasero-media/brasero-medium-selection.c
@@ -496,7 +496,6 @@ brasero_medium_selection_add_no_disc_entry (BraseroMediumSelection *self)
  * @type: a #BraseroMediaType
  *
  * Filters and displays media corresponding to @type.
- *
  **/
 void
 brasero_medium_selection_show_media_type (BraseroMediumSelection *selector,
diff --git a/libbrasero-media/brasero-medium-selection.h b/libbrasero-media/brasero-medium-selection.h
index 77dc379..089b321 100644
--- a/libbrasero-media/brasero-medium-selection.h
+++ b/libbrasero-media/brasero-medium-selection.h
@@ -64,6 +64,12 @@ struct _BraseroMediumSelectionClass
 							 BraseroMedium *medium);
 };
 
+/**
+ * BraseroMediumSelection:
+ *
+ * Rename to: MediumSelection
+ */
+
 struct _BraseroMediumSelection
 {
 	GtkComboBox parent_instance;
diff --git a/libbrasero-media/brasero-medium.c b/libbrasero-media/brasero-medium.c
index 71d12f7..4eb8da8 100644
--- a/libbrasero-media/brasero-medium.c
+++ b/libbrasero-media/brasero-medium.c
@@ -3421,7 +3421,7 @@ brasero_medium_can_use_burnfree (BraseroMedium *medium)
  *
  * Gets the #BraseroDrive in which the medium is inserted.
  *
- * Return value: a #BraseroDrive. No need to unref after use.
+ * Return value: (transfer none): a #BraseroDrive. No need to unref after use.
  *
  **/
 BraseroDrive *
diff --git a/libbrasero-media/brasero-medium.h b/libbrasero-media/brasero-medium.h
index 874ea96..64f2fec 100644
--- a/libbrasero-media/brasero-medium.h
+++ b/libbrasero-media/brasero-medium.h
@@ -45,7 +45,19 @@ G_BEGIN_DECLS
 #define BRASERO_MEDIUM_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), BRASERO_TYPE_MEDIUM, BraseroMediumClass))
 
 typedef struct _BraseroMediumClass BraseroMediumClass;
+
+/**
+ * BraseroMedium:
+ *
+ * Represents a physical medium currently inserted in a #BraseroDrive.
+ **/
 typedef struct _BraseroMedium BraseroMedium;
+
+/**
+ * BraseroDrive:
+ *
+ * Represents a physical drive currently connected.
+ **/
 typedef struct _BraseroDrive BraseroDrive;
 
 struct _BraseroMediumClass