libtracker-sparql: Updated documentation warnings/errors

3 files changed, 92 insertions, 91 deletions

diff --git a/src/libtracker-sparql/tracker-builder.vala b/src/libtracker-sparql/tracker-builder.vala
index f9cc3018f..97e6bfdfc 100644
--- a/src/libtracker-sparql/tracker-builder.vala
+++ b/src/libtracker-sparql/tracker-builder.vala
@@ -82,22 +82,23 @@ public class Tracker.Sparql.Builder : Object {
 	}
 
 	/**
+	 * tracker_sparql_builder_get_result:
+	 * @self: a #TrackerSparqlBuilder
+	 *
+	 * Retrieves a string representation of the constructed SPARQL query.
+	 *
+	 * Returns: the created SPARQL query. The string is contained in the
+	 * #TrackerSparqlBuilder object, and should not be freed by the caller.
+	 *
+	 * Since: 0.8
+	 */
+
+	/**
 	 * TrackerSparqlBuilder:result:
 	 *
 	 * String containing the constructed SPARQL in the #TrackerSparqlBuilder.
 	 */
 	public string result {
-		/**
-		 * tracker_sparql_builder_get_result:
-		 * @self: a #TrackerSparqlBuilder
-		 *
-		 * Returns the constructed SPARQL query as a string.
-		 *
-		 * Returns: the created SPARQL query. The string is contained in the
-		 * #TrackerSparqlBuilder object, and should not be freed by the caller.
-		 *
-		 * Since: 0.8
-		 */
 		get {
 			warn_if_fail (states.length == 1);
 			return str.str;
@@ -105,41 +106,43 @@ public class Tracker.Sparql.Builder : Object {
 	}
 
 	/**
+	 * tracker_sparql_builder_get_length:
+	 * @self: a #TrackerSparqlBuilder
+	 *
+	 * Returns the number of objects added to @self.
+	 *
+	 * Returns: the number of objects contained.
+	 *
+	 * Since: 0.8
+	 */
+
+	/**
 	 * TrackerSparqlBuilder:length:
 	 *
 	 * Number of objects added to the #TrackerSparqlBuilder.
 	 */
 	public int length {
-		/**
-		 * tracker_sparql_builder_get_length:
-		 * @self: a #TrackerSparqlBuilder
-		 *
-		 * Returns the number of objects added to @self.
-		 *
-		 * Returns: the number of objects contained.
-		 *
-		 * Since: 0.8
-		 */
 		get;
 		private set;
 	}
 
 	/**
+	 * tracker_sparql_builder_get_state:
+	 * @self: a #TrackerSparqlBuilder
+	 *
+	 * Returns the current state of @self
+	 *
+	 * Returns: a #TrackerSparqlBuilderState defining the current state of @self
+	 *
+	 * Since: 0.8
+	 */
+
+	/**
 	 * TrackerSparqlBuilder:state:
 	 *
 	 * Current state of the #TrackerSparqlBuilder.
 	 */
 	public State state {
-		/**
-		 * tracker_sparql_builder_get_state:
-		 * @self: a #TrackerSparqlBuilder
-		 *
-		 * Returns the current state of @self
-		 *
-		 * Returns: a #TrackerSparqlBuilderState defining the current state of @self
-		 *
-		 * Since: 0.8
-		 */
 		get { return states[states.length - 1]; }
 	}
 
diff --git a/src/libtracker-sparql/tracker-connection.vala b/src/libtracker-sparql/tracker-connection.vala
index e3bb0fed6..b11a614e9 100644
--- a/src/libtracker-sparql/tracker-connection.vala
+++ b/src/libtracker-sparql/tracker-connection.vala
@@ -332,8 +332,8 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 * @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.
+	 * Executes a SPARQL query on. The API call is completely synchronous, so
+	 * it may block.
 	 *
 	 * Returns: a #TrackerSparqlCursor if results were found, #NULL otherwise.
 	 * On error, #NULL is returned and the @error is set accordingly.
@@ -344,20 +344,6 @@ public abstract class Tracker.Sparql.Connection : Object {
 	public abstract Cursor query (string sparql, Cancellable? cancellable = null) throws Sparql.Error, IOError;
 
 	/**
-	 * 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.
-	 *
-	 * Since: 0.10
-	 */
-
-	/**
 	 * tracker_sparql_connection_query_finish:
 	 * @self: a #TrackerSparqlConnection
 	 * @_res_: a #GAsyncResult with the result of the operation
@@ -371,6 +357,20 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 *
 	 * Since 0.10
 	 */
+
+	/**
+	 * tracker_sparql_connection_query_async:
+	 * @self: a #TrackerSparqlConnection
+	 * @sparql: string containing the SPARQL query
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
+	 *
+	 * Executes asynchronously a SPARQL query.
+	 *
+	 * Since: 0.10
+	 */
 	public async abstract Cursor query_async (string sparql, Cancellable? cancellable = null) throws Sparql.Error, IOError;
 
 	/**
@@ -381,7 +381,7 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 * @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
+	 * Executes a SPARQL update. The API call is completely
 	 * synchronous, so it may block.
 	 *
 	 * Since: 0.10
@@ -400,7 +400,7 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 * @_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.
+	 * Executes asynchronously a SPARQL update.
 	 *
 	 * Since: 0.10
 	 */
@@ -427,9 +427,8 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 * @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.
+	 * Executes a SPARQL update 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.
@@ -451,7 +450,7 @@ public abstract class Tracker.Sparql.Connection : Object {
 	 * @_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.
+	 * Executes asynchronously a SPARQL update.
 	 *
 	 * Since: 0.10
 	 */
diff --git a/src/libtracker-sparql/tracker-cursor.vala b/src/libtracker-sparql/tracker-cursor.vala
index 439e52161..9ff3a44ec 100644
--- a/src/libtracker-sparql/tracker-cursor.vala
+++ b/src/libtracker-sparql/tracker-cursor.vala
@@ -74,10 +74,9 @@ public abstract class Tracker.Sparql.Cursor : Object {
 		 * 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.
+		 * Returns: the #TrackerSparqlConnection associated with this
+		 * #TrackerSparqlCursor. The returned object must not be unreferenced
+		 * by the caller.
 		 *
 		 * Since: 0.10
 		 */
@@ -97,12 +96,12 @@ public abstract class Tracker.Sparql.Cursor : Object {
 		 * tracker_sparql_cursor_get_n_columns:
 		 * @self: a #TrackerSparqlCursor
 		 *
-		 * Returns the number of columns available in the results to iterate.
 		 * This method should only be called after a successful
-		 * tracker_sparql_cursor_next(); otherwise its return value will be
-		 * undefined.
+		 * tracker_sparql_cursor_next(); otherwise its return value
+		 * will be undefined.
 		 *
-		 * Returns: a #gint with the number of columns.
+		 * Returns: a #gint representing the number of columns available in the
+		 * results to iterate.
 		 *
 		 * Since: 0.10
 		 */
@@ -114,9 +113,9 @@ public abstract class Tracker.Sparql.Cursor : Object {
 	 * @self: a #TrackerSparqlCursor
 	 * @column: column number to retrieve (first one is 0)
 	 *
-	 * Returns the value type at @column in the current row being iterated.
+	 * The data type bound to the current row in @column is returned.
 	 *
-	 * Returns: a value type
+	 * Returns: a #TrackerSparqlValueType.
 	 *
 	 * Since: 0.10
 	 */
@@ -127,9 +126,9 @@ public abstract class Tracker.Sparql.Cursor : Object {
 	 * @self: a #TrackerSparqlCursor
 	 * @column: column number to retrieve (first one is 0)
 	 *
-	 * Returns the variable name at @column.
+	 * Retrieves the variable name for the current row in @column.
 	 *
-	 * Returns: a string, which should not be freed by the caller.
+	 * Returns: a string which must not be freed.
 	 *
 	 * Since: 0.10
 	 */
@@ -141,10 +140,11 @@ public abstract class Tracker.Sparql.Cursor : Object {
 	 * @column: column number to retrieve (first one is 0)
 	 * @length: length of the returned string
 	 *
-	 * Returns the string at @column in the current row being iterated.
+	 * Retrieves a string representation of the data in the current
+	 * row in @column.
 	 *
-	 * Returns: a string, which should not be freed by the caller. #NULL
-	 * is returned if the column number is in the [0,#n_columns] range.
+	 * Returns: a string which must not be freed. %NULL is returned if
+	 * the column is not in the [0,#n_columns] range.
 	 *
 	 * Since: 0.10
 	 */
@@ -156,37 +156,37 @@ public abstract class Tracker.Sparql.Cursor : Object {
 	 * @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
+	 * Iterates to the next result. This is completely synchronous and
 	 * it may block.
 	 *
-	 * Returns: #FALSE if no more results found, #TRUE otherwise.
+	 * Returns: %FALSE if no more results found, otherwise %TRUE.
 	 *
 	 * Since: 0.10
 	 */
 	public abstract bool next (Cancellable? cancellable = null) throws GLib.Error;
 
 	/**
-	 * tracker_sparql_cursor_next_async:
+	 * tracker_sparql_cursor_next_finish:
 	 * @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
+	 * @_res_: a #GAsyncResult with the result of the operation
+	 * @error: #GError for error reporting.
 	 *
-	 * Iterates, asynchronously, to the next result.
+	 * Finishes the asynchronous iteration to the next result.
+	 *
+	 * Returns: %FALSE if no more results found, otherwise %TRUE.
 	 *
 	 * Since: 0.10
 	 */
 
 	/**
-	 * tracker_sparql_cursor_next_finish:
+	 * tracker_sparql_cursor_next_async:
 	 * @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.
+	 * @cancellable: a #GCancellable used to cancel the operation
+	 * @_callback_: user-defined #GAsyncReadyCallback to be called when
+	 *              asynchronous operation is finished.
+	 * @_user_data_: user-defined data to be passed to @_callback_
 	 *
-	 * Returns: #FALSE if no more results found, #TRUE otherwise.
+	 * Iterates, asynchronously, to the next result.
 	 *
 	 * Since: 0.10
 	 */
@@ -202,15 +202,14 @@ public abstract class Tracker.Sparql.Cursor : Object {
 	 */
 	public abstract void rewind ();
 
-
 	/**
 	 * tracker_sparql_cursor_get_integer:
 	 * @self: a #TrackerSparqlCursor
 	 * @column: column number to retrieve (first one is 0)
 	 *
-	 * Returns the integer at @column in the current row being iterated.
+	 * Retrieve an integer for the current row in @column.
 	 *
-	 * Returns: a integer.
+	 * Returns: a #gint64.
 	 *
 	 * Since: 0.10
 	 */
@@ -225,7 +224,7 @@ public abstract class Tracker.Sparql.Cursor : Object {
 	 * @self: a #TrackerSparqlCursor
 	 * @column: column number to retrieve (first one is 0)
 	 *
-	 * Returns the double at @column in the current row being iterated.
+	 * Retrieve a double for the current row in @column.
 	 *
 	 * Returns: a double.
 	 *
@@ -242,9 +241,9 @@ public abstract class Tracker.Sparql.Cursor : Object {
 	 * @self: a #TrackerSparqlCursor
 	 * @column: column number to retrieve (first one is 0)
 	 *
-	 * Returns the boolean at @column in the current row being iterated.
+	 * Retrieve a boolean for the current row in @column.
 	 *
-	 * Returns: a boolean.
+	 * Returns: a #gboolean.
 	 *
 	 * Since: 0.10
 	 */
@@ -256,13 +255,13 @@ public abstract class Tracker.Sparql.Cursor : Object {
 	}
 
 	/**
-	 * tracker_sparql_cursor_get_unbound:
+	 * tracker_sparql_cursor_is_bound:
 	 * @self: a #TrackerSparqlCursor
 	 * @column: column number to retrieve (first one is 0)
 	 *
-	 * Returns true when @column at the current row being iterated is unbound
+	 * If the current row and @column are bound to a value, %TRUE is returned.
 	 *
-	 * Returns: a boolean.
+	 * Returns: a %TRUE or %FALSE.
 	 *
 	 * Since: 0.10
 	 */