[tracker] Add a bunch of docs to libtracker-client.

[Carlos Garnacho <carlosg src gnome org>]

commit a5faed74c523622d6e0056bad4c51b518d85a3a2
Author: Carlos Garnacho <carlos lanedo com>
Date:   Wed Dec 9 17:34:54 2009 +0100

    Add a bunch of docs to libtracker-client.

 .../libtracker-client/libtracker-client-docs.sgml  |    6 +-
 .../libtracker-client-sections.txt                 |   36 +---------
 src/libtracker-client/tracker.c                    |   73 +++++++++++++++++++-
 3 files changed, 75 insertions(+), 40 deletions(-)
---
diff --git a/docs/reference/libtracker-client/libtracker-client-docs.sgml b/docs/reference/libtracker-client/libtracker-client-docs.sgml
index db0edc7..d12377d 100644
--- a/docs/reference/libtracker-client/libtracker-client-docs.sgml
+++ b/docs/reference/libtracker-client/libtracker-client-docs.sgml
@@ -3,9 +3,10 @@
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
 <!ENTITY tracker SYSTEM "xml/tracker.xml">
 <!ENTITY tracker-cancel SYSTEM "xml/tracker_cancel.xml">
-<!ENTITY tracker-sparql SYSTEM "xml/tracker_sparql.xml">
+<!ENTITY tracker-misc SYSTEM "xml/tracker_misc.xml">
 <!ENTITY tracker-statistics SYSTEM "xml/tracker_statistics.xml">
 <!ENTITY tracker-resources SYSTEM "xml/tracker_resources.xml">
+<!ENTITY tracker-search SYSTEM "xml/tracker_search.xml">
 <!ENTITY version SYSTEM "version.xml">
 ]>
 <book id="index">
@@ -32,11 +33,12 @@
       <title>General</title>
       &tracker;
       &tracker-cancel;
-      &tracker-sparql;
+      &tracker-misc;
     </chapter>
     <chapter>
       <title>Querying</title>
       &tracker-statistics;
       &tracker-resources;
+      &tracker-search;
     </chapter>
 </book>
diff --git a/docs/reference/libtracker-client/libtracker-client-sections.txt b/docs/reference/libtracker-client/libtracker-client-sections.txt
index f0d4697..4bc7b48 100644
--- a/docs/reference/libtracker-client/libtracker-client-sections.txt
+++ b/docs/reference/libtracker-client/libtracker-client-sections.txt
@@ -14,7 +14,7 @@ tracker_cancel_last_call
 </SECTION>
 
 <SECTION>
-<FILE>tracker_sparql</FILE>
+<FILE>tracker_misc</FILE>
 <TITLE>Utilities</TITLE>
 tracker_sparql_escape
 </SECTION>
@@ -55,37 +55,3 @@ tracker_search_metadata_by_text_and_location_async
 tracker_search_metadata_by_text_and_mime_async
 tracker_search_metadata_by_text_and_mime_and_location_async
 </SECTION>
-
-<SECTION>
-<FILE>tracker-resources-glue</FILE>
-DBUS_GLIB_CLIENT_WRAPPERS_org_freedesktop_Tracker1_Resources
-org_freedesktop_Tracker1_Resources_load
-org_freedesktop_Tracker1_Resources_load_reply
-org_freedesktop_Tracker1_Resources_load_async
-dbus_g_proxy_begin_call
-org_freedesktop_Tracker1_Resources_sparql_query
-org_freedesktop_Tracker1_Resources_sparql_query_reply
-org_freedesktop_Tracker1_Resources_sparql_query_async
-org_freedesktop_Tracker1_Resources_sparql_update
-org_freedesktop_Tracker1_Resources_sparql_update_reply
-org_freedesktop_Tracker1_Resources_sparql_update_async
-org_freedesktop_Tracker1_Resources_sparql_update_blank
-org_freedesktop_Tracker1_Resources_sparql_update_blank_reply
-org_freedesktop_Tracker1_Resources_sparql_update_blank_async
-org_freedesktop_Tracker1_Resources_batch_sparql_update
-org_freedesktop_Tracker1_Resources_batch_sparql_update_reply
-org_freedesktop_Tracker1_Resources_batch_sparql_update_async
-org_freedesktop_Tracker1_Resources_batch_commit
-org_freedesktop_Tracker1_Resources_batch_commit_reply
-org_freedesktop_Tracker1_Resources_batch_commit_async
-</SECTION>
-
-<SECTION>
-<FILE>tracker-statistics-glue</FILE>
-DBUS_GLIB_CLIENT_WRAPPERS_org_freedesktop_Tracker1_Statistics
-org_freedesktop_Tracker1_Statistics_get
-org_freedesktop_Tracker1_Statistics_get_reply
-org_freedesktop_Tracker1_Statistics_get_async
-dbus_g_proxy_begin_call
-</SECTION>
-
diff --git a/src/libtracker-client/tracker.c b/src/libtracker-client/tracker.c
index 1bda522..63e9b89 100644
--- a/src/libtracker-client/tracker.c
+++ b/src/libtracker-client/tracker.c
@@ -45,6 +45,52 @@
  * applications is also available in some cases.
  **/
 
