[tracker/direct-access: 149/158] libtracker-sparql: WIP adding Connection documentation

[Jürg Billeter <juergbi src gnome org>]

commit 42ad5863989296591b9b8b639c2ee857e4158422
Author: Aleksander Morgado <aleksander lanedo com>
Date:   Tue Aug 3 18:59:14 2010 +0200

    libtracker-sparql: WIP adding Connection documentation

 .../libtracker-sparql/libtracker-sparql-docs.sgml  |   31 ++--
 .../libtracker-sparql-sections.txt                 |   47 +++++
 src/libtracker-sparql/tracker-connection.vala      |  200 ++++++++++++++++++-
 3 files changed, 248 insertions(+), 30 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
index f6b2439..79be6e7 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
@@ -1,12 +1,8 @@
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                "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-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 tracker-sparql-connection SYSTEM "xml/tracker-sparql-connection.xml">
 <!ENTITY tracker-sparql-builder SYSTEM "xml/tracker-sparql-builder.xml">
 <!ENTITY version SYSTEM "version.xml">
 ]>
@@ -27,20 +23,17 @@
     </partintro>
   </part>
 
-    <chapter>
-      <title>General</title>
-<!--      &tracker; -->
-<!--      &tracker-cancel; -->
+  <chapter>
+    <title>General</title>
       &tracker-misc;
-    </chapter>
-    <!--chapter>
-      <title>Querying</title>
-      &tracker-statistics;
-      &tracker-resources;
-      &tracker-search;
-    </chapter-->
-    <chapter>
-      <title>Building Queries</title>
+  </chapter>
+  <chapter>
+    <title>Connection to the Store</title>
+      &tracker-sparql-connection;
+  </chapter>
+  <chapter>
+    <title>Building SPARQL Queries</title>
       &tracker-sparql-builder;
-    </chapter>
+  </chapter>
+
 </book>
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
index b675a6c..5663d97 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
@@ -7,6 +7,7 @@ tracker_sparql_escape_uri_printf
 tracker_sparql_escape_uri_vprintf
 </SECTION>
 
+
 <SECTION>
 <FILE>tracker-sparql-builder</FILE>
 <TITLE>TrackerSparqlBuilder</TITLE>
@@ -61,3 +62,49 @@ tracker_sparql_builder_construct
 tracker_sparql_builder_construct_embedded_insert
 tracker_sparql_builder_construct_update
 </SECTION>
+
+
+<SECTION>
+<FILE>tracker-sparql-connection</FILE>
+<TITLE>TrackerSparqlConnection</TITLE>
+TrackerSparqlConnection
+tracker_sparql_connection_get
+tracker_sparql_connection_get_direct
+tracker_sparql_connection_query
+tracker_sparql_connection_query_async
+tracker_sparql_connection_query_finish
+tracker_sparql_connection_update
+tracker_sparql_connection_update_async
+tracker_sparql_connection_update_finish
+tracker_sparql_connection_update_blank
+tracker_sparql_connection_update_blank_async
+tracker_sparql_connection_update_blank_finish
+tracker_sparql_connection_update_commit
+tracker_sparql_connection_update_commit_async
+tracker_sparql_connection_update_commit_finish
+tracker_sparql_connection_import
+tracker_sparql_connection_import_async
+tracker_sparql_connection_import_finish
+tracker_sparql_connection_statistics
+tracker_sparql_connection_statistics_async
+tracker_sparql_connection_statistics_finish
+<SUBSECTION Standard>
+TrackerSparqlConnectionClass
+TRACKER_SPARQL_CONNECTION
+TRACKER_SPARQL_CONNECTION_CLASS
+TRACKER_SPARQL_CONNECTION_GET_CLASS
+TRACKER_SPARQL_IS_CONNECTION
+TRACKER_SPARQL_IS_CONNECTION_CLASS
+TRACKER_SPARQL_TYPE_CONNECTION
+tracker_sparql_connection_get_type
+<SUBSECTION Private>
+TRACKER_DBUS_INTERFACE_RESOURCES
+TRACKER_DBUS_INTERFACE_STATISTICS
+TRACKER_DBUS_INTERFACE_STEROIDS
+TRACKER_DBUS_OBJECT_RESOURCES
+TRACKER_DBUS_OBJECT_STATISTICS
+TRACKER_DBUS_OBJECT_STEROIDS
+TRACKER_DBUS_SERVICE
+TrackerSparqlConnectionPrivate
+tracker_sparql_connection_construct
+</SECTION>
diff --git a/src/libtracker-sparql/tracker-connection.vala b/src/libtracker-sparql/tracker-connection.vala
index 9dfa02a..7d0b198 100644
--- a/src/libtracker-sparql/tracker-connection.vala
+++ b/src/libtracker-sparql/tracker-connection.vala
@@ -17,6 +17,19 @@
  * Boston, MA  02110-1301, USA.
  */
 
