GNOME.org
 

[tracker/direct-access: 150/158] libtracker-sparql: documentation base finished

commit 15c696aaff118b8032960dc5156491eaa35834c5
Author: Aleksander Morgado <aleksander lanedo com>
Date:   Wed Aug 4 11:55:04 2010 +0200

    libtracker-sparql: documentation base finished

 .../libtracker-sparql/libtracker-sparql-docs.sgml  |   39 ++++---
 .../libtracker-sparql-sections.txt                 |   30 ++++++
 .../libtracker-sparql/libtracker-sparql.types      |    5 +-
 src/libtracker-sparql/tracker-connection.vala      |   98 ++++++++++++++++-
 src/libtracker-sparql/tracker-cursor.vala          |  111 +++++++++++++++++++-
 5 files changed, 256 insertions(+), 27 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
index 79be6e7..0978b6e 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-docs.sgml
@@ -1,39 +1,42 @@
 <?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-misc SYSTEM "xml/tracker-misc.xml">
-<!ENTITY tracker-sparql-connection SYSTEM "xml/tracker-sparql-connection.xml">
 <!ENTITY tracker-sparql-builder SYSTEM "xml/tracker-sparql-builder.xml">
+<!ENTITY tracker-sparql-connection SYSTEM "xml/tracker-sparql-connection.xml">
+<!ENTITY tracker-sparql-cursor SYSTEM "xml/tracker-sparql-cursor.xml">
+<!ENTITY tracker-misc SYSTEM "xml/tracker-misc.xml">
 <!ENTITY version SYSTEM "version.xml">
 ]>
 <book id="index">
   <bookinfo>
-    <title>Tracker Sparql Library Reference Manual</title>
+    <title>Tracker SPARQL Library Reference Manual</title>
     <releaseinfo>for libtracker-sparql &version;</releaseinfo>
   </bookinfo>
 
-  <part id="libtracker-sparql">
+  <part id="libtracker-sparql-overview">
     <title>Overview</title>
     <partintro>
       <para>
-        The libtracker-sparql library BLA BLA BLA...
+        The libtracker-sparql library is the foundation for Tracker
+        querying and inserting into the data store. The data store
+        allows both querying and inserting using SPARQL based on the
+        Nepomuk ontology.
       </para>
+    </partintro>
+  </part>
+
+  <part id="libtracker-sparql-reference">
+    <title>Reference</title>
+    <partintro>
       <para>
+        This section provides the detailed API of the Tracker SPARQL library.
       </para>
     </partintro>
-  </part>
 
-  <chapter>
-    <title>General</title>
-      &tracker-misc;
-  </chapter>
-  <chapter>
-    <title>Connection to the Store</title>
-      &tracker-sparql-connection;
-  </chapter>
-  <chapter>
-    <title>Building SPARQL Queries</title>
-      &tracker-sparql-builder;
-  </chapter>
+    &tracker-sparql-builder;
+    &tracker-sparql-connection;
+    &tracker-sparql-cursor;
+    &tracker-misc;
+  </part>
 
 </book>
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
index 5663d97..5d5d554 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
@@ -67,6 +67,7 @@ tracker_sparql_builder_construct_update
 <SECTION>
 <FILE>tracker-sparql-connection</FILE>
 <TITLE>TrackerSparqlConnection</TITLE>
+TrackerSparqlError
 TrackerSparqlConnection
 tracker_sparql_connection_get
 tracker_sparql_connection_get_direct
@@ -107,4 +108,33 @@ TRACKER_DBUS_OBJECT_STEROIDS
 TRACKER_DBUS_SERVICE
 TrackerSparqlConnectionPrivate
 tracker_sparql_connection_construct