+/**
+ * SECTION:tracker_cancel
+ * @short_description: Cancelling requests.
+ * @include: libtracker-client/tracker.h
+ *
+ * Tracker allows you to cancel any request that has not been processed
+ * yet. Aditionally, for fully synchronous requests, there is helper
+ * API to cancel the last request.
+ **/
+
+/**
+ * SECTION:tracker_resources
+ * @short_description: Doing SPARQL queries to tracker-store.
+ * @include: libtracker-client/tracker.h
+ *
+ * Tracker uses the SPARQL query language
+ * <footnote><para><ulink url="http://www.w3.org/TR/rdf-sparql-query/";>SPARQL</ulink> query language for RDF (W3C)</para></footnote>
+ * to retrieve data from tracker-store, and the stored information applies to the Nepomuk
+ * ontology
+ * <footnote><para><ulink url="http://nepomuk.semanticdesktop.org/";>Nepomuk</ulink> - The social semantic desktop</para></footnote>.
+ **/
+
+/**
+ * SECTION:tracker_statistics
+ * @short_description: Data statistics.
+ * @include: libtracker-client/tracker.h
+ *
+ * This API is meant to get statistics about the stored data.
+ **/
+
+/**
+ * SECTION:tracker_misc
+ * @short_description: Utility and miscellaneous functions.
+ * @include: libtracker-client/tracker.h
+ *
+ * This is miscellaneous API that may be useful to users.
+ **/
+
+/**
+ * SECTION:tracker_search
+ * @short_description: Simple search functions.
+ * @include: libtracker-client/tracker.h
+ *
+ * Simple search API.
+ **/
+
 typedef struct {
         DBusGProxy     *proxy;
         DBusGProxyCall *pending_call;
@@ -117,8 +163,11 @@ tracker_void_reply (DBusGProxy *proxy,
  * tracker_sparql_escape:
  * @str: a string to escape.
  *
+ * Escapes a string so it can be passed as a SPARQL parameter in
+ * any query/update.
+ *
  * Returns: the newly allocated escaped string which must be freed
- * using g_free(). 
+ * using g_free().
  **/
 gchar *
 tracker_sparql_escape (const gchar *str)
@@ -450,7 +499,7 @@ tracker_resources_load (TrackerClient  *client,
  *  GError *error = NULL;
  *  const gchar *query;
  *
- *  // Create D-Bus connection with no warnings and no timeout.
+ *  /&ast; Create D-Bus connection with no warnings and no timeout. &ast;/
  *  client = tracker_connect (FALSE, 0);
  *  query = "SELECT" 
  *          "  ?album"
@@ -474,7 +523,7 @@ tracker_resources_load (TrackerClient  *client,
  *          return;
  *  }
  * 
- *  // Do something with the array
+ *  /&ast; Do something with the array &ast;/
  * 
  *  g_ptr_array_free (array, TRUE);
  * </programlisting>
@@ -553,6 +602,14 @@ tracker_resources_batch_sparql_update (TrackerClient  *client,
                                                                &*error);
 }
 
+/**
+ * tracker_resources_batch_commit:
+ * @client: a #TrackerClient.
+ * @error: return location for errors.
+ *
+ * Commits a batch of already issued SPARQL updates. This API call is
+ * synchronous so it may block.
+ **/
 void
 tracker_resources_batch_commit (TrackerClient  *client, 
                                 GError        **error)
@@ -727,6 +784,16 @@ tracker_resources_batch_sparql_update_async (TrackerClient    *client,
         return id;
 }
 
+/**
+ * tracker_resources_batch_commit_async:
+ * @client: a #TrackerClient.
+ * @callback: callback to be called when the operation is finished.
+ * @user_data: user data to pass to @callback.
+ *
+ * Commits a batch of already issued SPARQL updates. 
+ *
+ * Returns: The operation ID.
+ **/
 guint
 tracker_resources_batch_commit_async (TrackerClient    *client, 
                                       TrackerReplyVoid  callback,