[tracker] libtracker-sparql: Document the Wait() API briefly and update examples in documentation

[Martyn James Russell <mr src gnome org>]

commit 2e4d95289c088077ebb6043b3e3496672e3ec60e
Author: Martyn Russell <martyn lanedo com>
Date:   Thu Oct 7 16:52:16 2010 +0100

    libtracker-sparql: Document the Wait() API briefly and update examples in documentation

 docs/reference/libtracker-sparql/examples.sgml |   19 +++++++++++--------
 src/libtracker-sparql/tracker-connection.vala  |    7 +++++++
 2 files changed, 18 insertions(+), 8 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/examples.sgml b/docs/reference/libtracker-sparql/examples.sgml
index 33e2b3e..ddaf5dc 100644
--- a/docs/reference/libtracker-sparql/examples.sgml
+++ b/docs/reference/libtracker-sparql/examples.sgml
@@ -137,9 +137,10 @@ int main (int argc, const char **argv)
   g_type_init ();
 
   /* As we know only read-only queries will be done, it's enough
-   * to use a connection with only direct-access setup. 
+   * to use a connection with only direct-access setup. The NULL
+   * represents a possible GCancellable.
    */
-  connection = <function><link linkend="tracker-sparql-connection-get-direct">tracker_sparql_connection_get_direct</link></function> (&amp;error);
+  connection = <function><link linkend="tracker-sparql-connection-get-direct">tracker_sparql_connection_get_direct</link></function> (NULL, &amp;error);
   if (!connection) {
     g_printerr ("Couldn't obtain a direct connection to the Tracker store: %s",
                 error ? error-&gt;message : "unknown error");
@@ -239,10 +240,11 @@ int main (int argc, const char **argv)
   /* Initialize GLib type system */
   g_type_init ();
 
-  /* Do NOT get a direct connection if you're going to
-   * do some write operation in the Store
+  /* Do NOT get a direct connection if you're going to do some write
+   * operation in the Store. The NULL represents a possible
+   * GCancellable.
    */
-  connection = <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function> (&amp;error);
+  connection = <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function> (NULL, &amp;error);
   if (!connection) {
     g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
                 error ? error-&gt;message : "unknown error");
@@ -334,10 +336,11 @@ int main (int argc, const char **argv)
   /* Initialize GLib type system */
   g_type_init ();
 
-  /* Do NOT get a direct connection if you're going to
-   * do some write operation in the Store
+  /* Do NOT get a direct connection if you're going to do some write
+   * operation in the Store. The NULL represents a possible
+   * GCancellable.
    */
-  connection = <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function> (&amp;error);
+  connection = <function><link linkend="tracker-sparql-connection-get">tracker_sparql_connection_get</link></function> (NULL, &amp;error);
   if (!connection) {
     g_printerr ("Couldn't obtain a connection to the Tracker store: %s",
                 error ? error-&gt;message : "unknown error");
diff --git a/src/libtracker-sparql/tracker-connection.vala b/src/libtracker-sparql/tracker-connection.vala
index b11a614..cb87393 100644
--- a/src/libtracker-sparql/tracker-connection.vala
+++ b/src/libtracker-sparql/tracker-connection.vala
@@ -204,6 +204,13 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 * still pending. We don't expect this to be a normal programming model when
 	 * using this API.
 	 *
+	 * All backends will call the D-Bus tracker-store API Wait() to make sure
+	 * the store and databases are in the right state before any user based
+	 * requests can proceed. There may be a small delay during this call if the
+	 * databases weren't shutdown cleanly and need to be checked on start up. If
+	 * the journal needs to be replayed in such an event, the delay may be
+	 * substantial while data is restored as best as possible.
+	 *
 	 * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
 	 * object when no longer used.
 	 *