+tracker_sparql_error_quark
+</SECTION>
+
+
+<SECTION>
+<FILE>tracker-sparql-cursor</FILE>
+<TITLE>TrackerSparqlCursor</TITLE>
+TrackerSparqlCursor
+tracker_sparql_cursor_get_connection
+tracker_sparql_cursor_get_n_columns
+tracker_sparql_cursor_get_string
+tracker_sparql_cursor_get_type
+tracker_sparql_cursor_next
+tracker_sparql_cursor_next_async
+tracker_sparql_cursor_next_finish
+tracker_sparql_cursor_rewind
+tracker_sparql_cursor_set_connection
+<SUBSECTION Standard>
+TrackerSparqlCursorClass
+TRACKER_SPARQL_CURSOR
+TRACKER_SPARQL_CURSOR_CLASS
+TRACKER_SPARQL_CURSOR_GET_CLASS
+TRACKER_SPARQL_ERROR
+TRACKER_SPARQL_IS_CURSOR
+TRACKER_SPARQL_IS_CURSOR_CLASS
+TRACKER_SPARQL_TYPE_CURSOR
+<SUBSECTION Private>
+TrackerSparqlCursorPrivate
+tracker_sparql_cursor_construct
 </SECTION>
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql.types b/docs/reference/libtracker-sparql/libtracker-sparql.types
index 0c5128c..10b4f32 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql.types
+++ b/docs/reference/libtracker-sparql/libtracker-sparql.types
@@ -1 +1,4 @@
-tracker_sparql_builder_get_type
\ No newline at end of file
+tracker_sparql_builder_get_type
+tracker_sparql_builder_state_get_type
+tracker_sparql_connection_get_type
+tracker_sparql_cursor_get_type
\ No newline at end of file
diff --git a/src/libtracker-sparql/tracker-connection.vala b/src/libtracker-sparql/tracker-connection.vala
index 7d0b198..04ec7b1 100644
--- a/src/libtracker-sparql/tracker-connection.vala
+++ b/src/libtracker-sparql/tracker-connection.vala
@@ -19,18 +19,18 @@
 
 /**
  * SECTION: tracker-sparql-connection
- * @short_description: Manage connections to the Store
+ * @short_description: Connecting to the Store
  * @title: TrackerSparqlConnection
  * @stability: Stable
  * @include: tracker-sparql.h
  *
  * <para>
- * #TrackerSparqlConnection is an object which allows setting up read-only
+ * #TrackerSparqlConnection is an object which allows setting up
  * connections to the Tracker Store.
  * </para>
  */
 
-// Convenience
+// Convenience, hidden in the documentation
 public const string TRACKER_DBUS_SERVICE = "org.freedesktop.Tracker1";
 public const string TRACKER_DBUS_INTERFACE_RESOURCES = TRACKER_DBUS_SERVICE + ".Resources";
 public const string TRACKER_DBUS_OBJECT_RESOURCES = "/org/freedesktop/Tracker1/Resources";
@@ -39,6 +39,26 @@ public const string TRACKER_DBUS_OBJECT_STATISTICS = "/org/freedesktop/Tracker1/
 public const string TRACKER_DBUS_INTERFACE_STEROIDS = TRACKER_DBUS_SERVICE + ".Steroids";
 public const string TRACKER_DBUS_OBJECT_STEROIDS = "/org/freedesktop/Tracker1/Steroids";
 
