[discident-glib] Add API documentation

[Bastien Nocera <hadess src gnome org>]

commit 5700bebf87d6a50f187346a0dd6dc5afcb9e87bd
Author: Bastien Nocera <hadess hadess net>
Date:   Tue Mar 23 10:25:28 2010 +0000

    Add API documentation

 discident-glib/discident-glib.c |   79 +++++++++++++++++++++++++++++++++++++-
 1 files changed, 76 insertions(+), 3 deletions(-)
---
diff --git a/discident-glib/discident-glib.c b/discident-glib/discident-glib.c
index 3dad9e7..7d27e7a 100644
--- a/discident-glib/discident-glib.c
+++ b/discident-glib/discident-glib.c
@@ -146,6 +146,18 @@ discident_add_info_to_list (GList *list,
 	return g_list_prepend (list, item);
 }
 
+/**
+ * discident_get_gtin_file:
+ * @directory: a #GFile representing a directory
+ * @error: a #GError.
+ *
+ * Return the GTIN of the DVD location at @directory. Note that this
+ * function does blocking I/O. See discident_get_gtin_file_async()
+ * for a function that does not.
+ *
+ * Returns: a string containing the GTIN for the DVD or %NULL in case of errors.
+ * Free the returned string with g_free() when done.
+ **/
 char *
 discident_get_gtin_file (GFile *directory, GError **error)
 {
@@ -327,11 +339,24 @@ on_videodir_enumerate_loaded (GObject      *source_object,
 					    simple);
 }
 
+/**
+ * discident_get_gtin_file_async:
+ * @directory: a #GFile representing a directory
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
+ *
+ * Asynchronously gets the GTIN of the DVD tree location in
+ * @directory. This function does not use the Internet.
+ *
+ * When the operation is finished, @callback will be called. You can then call
+ * discident_get_gtin_file_finish() to get the result of the operation.
+ **/
 void
 discident_get_gtin_file_async  (GFile               *directory,
-			     GCancellable        *cancellable,
-			     GAsyncReadyCallback  callback,
-			     gpointer             user_data)
+				GCancellable        *cancellable,
+				GAsyncReadyCallback  callback,
+				gpointer             user_data)
 {
 	GSimpleAsyncResult *simple;
 	GFile *video_ts_dir;
@@ -364,6 +389,18 @@ discident_get_gtin_file_async  (GFile               *directory,
 	g_object_unref (video_ts_dir);
 }
 
+/**
+ * discident_get_gtin_file_finish:
+ * @directory: a #GFile representing a directory
+ * @res: a #GAsyncResult.
+ * @error: a #GError.
+ *
+ * Finishes getting the GTIN for the DVD tree at @directory. See 
+ * discident_get_gtin_file_async().
+ *
+ * Returns: the GTIN for the DVD or %NULL in case of errors.
+ * Free the returned string with g_free() when done.
+ **/
 char *
 discident_get_gtin_file_finish (GFile               *directory,
 			     GAsyncResult        *res,
@@ -460,6 +497,18 @@ discident_get_title_for_gtin (const char *gtin,
 	return title;
 }
 
+/**
+ * discident_get_title:
+ * @directory: a #GFile representing a directory
+ * @error: a #GError.
+ *
+ * Returns the title of the DVD located at @directory. Note that this
+ * function does blocking I/O. See discident_get_title_file_async()
+ * for a function that does not.
+ *
+ * Returns: a string containing the title or %NULL in case of errors.
+ * Free the returned string with g_free() when done.
+ **/
 char *
 discident_get_title (GFile   *directory,
 		     GError **error)
@@ -552,6 +601,19 @@ on_discident_got_gtin (GObject      *source_object,
 	g_object_unref (query);
 }
 
+/**
+ * discident_get_title_file_async:
+ * @directory: a #GFile representing a directory
+ * @cancellable: optional #GCancellable object, %NULL to ignore.
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to callback function
+ *
+ * Asynchronously gets the title of the DVD tree located in
+ * @directory using the DiscIdent web service.
+ *
+ * When the operation is finished, @callback will be called. You can then call
+ * discident_get_title_file_finish() to get the result of the operation.
+ **/
 void
 discident_get_title_file_async (GFile               *directory,
 				GCancellable        *cancellable,
@@ -576,6 +638,17 @@ discident_get_title_file_async (GFile               *directory,
 				       simple);
 }
 
+/**
+ * discident_get_title_file_finish:
+ * @directory: a #GFile representing a directory
+ * @res: a #GAsyncResult.
+ * @error: a #GError.
+ *
+ * Finishes a title get operation. See discident_get_title_file_async().
+ *
+ * Returns: a string containing the title or %NULL in case of errors.
+ * Free the returned string with g_free() when done.
+ **/
 char *
 discident_get_title_file_finish (GFile               *directory,
 				 GAsyncResult        *res,