[tracker/extraction-improvements: 6/9] libtracker-extract: Document tracker-client API

[Carlos Garnacho <carlosg src gnome org>]

commit e0b43ddae4602b303ba324161252cfef0b939291
Author: Carlos Garnacho <carlos lanedo com>
Date:   Tue Jun 21 17:41:30 2011 +0200

    libtracker-extract: Document tracker-client API

 .../libtracker-extract-sections.txt                |   11 ++++
 src/libtracker-extract/tracker-extract-client.c    |   58 ++++++++++++++++++++
 2 files changed, 69 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/libtracker-extract/libtracker-extract-sections.txt b/docs/reference/libtracker-extract/libtracker-extract-sections.txt
index e8832c8..bc7aff2 100644
--- a/docs/reference/libtracker-extract/libtracker-extract-sections.txt
+++ b/docs/reference/libtracker-extract/libtracker-extract-sections.txt
@@ -44,3 +44,14 @@ tracker_exif_new
 tracker_exif_free
 tracker_exif_read
 </SECTION>
+
+<SECTION>
+<FILE>tracker-extract-client</FILE>
+TrackerExtractInfo
+tracker_extract_client_get_metadata
+tracker_extract_client_get_metadata_finish
+tracker_extract_info_get_preupdate
+tracker_extract_info_get_update
+tracker_extract_info_get_where_clause
+tracker_extract_client_cancel_for_prefix
+</SECTION>
diff --git a/src/libtracker-extract/tracker-extract-client.c b/src/libtracker-extract/tracker-extract-client.c
index ac229a2..6361e78 100644
--- a/src/libtracker-extract/tracker-extract-client.c
+++ b/src/libtracker-extract/tracker-extract-client.c
@@ -338,6 +338,21 @@ get_metadata_fast_async (GDBusConnection    *connection,
 	g_object_unref (message);
 }
 
+/**
+ * tracker_extract_client_get_metadata:
+ * @file: a #GFile
+ * @mime_type: mimetype of @file
+ * @cancellable: (allow-none): cancellable for the async operation, or %NULL
+ * @callback: (scope async): callback to call when the request is satisfied.
+ * @user_data: (closure): data for the callback function
+ *
+ * Asynchronously requests metadata for @file, this request is sent to the
+ * tracker-extract daemon.
+ *
+ * When the request is finished, @callback will be executed. You can then
+ * call tracker_extract_client_get_metadata_finish() to get the result of
+ * the operation.
+ **/
 void
 tracker_extract_client_get_metadata (GFile               *file,
                                      const gchar         *mime_type,
@@ -372,6 +387,16 @@ tracker_extract_client_get_metadata (GFile               *file,
 	get_metadata_fast_async (connection, uri, mime_type, cancellable, res);
 }
 
+/**
+ * tracker_extract_client_get_metadata_finish:
+ * @file: a #GFile
+ * @res: a #GAsyncResult
+ * @error: return location for error, or %NULL to ignore.
+ *
+ * Finishes an asynchronous metadata request.
+ *
+ * Returns: (transfer full): the #TrackerExtractInfo holding the result.
+ **/
 TrackerExtractInfo *
 tracker_extract_client_get_metadata_finish (GFile         *file,
                                             GAsyncResult  *res,
@@ -388,24 +413,57 @@ tracker_extract_client_get_metadata_finish (GFile         *file,
 	return g_simple_async_result_get_op_res_gpointer (G_SIMPLE_ASYNC_RESULT (res));
 }
 
+/**
+ * tracker_extract_info_get_preupdate:
+ * @info: a #TrackerExtractInfo
+ *
+ * returns the sparql clauses to be inserted before
+ * the sparql insert/update for the file.
+ *
+ * Returns: (transfer none): the clauses to be inserted
+ *          before update.
+ **/
 G_CONST_RETURN gchar *
 tracker_extract_info_get_preupdate (TrackerExtractInfo *info)
 {
 	return info->preupdate;
 }
 
+/**
+ * tracker_extract_info_get_update:
+ * @info: a #TrackerExtractInfo
+ *
+ * Sparql holding metadata for the file.
+ *
+ * Returns: (transfer none): Sparql to be inserted into
+ *          the file update.
+ **/
 G_CONST_RETURN gchar *
 tracker_extract_info_get_update (TrackerExtractInfo *info)
 {
 	return info->update;
 }
 
+/**
+ * tracker_extract_info_get_where_clause:
+ * @info: 
+ *
+ * Where clause for the file update.
+ *
+ * Returns: (transfer none): the where clause.
+ **/
 G_CONST_RETURN gchar *
 tracker_extract_info_get_where_clause (TrackerExtractInfo *info)
 {
 	return info->where;
 }
 
+/**
+ * tracker_extract_client_cancel_for_prefix:
+ * @prefix: a #GFile
+ *
+ * Cancels any ongoing extraction task for (or within) @prefix.
+ **/
 void
 tracker_extract_client_cancel_for_prefix (GFile *prefix)
 {