+/**
+ * SECTION: tracker-sparql-connection
+ * @short_description: Manage connections to the Store
+ * @title: TrackerSparqlConnection
+ * @stability: Stable
+ * @include: tracker-sparql.h
+ *
+ * <para>
+ * #TrackerSparqlConnection is an object which allows setting up read-only
+ * connections to the Tracker Store.
+ * </para>
+ */
+
 // Convenience
 public const string TRACKER_DBUS_SERVICE = "org.freedesktop.Tracker1";
 public const string TRACKER_DBUS_INTERFACE_RESOURCES = TRACKER_DBUS_SERVICE + ".Resources";
@@ -35,18 +48,33 @@ public errordomain Tracker.Sparql.Error {
 	UNSUPPORTED
 }
 
+/**
+ * TrackerSparqlConnection:
+ *
+ * The <structname>TrackerSparqlConnection</structname> object represents an
+ * connection with the Tracker Store.
+ */
 public abstract class Tracker.Sparql.Connection : Object {
 	static bool direct_only;
 	static weak Connection? singleton;
 	static int verbosity = 0;
 
+	/**
+	 * tracker_sparql_connection_get:
+	 *
+	 * Returns a new #TrackerSparqlConnection, which will use the best method
+	 * available to connect to the Tracker Store.
+	 *
+	 * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
+	 * object when no longer used.
+	 */
 	public static Connection get () throws Sparql.Error {
 		if (singleton != null) {
 			assert (!direct_only);
 			return singleton;
 		} else {
 			log_init ();
-			
+
 			var result = new PluginLoader ();
 			singleton = result;
 			result.add_weak_pointer ((void**) (&singleton));
@@ -54,13 +82,22 @@ public abstract class Tracker.Sparql.Connection : Object {
 		}
 	}
 
+	/**
+	 * tracker_sparql_connection_get_direct:
+	 *
+	 * Returns a new #TrackerSparqlConnection, which uses direct-access method
+	 * to connect to the Tracker Store.
+	 *
+	 * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
+	 * object when no longer used.
+	 */
 	public static Connection get_direct () throws Sparql.Error {
 		if (singleton != null) {
 			assert (direct_only);
 			return singleton;
 		} else {
 			log_init ();
-			
+
 			var result = new PluginLoader (true /* direct_only */);
 			direct_only = true;
 			singleton = result;
@@ -74,7 +111,7 @@ public abstract class Tracker.Sparql.Connection : Object {
 		string env_verbosity = Environment.get_variable ("TRACKER_SPARQL_VERBOSITY");
 		if (env_verbosity != null)
 			verbosity = env_verbosity.to_int ();
-	
+
 		GLib.Log.set_handler (null, LogLevelFlags.LEVEL_MASK | LogLevelFlags.FLAG_FATAL, log_handler);
 		GLib.Log.set_default_handler (log_handler);
 	}
@@ -131,37 +168,178 @@ public abstract class Tracker.Sparql.Connection : Object {
 		GLib.Log.default_handler (log_domain, log_level, message);
 	}
 
-	// Query
+	/**
+	 * tracker_sparql_connection_query:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL query
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Executes a SPARQL query on the store. The API call is completely
+	 * synchronous, so it may block.
+	 *
+	 * Returns: a #TrackerSparqlCursor to iterate the reply if successful, #NULL
+	 * on error. Call g_object_unref() on the returned cursor when no longer
+	 * needed.
+	 */
 	public abstract Cursor? query (string sparql, Cancellable? cancellable = null) throws Sparql.Error;
+
+	/**
+	 * tracker_sparql_connection_query_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL query
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Executes asynchronously a SPARQL query on the store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_query_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous SPARQL query operation.
+	 *
+	 * Returns: a #TrackerSparqlCursor to iterate the reply if successful, #NULL
+	 * on error. Call g_object_unref() on the returned cursor when no longer
+	 * needed.
+	 */
 	public async abstract Cursor? query_async (string sparql, Cancellable? cancellable = null) throws Sparql.Error;
 
-	// Update
+	/**
+	 * tracker_sparql_connection_update:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL update query
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Executes a SPARQL update on the store. The API call is completely
+	 * synchronous, so it may block.
+	 */
 	public virtual void update (string sparql, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'update' not implemented");
 	}
+
+	/**
+	 * tracker_sparql_connection_update_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL update query
+	 * @priority: the priority for the asynchronous operation
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Executes asynchronously a SPARQL update on the store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_update_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous SPARQL update operation.
+	 */
 	public async virtual void update_async (string sparql, int priority = GLib.Priority.DEFAULT, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'update_async' not implemented");
 	}
 
-	// UpdateBlank
+	/**
+	 * tracker_sparql_connection_update_blank:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL update query
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Executes a SPARQL update on the store, and returns the URNs of the
+	 * generated nodes, if any. The API call is completely synchronous, so it
+	 * may block.
+	 *
+	 * Returns: a #GVariant with the generated URNs, which should be freed with
+	 * g_variant_unref() when no longer used.
+	 */
 	public virtual GLib.Variant? update_blank (string sparql, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'update_blank' not implemented");
 		return null;
 	}
+
+	/**
+	 * tracker_sparql_connection_update_blank_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL update query
+	 * @priority: the priority for the asynchronous operation
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Executes asynchronously a SPARQL update on the store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_update_blank_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous SPARQL update operation, and returns
+	 * the URNs of the generated nodes, if any.
+	 *
+	 * Returns: a #GVariant with the generated URNs, which should be freed with
+	 * g_variant_unref() when no longer used.
+	 */
 	public async virtual GLib.Variant? update_blank_async (string sparql, int priority = GLib.Priority.DEFAULT, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'update_blank_async' not implemented");
 		return null;
 	}
 
-	// Only applies to update_async with the right priority. 
-	// Priority is used to identify batch updates.
+	/**
+	 * tracker_sparql_connection_update_commit:
+	 * @self: a #TrackerSparqlConnection
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Makes sure that any previous asynchronous update has been commited
+	 * to the store. Only applies to tracker_sparql_connection_update_async()
+	 * with the right priority (Priority is used to identify batch updates.)
+	 * The API call is completely synchronous, so it may block.
+	 */
 	public virtual void update_commit (Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'update_commit' not implemented");
 	}
+
+	/**
+	 * tracker_sparql_connection_update_commit_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 *
+	 * Makes sure, asynchronously, that any previous asynchronous update has
+	 * been commited to the store. Only applies to
+	 * tracker_sparql_connection_update_async() with the right priority
+	 * (Priority is used to identify batch updates.)
+	 * Executes asynchronously a SPARQL update on the store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_update_commit_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous commit operation.
+	 */
 	public async virtual void update_commit_async (Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'update_commit_async' not implemented");
 	}
-	
+
 	// Import
 	public virtual void import (File file, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'import' not implemented");
@@ -169,13 +347,13 @@ public abstract class Tracker.Sparql.Connection : Object {
 	public async virtual void import_async (File file, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'import_async' not implemented");
 	}
-	
+
 	// Statistics
 	public virtual Cursor? statistics (Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'statistics' not implemented");
 		return null;
 	}
-	
+
 	public async virtual Cursor? statistics_async (Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'statistics_async' not implemented");
 		return null;