+
+/**
+ * TRACKER_SPARQL_ERROR:
+ *
+ * Error domain for Tracker Sparql. Errors in this domain will be from the
+ * #TrackerSparqlError enumeration. See #GError for more information on error
+ * domains.
+ */
+
+/**
+ * TrackerSparqlError:
+ * @TRACKER_SPARQL_ERROR_PARSE: Error parsing the SPARQL string.
+ * @TRACKER_SPARQL_UNKNOWN_CLASS: Unknown class.
+ * @TRACKER_SPARQL_UNKNOWN_PROPERTY: Unknown property.
+ * @TRACKER_SPARQL_TYPE: Wrong type.
+ * @TRACKER_SPARQL_INTERNAL: Internal error.
+ * @TRACKER_SPARQL_UNSUPPORTED: Unsupported feature or method.
+ *
+ * Possible errors reported in the operations with the #TrackerSparqlConnection.
+ */
 public errordomain Tracker.Sparql.Error {
 	PARSE,
 	UNKNOWN_CLASS,
@@ -61,6 +81,7 @@ public abstract class Tracker.Sparql.Connection : Object {
 
 	/**
 	 * tracker_sparql_connection_get:
+	 * @error: #GError for error reporting.
 	 *
 	 * Returns a new #TrackerSparqlConnection, which will use the best method
 	 * available to connect to the Tracker Store.
@@ -84,6 +105,7 @@ public abstract class Tracker.Sparql.Connection : Object {
 
 	/**
 	 * tracker_sparql_connection_get_direct:
+	 * @error: #GError for error reporting.
 	 *
 	 * Returns a new #TrackerSparqlConnection, which uses direct-access method
 	 * to connect to the Tracker Store.
@@ -325,7 +347,6 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 * 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.
 	 */
 
 	/**
@@ -340,20 +361,85 @@ public abstract class Tracker.Sparql.Connection : Object {
 		warning ("Interface 'update_commit_async' not implemented");
 	}
 
-	// Import
+	/**
+	 * tracker_sparql_connection_import:
+	 * @self: a #TrackerSparqlConnection
+	 * @file: a #GFile
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Loads a Turtle file (TTL) into the store. The API call is completely
+	 * synchronous, so it may block.
+	 */
 	public virtual void import (File file, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'import' not implemented");
 	}
+
+	/**
+	 * tracker_sparql_connection_import_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @file: a #GFile
+	 * @_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
+	 *
+	 * Loads, asynchronously, a Turtle file (TTL) into the store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_import_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous load of the Turtle file.
+	 */
 	public async virtual void import_async (File file, Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'import_async' not implemented");
 	}
 
-	// Statistics
+	/**
+	 * tracker_sparql_connection_statistics:
+	 * @self: a #TrackerSparqlConnection
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Retrieves the statistics from 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 virtual Cursor? statistics (Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'statistics' not implemented");
 		return null;
 	}
 
+	/**
+	 * tracker_sparql_connection_statistics_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
+	 *
+	 * Retrieves, asynchronously, the statistics from the Store.
+	 */
+
+	/**
+	 * tracker_sparql_connection_statistics_finish:
+	 * @self: a #TrackerSparqlConnection
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous retrieval of statistics from the Store.
+	 *
+	 * 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 virtual Cursor? statistics_async (Cancellable? cancellable = null) throws Sparql.Error {
 		warning ("Interface 'statistics_async' not implemented");
 		return null;
diff --git a/src/libtracker-sparql/tracker-cursor.vala b/src/libtracker-sparql/tracker-cursor.vala
index 3a83173..a1f6402 100644
--- a/src/libtracker-sparql/tracker-cursor.vala
+++ b/src/libtracker-sparql/tracker-cursor.vala
@@ -17,12 +17,119 @@
  * Boston, MA  02110-1301, USA.
  */
 
+/**
+ * SECTION: tracker-sparql-cursor
+ * @short_description: Iteration of the query results
+ * @title: TrackerSparqlCursor
+ * @stability: Stable
+ * @include: tracker-sparql.h
+ *
+ * <para>
+ * #TrackerSparqlCursor is an object which provides methods to iterate the
+ * results of a query to the Tracker Store.
+ * </para>
+ */
+
+
+/**
+ * TrackerSparqlCursor:
+ *
+ * The <structname>TrackerSparqlCursor</structname> object represents an
+ * iterator of results.
+ */
 public abstract class Tracker.Sparql.Cursor : Object {
-	public Connection connection { get; set; }
-	public abstract int n_columns { get; }
+
+	/**
+	 * TrackerSparqlCursor:connection:
+	 *
+	 * The #TrackerSparqlConnection used to retrieve the results.
+	 */
+	public Connection connection {
+		/**
+		 * tracker_sparql_cursor_get_connection:
+		 * @self: a #TrackerSparqlCursor
+		 *
+		 * Returns the connection used to retrieve the results.
+		 *
+		 * Returns: a #TrackerSparqlConnection. The returned object must not
+		 * be freed by the caller.
+		 */
+		get;
+		// Note: set method hidden in the documentation as the user of the
+		//  library should never use it.
+		set;
+	}
+
+	/**
+	 * TrackerSparqlCursor:n_columns:
+	 *
+	 * Number of columns available in the results to iterate.
+	 */
+	public abstract int n_columns {
+		/**
+		 * tracker_sparql_cursor_get_n_columns:
+		 * @self: a #TrackerSparqlCursor
+		 *
+		 * Returns the number of columns available in the results to iterate.
+		 *
+		 * Returns: a #gint with the number of columns.
+		 */
+		get;
+	}
+
+	/**
+	 * tracker_sparql_cursor_get_string:
+	 * @self: a #TrackerSparqlCursor
+	 * @column: column number to retrieve
+	 * @length: length of the returned string
+	 *
+	 * Returns the string at @column in the current row being iterated.
+	 *
+	 * Returns: a string, which should not be freed by the caller.
+	 */
 	public abstract unowned string? get_string (int column, out long length = null);
 
+	/**
+	 * tracker_sparql_cursor_next:
+	 * @self: a #TrackerSparqlCursor
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Iterates to the next result. The API call is completely synchronous, so
+	 * it may block.
+	 *
+	 * Returns: #FALSE if no more results found, #TRUE otherwise.
+	 */
 	public abstract bool next (Cancellable? cancellable = null) throws GLib.Error;
+
+	/**
+	 * tracker_sparql_cursor_next_async:
+	 * @self: a #TrackerSparqlCursor
+	 * @_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
+	 *
+	 * Iterates, asynchronously, to the next result.
+	 */
+
+	/**
+	 * tracker_sparql_cursor_next_finish:
+	 * @self: a #TrackerSparqlCursor
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
+	 *
+	 * Finishes the asynchronous iteration to the next result.
+	 *
+	 * Returns: #FALSE if no more results found, #TRUE otherwise.
+	 */
 	public async abstract bool next_async (Cancellable? cancellable = null) throws GLib.Error;
+
+	/**
+	 * tracker_sparql_cursor_rewind:
+	 * @self: a #TrackerSparqlCursor
+	 *
+	 * Resets the iterator to point back to the first result.
+	 */
 	public abstract void rewind ();
 }
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]