libtracker-sparql: Update library API documentation

Port references and links to the gi-docgen format, and while at
it flesh out some more documentation and adjust formatting to
look better with the gi-docgen templates.

25 files changed, 1152 insertions, 910 deletions

diff --git a/src/libtracker-sparql/tracker-batch.c b/src/libtracker-sparql/tracker-batch.c
index 3a20e27a5..38c074fd2 100644
--- a/src/libtracker-sparql/tracker-batch.c
+++ b/src/libtracker-sparql/tracker-batch.c
@@ -19,30 +19,27 @@
  * Author: Carlos Garnacho <carlosg@gnome.org>
  */
 /**
- * SECTION: tracker-batch
- * @short_description: Update batches
- * @title: TrackerBatch
- * @stability: Stable
- * @include: tracker-sparql.h
- *
- * #TrackerBatch is an object containing a series of SPARQL updates,
- * in either SPARQL string or #TrackerResource form. This object has
- * a single use, after the batch is executed, it can only be finished
- * and freed.
- *
- * A batch is created with tracker_sparql_connection_create_batch().
- * To add resources use tracker_batch_add_resource() or
- * tracker_batch_add_sparql().
- *
- * When a batch is ready for execution, use tracker_batch_execute()
- * or tracker_batch_execute_async(). The batch is executed as a single
+ * TrackerBatch:
+ *
+ * `TrackerBatch` executes a series of SPARQL updates and RDF data
+ * insertions within a transaction.
+ *
+ * A batch is created with [method@Tracker.SparqlConnection.create_batch].
+ * To add resources use [method@Tracker.Batch.add_resource],
+ * [method@Tracker.Batch.add_sparql] or [method@Batch.add_statement].
+ *
+ * When a batch is ready for execution, use [method@Tracker.Batch.execute]
+ * or [method@Tracker.Batch.execute_async]. The batch is executed as a single
  * transaction, it will succeed or fail entirely.
  *
- * The mapping of blank node labels is global in a #TrackerBatch,
+ * This object has a single use, after the batch is executed it can
+ * only be finished and freed.
+ *
+ * The mapping of blank node labels is global in a `TrackerBatch`,
  * referencing the same blank node label in different operations in
  * a batch will resolve to the same resource.
  *
- * This object was added in Tracker 3.1.
+ * Since: 3.1
  */
 #include "config.h"
 
@@ -133,7 +130,7 @@ tracker_batch_class_init (TrackerBatchClass *klass)
 	/**
 	 * TrackerBatch:connection:
 	 *
-	 * The #TrackerSparqlConnection the batch belongs to.
+	 * The [class@Tracker.SparqlConnection] the batch belongs to.
 	 */
 	props[PROP_CONNECTION] =
 		g_param_spec_object ("connection",
@@ -150,9 +147,10 @@ tracker_batch_class_init (TrackerBatchClass *klass)
 
 /**
  * tracker_batch_get_connection:
- * @batch: a #TrackerBatch
+ * @batch: A `TrackerBatch`
  *
- * Returns the #TrackerSparqlConnection that this batch was created from.
+ * Returns the [class@Tracker.SparqlConnection] that this batch was created
+ * from.
  *
  * Returns: (transfer none): The SPARQL connection of this batch.
  **/
@@ -168,8 +166,8 @@ tracker_batch_get_connection (TrackerBatch *batch)
 
 /**
  * tracker_batch_add_sparql:
- * @batch: a #TrackerBatch
- * @sparql: a SPARQL update string
+ * @batch: A `TrackerBatch`
+ * @sparql: A SPARQL update string
  *
  * Adds an SPARQL update string to @batch.
  *
@@ -190,9 +188,9 @@ tracker_batch_add_sparql (TrackerBatch *batch,
 
 /**
  * tracker_batch_add_resource:
- * @batch: a #TrackerBatch
+ * @batch: A `TrackerBatch`
  * @graph: (nullable): RDF graph to insert the resource to
- * @resource: a #TrackerResource
+ * @resource: A [class@Tracker.Resource]
  *
  * Adds the RDF represented by @resource to @batch.
  *
@@ -214,17 +212,18 @@ tracker_batch_add_resource (TrackerBatch    *batch,
 
 /**
  * tracker_batch_add_statement: (skip):
- * @batch: a #TrackerBatch
- * @stmt: a #TrackerSparqlStatement containing a SPARQL update
- * @...: parameters bound to @stmt, in triples of name/type/value
+ * @batch: a `TrackerBatch`
+ * @stmt: a [class@Tracker.SparqlStatement] containing a SPARQL update
+ * @...: NULL-terminated list of parameters bound to @stmt, in triplets of name, type and value.
  *
- * Adds a #TrackerSparqlStatement containing an SPARQL update. The statement will
+ * Adds a [class@Tracker.SparqlStatement] containing an SPARQL update. The statement will
  * be executed once in the batch, with the parameters bound as specified in the
  * variable arguments.
  *
- * The variable arguments are a NULL terminated set of variable name, value GType,
- * and actual value. For example, for a statement that has a single `~name` parameter,
- * it could be given a value for execution with the given code:
+ * The variable arguments are a NULL terminated set of variable name, type [type@GObject.Type],
+ * and value. The value C type must correspond to the given [type@GObject.Type]. For example, for
+ * a statement that has a single `~name` parameter, it could be given a value for execution
+ * with the following code:
  *
  * ```c
  * tracker_batch_add_statement (batch, stmt,
@@ -232,13 +231,13 @@ tracker_batch_add_resource (TrackerBatch    *batch,
  *                              NULL);
  * ```
  *
- * The #TrackerSparqlStatement may be used on multiple tracker_batch_add_statement()
- * calls with the same or different values, on the same or different #TrackerBatch
+ * A [class@Tracker.SparqlStatement] may be used on multiple [method@Tracker.Batch.add_statement]
+ * calls with the same or different values, on the same or different `TrackerBatch`
  * objects.
  *
- * This function should only be called on #TrackerSparqlStatement objects
- * obtained through tracker_sparql_connection_update_statement() or
- * update statements loaded through tracker_sparql_connection_load_statement_from_gresource().
+ * This function should only be called on [class@Tracker.SparqlStatement] objects
+ * obtained through [method@Tracker.SparqlConnection.update_statement] or
+ * update statements loaded through [method@Tracker.SparqlConnection.load_statement_from_gresource].
  *
  * Since: 3.5
  **/
@@ -295,22 +294,20 @@ tracker_batch_add_statement (TrackerBatch           *batch,
 
 /**
  * tracker_batch_add_statementv: (rename-to tracker_batch_add_statement)
- * @batch: a #TrackerBatch
- * @stmt: a #TrackerSparqlStatement containing a SPARQL update
- * @n_values: the number of bound parameters
- * @variable_names: (array length=n_values): the names of each bound parameter
- * @values: (array length=n_values): the values of each bound parameter
+ * @batch: A `TrackerBatch`
+ * @stmt: A [class@Tracker.SparqlStatement] containing a SPARQL update
+ * @n_values: The number of bound parameters
+ * @variable_names: (array length=n_values): The names of each bound parameter
+ * @values: (array length=n_values): The values of each bound parameter
  *
- * Adds a #TrackerSparqlStatement containing an SPARQL update. The statement will
+ * Adds a [class@Tracker.SparqlStatement] containing an SPARQL update. The statement will
  * be executed once in the batch, with the values bound as specified by @variable_names
  * and @values.
  *
  * For example, for a statement that has a single `~name` parameter,
  * it could be given a value for execution with the given code:
  *
- * <div class="gi-lang-c"><pre><code class="language-c">
- *
- * ```
+ * ```c
  * const char *names = { "name" };
  * const GValue values[G_N_ELEMENTS (names)] = { 0, };
  *
@@ -320,29 +317,20 @@ tracker_batch_add_statement (TrackerBatch           *batch,
  *                               G_N_ELEMENTS (names),
  *                               names, values);
  * ```
- * </code></pre></div>
- *
- * <div class="gi-lang-python"><pre><code class="language-python">
- *
- * ```
+ * ```python
  * batch.add_statement(stmt, ['name'], ['John Smith']);
  * ```
- * </code></pre></div>
- *
- * <div class="gi-lang-javascript"><pre><code class="language-javascript">
- *
- * ```
+ * ```js
  * batch.add_statement(stmt, ['name'], ['John Smith']);
  * ```
- * </code></pre></div>
  *
- * The #TrackerSparqlStatement may be used on multiple tracker_batch_add_statement()
- * calls with the same or different values, on the same or different #TrackerBatch
+ * A [class@Tracker.SparqlStatement] may be used on multiple [method@Tracker.Batch.add_statement]
+ * calls with the same or different values, on the same or different `TrackerBatch`
  * objects.
  *
- * This function should only be called on #TrackerSparqlStatement objects
- * obtained through tracker_sparql_connection_update_statement() or
- * update statements loaded through tracker_sparql_connection_load_statement_from_gresource().
+ * This function should only be called on [class@Tracker.SparqlStatement] objects
+ * obtained through [method@Tracker.SparqlConnection.update_statement] or
+ * update statements loaded through [method@Tracker.SparqlConnection.load_statement_from_gresource].
  *
  * Since: 3.5
  **/
@@ -366,9 +354,9 @@ tracker_batch_add_statementv (TrackerBatch           *batch,
 
 /**
  * tracker_batch_execute:
- * @batch: a #TrackerBatch
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @error: location for a #GError, or %NULL
+ * @batch: a `TrackerBatch`
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
  *
  * Executes the batch. This operations happens synchronously.
  *
@@ -394,11 +382,11 @@ tracker_batch_execute (TrackerBatch  *batch,
 
 /**
  * tracker_batch_execute_async:
- * @batch: a #TrackerBatch
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @callback: user-defined #GAsyncReadyCallback to be called when
- *            asynchronous operation is finished.
- * @user_data: user-defined data to be passed to @callback
+ * @batch: A `TrackerBatch`
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
  *
  * Executes the batch. This operation happens asynchronously, when
  * finished @callback will be executed.
@@ -424,11 +412,11 @@ tracker_batch_execute_async (TrackerBatch        *batch,
 
 /**
  * tracker_batch_execute_finish:
- * @batch: a #TrackerBatch
- * @res: a #GAsyncResult with the result of the operation
- * @error: location for a #GError, or %NULL
+ * @batch: A `TrackerBatch`
+ * @res: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Finishes the operation started with tracker_batch_execute_async().
+ * Finishes the operation started with [method@Tracker.Batch.execute_async].
  *
  * Returns: %TRUE of there were no errors, %FALSE otherwise
  *
diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c
index fcc4ba3b3..76f57b636 100644
--- a/src/libtracker-sparql/tracker-connection.c
+++ b/src/libtracker-sparql/tracker-connection.c
@@ -18,43 +18,67 @@
  */
 
 /**
- * SECTION: tracker-sparql-connection
- * @short_description: Connection to SPARQL triple store
- * @title: TrackerSparqlConnection
- * @stability: Stable
- * @include: tracker-sparql.h
- *
- * #TrackerSparqlConnection is an object that represents a connection to a
- * SPARQL triple store. This store may be local and private (see
- * tracker_sparql_connection_new()), or it may be a remote connection to a
- * public endpoint (See tracker_sparql_connection_bus_new() and
- * tracker_sparql_connection_remote_new()).
- *
- * A #TrackerSparqlConnection is private to the calling process, it can be
- * exposed publicly via a #TrackerEndpoint, see tracker_endpoint_dbus_new().
- *
- * Updates on a connection are performed via the tracker_sparql_connection_update()
- * family of calls. tracker_sparql_connection_update_array() may be used for batched
- * updates. All functions have asynchronous variants.
- *
- * Queries on a connection are performed via tracker_sparql_connection_query()
- * and tracker_sparql_connection_query_statement(). The first call receives a
- * query string and returns a #TrackerSparqlCursor to iterate the results. The
- * second call returns a #TrackerSparqlStatement object that may be reused for
- * repeatable queries with variable parameters. tracker_sparql_statement_execute()
- * will returns a #TrackerSparqlCursor.
- *
- * Depending on the ontology definition, #TrackerSparqlConnection may emit
- * notifications whenever changes happen in the stored data. These notifications
- * can be processed via a #TrackerNotifier obtained with
- * tracker_sparql_connection_create_notifier().
- *
- * After use, a #TrackerSparqlConnection should be closed. See
- * tracker_sparql_connection_close() and tracker_sparql_connection_close_async().
- *
- * A #TrackerSparqlConnection may be used from multiple threads, asynchronous
- * database updates are executed sequentially on arrival order, asynchronous
- * queries are executed in a thread pool.
+ * TrackerSparqlConnection:
+ *
+ * `TrackerSparqlConnection` holds a connection to a RDF triple store.
+ *
+ * This triple store may be of three types:
+ *
+ *  - Local to the process, created through [ctor@Tracker.SparqlConnection.new].
+ *  - A HTTP SPARQL endpoint over the network, created through
+ *    [ctor@Tracker.SparqlConnection.remote_new]
+ *  - A DBus SPARQL endpoint owned by another process in the same machine, created
+ *    through [ctor@Tracker.SparqlConnection.bus_new]
+ *
+ * When creating a local triple store, it is required to give details about its
+ * structure. This is done by passing a location to an ontology, see more
+ * on how are [ontologies defined](ontologies.html). A local database may be
+ * stored in a filesystem location, or it may reside in memory.
+ *
+ * A `TrackerSparqlConnection` is private to the calling process, it can be
+ * exposed to other hosts/processes via a [class@Tracker.Endpoint], see
+ * [ctor@Tracker.EndpointDBus.new] and [ctor@Tracker.EndpointHttp.new].
+ *
+ * When issuing SPARQL queries and updates, it is recommended that these are
+ * created through [class@Tracker.SparqlStatement] to avoid the SPARQL
+ * injection class of bugs, see [method@Tracker.SparqlConnection.query_statement]
+ * and [method@Tracker.SparqlConnection.update_statement]. For SPARQL updates
+ * it is also possible to use a "builder" approach to generate RDF data, see
+ * [class@Tracker.Resource]. It is also possible to create [class@Tracker.SparqlStatement]
+ * objects for SPARQL queries and updates from SPARQL strings embedded in a
+ * [struct@Gio.Resource], see [method@Tracker.SparqlConnection.load_statement_from_gresource].
+ *
+ * To get the best performance, it is recommended that SPARQL updates are clustered
+ * through [class@Tracker.Batch].
+ *
+ * `TrackerSparqlConnection` also offers a number of methods for the simple cases,
+ * [method@Tracker.SparqlConnection.query] may be used when there is a SPARQL
+ * query string directly available, and the [method@Tracker.SparqlConnection.update]
+ * family of functions may be used for one-off updates. All functions have asynchronous
+ * variants.
+ *
+ * When a SPARQL query is executed, a [class@Tracker.SparqlCursor] will be obtained
+ * to iterate over the query results.
+ *
+ * Depending on the ontology definition, `TrackerSparqlConnection` may emit
+ * notifications whenever resources of certain types get insert, modified or
+ * deleted from the triple store (see [nrl:notify](nrl-ontology.html#nrl:notify).
+ * These notifications can be handled via a [class@Tracker.Notifier] obtained with
+ * [method@Tracker.SparqlConnection.create_notifier].
+ *
+ * After done with a connection, it is recommended to call [method@Tracker.SparqlConnection.close]
+ * or [method@Tracker.SparqlConnection.close_async] explicitly to cleanly close the
+ * connection and prevent consistency checks on future runs. The triple store
+ * connection will be implicitly closed when the `TrackerSparqlConnection` object
+ * is disposed.
+ *
+ * A `TrackerSparqlConnection` may be used from multiple threads, asynchronous
+ * updates are executed sequentially on arrival order, asynchronous
+ * queries are dispatched in a thread pool.
+ *
+ * If you ever have the need to procedurally compose SPARQL query strings, consider
+ * the use of [func@Tracker.sparql_escape_string] for literal strings and
+ * the [func@Tracker.sparql_escape_uri] family of functions for URIs.
  */
 #include "config.h"
 
@@ -118,21 +142,25 @@ tracker_sparql_connection_lookup_dbus_service (TrackerSparqlConnection  *connect
 
 /**
  * tracker_sparql_connection_query:
- * @connection: a #TrackerSparqlConnection
- * @sparql: string containing the SPARQL query
- * @cancellable: a #GCancellable used to cancel the operation
- * @error: #GError for error reporting.
+ * @connection: A `TrackerSparqlConnection`
+ * @sparql: String containing the SPARQL query
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
  *
- * Executes a SPARQL query on. The API call is completely synchronous, so
- * it may block.
+ * Executes a SPARQL query on @connection.
  *
- * The @sparql query should be built with #TrackerResource, or
- * its parts correctly escaped using tracker_sparql_escape_string(),
- * otherwise SPARQL injection is possible.
+ * This method is synchronous and will block until the query
+ * is executed. See [method@Tracker.SparqlConnection.query_async]
+ * for an asynchronous variant.
+ *
+ * If the query is partially built from user input or other
+ * untrusted sources, special care is required about possible
+ * SPARQL injection. In order to avoid it entirely, it is recommended
+ * to use [class@Tracker.SparqlStatement]. The function
+ * [func@Tracker.sparql_escape_string] exists as a last resort,
+ * but its use is not recommended.
  *
- * Returns: (transfer full): a #TrackerSparqlCursor if results were found.
- * On error, #NULL is returned and the @error is set accordingly.
- * Call g_object_unref() on the returned cursor when no longer needed.
+ * Returns: (transfer full): a [class@Tracker.SparqlCursor] with the results.
  */
 TrackerSparqlCursor *
 tracker_sparql_connection_query (TrackerSparqlConnection  *connection,
@@ -159,14 +187,21 @@ tracker_sparql_connection_query (TrackerSparqlConnection  *connection,
 
 /**
  * tracker_sparql_connection_query_async:
- * @connection: 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.
+ * @connection: A `TrackerSparqlConnection`
+ * @sparql: String containing the SPARQL query
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
+ *
+ * Executes asynchronously a SPARQL query on @connection
+ *
+ * If the query is partially built from user input or other
+ * untrusted sources, special care is required about possible
+ * SPARQL injection. In order to avoid it entirely, it is recommended
+ * to use [class@Tracker.SparqlStatement]. The function
+ * [func@Tracker.sparql_escape_string] exists as a last resort,
+ * but its use is not recommended.
  */
 void
 tracker_sparql_connection_query_async (TrackerSparqlConnection *connection,
@@ -188,15 +223,13 @@ tracker_sparql_connection_query_async (TrackerSparqlConnection *connection,
 
 /**
  * tracker_sparql_connection_query_finish:
- * @connection: a #TrackerSparqlConnection
- * @res: a #GAsyncResult with the result of the operation
- * @error: #GError for error reporting.
+ * @connection: A `TrackerSparqlConnection`
+ * @res: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Finishes the asynchronous SPARQL query operation.
+ * Finishes the operation started with [method@Tracker.SparqlConnection.query_async].
  *
- * Returns: (transfer full): a #TrackerSparqlCursor if results were found.
- * On error, #NULL is returned and the @error is set accordingly.
- * Call g_object_unref() on the returned cursor when no longer needed.
+ * Returns: (transfer full): a [class@Tracker.SparqlCursor] with the results.
  */
 TrackerSparqlCursor *
 tracker_sparql_connection_query_finish (TrackerSparqlConnection  *connection,
@@ -220,17 +253,28 @@ tracker_sparql_connection_query_finish (TrackerSparqlConnection  *connection,
 
 /**
  * tracker_sparql_connection_update:
- * @connection: 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. The API call is completely
- * synchronous, so it may block.
- *
- * The @sparql query should be built with #TrackerResource, or
- * its parts correctly escaped using tracker_sparql_escape_string(),
- * otherwise SPARQL injection is possible.
+ * @connection: A `TrackerSparqlConnection`
+ * @sparql: String containing the SPARQL update query
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
+ *
+ * Executes a SPARQL update on @connection.
+ *
+ * This method is synchronous and will block until the update
+ * is finished. See [method@Tracker.SparqlConnection.update_async]
+ * for an asynchronous variant.
+ *
+ * It is recommented to consider the usage of [class@Tracker.Batch]
+ * to cluster database updates. Frequent isolated SPARQL updates
+ * through this method will have a degraded performance in comparison.
+ *
+ * If the query is partially built from user input or other
+ * untrusted sources, special care is required about possible
+ * SPARQL injection. In order to avoid it entirely, it is recommended
+ * to use [class@Tracker.SparqlStatement], or to build the SPARQL
+ * input through [class@Tracker.Resource]. The function
+ * [func@Tracker.sparql_escape_string] exists as a last resort,
+ * but its use is not recommended.
  */
 void
 tracker_sparql_connection_update (TrackerSparqlConnection  *connection,
@@ -251,14 +295,26 @@ tracker_sparql_connection_update (TrackerSparqlConnection  *connection,
 
 /**
  * tracker_sparql_connection_update_async:
- * @connection: a #TrackerSparqlConnection
- * @sparql: string containing the SPARQL update 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
+ * @connection: A `TrackerSparqlConnection`
+ * @sparql: String containing the SPARQL update query
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
  *
  * Executes asynchronously a SPARQL update.
+ *
+ * It is recommented to consider the usage of [class@Tracker.Batch]
+ * to cluster database updates. Frequent isolated SPARQL updates
+ * through this method will have a degraded performance in comparison.
+ *
+ * If the query is partially built from user input or other
+ * untrusted sources, special care is required about possible
+ * SPARQL injection. In order to avoid it entirely, it is recommended
+ * to use [class@Tracker.SparqlStatement], or to build the SPARQL
+ * input through [class@Tracker.Resource]. The function
+ * [func@Tracker.sparql_escape_string] exists as a last resort,
+ * but its use is not recommended.
  */
 void
 tracker_sparql_connection_update_async (TrackerSparqlConnection *connection,
@@ -280,11 +336,11 @@ tracker_sparql_connection_update_async (TrackerSparqlConnection *connection,
 
 /**
  * tracker_sparql_connection_update_finish:
- * @connection: a #TrackerSparqlConnection
- * @res: a #GAsyncResult with the result of the operation
- * @error: #GError for error reporting.
+ * @connection: A `TrackerSparqlConnection`
+ * @res: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Finishes the asynchronous SPARQL update operation.
+ * Finishes the operation started with [method@Tracker.SparqlConnection.update_async].
  */
 void
 tracker_sparql_connection_update_finish (TrackerSparqlConnection  *connection,
@@ -302,16 +358,24 @@ tracker_sparql_connection_update_finish (TrackerSparqlConnection  *connection,
 
 /**
  * tracker_sparql_connection_update_array_async:
- * @connection: a #TrackerSparqlConnection
- * @sparql: an array of strings containing the SPARQL update queries
- * @sparql_length: the amount of strings you pass as @sparql
- * @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
+ * @connection: A `TrackerSparqlConnection`
+ * @sparql: An array of strings containing the SPARQL update queries
+ * @sparql_length: The amount of strings you pass as @sparql
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
  *
  * Executes asynchronously an array of SPARQL updates. All updates in the
  * array are handled within a single transaction.
+ *
+ * If the query is partially built from user input or other
+ * untrusted sources, special care is required about possible
+ * SPARQL injection. In order to avoid it entirely, it is recommended
+ * to use [class@Tracker.SparqlStatement], or to build the SPARQL
+ * input through [class@Tracker.Resource]. The function
+ * [func@Tracker.sparql_escape_string] exists as a last resort,
+ * but its use is not recommended.
  */
 void
 tracker_sparql_connection_update_array_async (TrackerSparqlConnection  *connection,
@@ -335,11 +399,11 @@ tracker_sparql_connection_update_array_async (TrackerSparqlConnection  *connecti
 
 /**
  * tracker_sparql_connection_update_array_finish:
- * @connection: a #TrackerSparqlConnection
- * @res: a #GAsyncResult with the result of the operation
- * @error: #GError for error reporting.
+ * @connection: A `TrackerSparqlConnection`
+ * @res: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Finishes the asynchronous SPARQL update_array operation.
+ * Finishes the operation started with [method@Tracker.SparqlConnection.update_array_async].
  *
  * Returns: #TRUE if there were no errors.
  */
@@ -360,16 +424,19 @@ tracker_sparql_connection_update_array_finish (TrackerSparqlConnection  *connect
 
 /**
  * tracker_sparql_connection_update_blank:
- * @connection: a #TrackerSparqlConnection
- * @sparql: string containing the SPARQL update query
- * @cancellable: a #GCancellable used to cancel the operation
- * @error: #GError for error reporting.
+ * @connection: A `TrackerSparqlConnection`
+ * @sparql: String containing the SPARQL update query
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
+ *
+ * Executes a SPARQL update and returns the names of the generated blank nodes.
  *
- * Executes a SPARQL update and returns the URNs of the generated nodes,
- * if any. The API call is completely synchronous, so it may block.
+ * This method is synchronous and will block until the update
+ * is finished. See [method@Tracker.SparqlConnection.update_blank_async]
+ * for an asynchronous variant.
  *
- * The @sparql query should be built with #TrackerResource, or
- * its parts correctly escaped using tracker_sparql_escape_string(),
+ * The @sparql query should be built with [class@Tracker.Resource], or
+ * its parts correctly escaped using [func@Tracker.sparql_escape_string],
  * otherwise SPARQL injection is possible.
  *
  * The format string of the `GVariant` is `aaa{ss}` (an array of an array
@@ -379,14 +446,13 @@ tracker_sparql_connection_update_array_finish (TrackerSparqlConnection  *connect
  * (e.g. `foo` for the blank node `_:foo`) and the URN that was generated for
  * it. For most updates the first two outer arrays will only contain one item.
  *
- * Returns: a #GVariant with the generated URNs, which should be freed with
- * g_variant_unref() when no longer used.
+ * Returns: a [type@GLib.Variant] with the generated URNs.
  *
  * Deprecated: 3.5: This function makes the expectation that blank nodes have
  * a durable name that persist. The SPARQL and RDF specs define a much more
  * reduced scope for blank node labels. This function advises a behavior that
  * goes against that reduced scope, and will directly make the returned values
- * meaningless if the %TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES flag
+ * meaningless if the #TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES flag
  * is defined in the connection.
  *
  * Users that want names generated for them, should look for other methods
@@ -411,18 +477,20 @@ tracker_sparql_connection_update_blank (TrackerSparqlConnection  *connection,
 
 /**
  * tracker_sparql_connection_update_blank_async:
- * @connection: a #TrackerSparqlConnection
- * @sparql: string containing the SPARQL update 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 update with blank nodes. See
- * the tracker_sparql_connection_update_blank() documentation to
- * see the differences with tracker_sparql_connection_update().
- *
- * Deprecated: 3.5: See tracker_sparql_connection_update_blank().
+ * @connection: A `TrackerSparqlConnection`
+ * @sparql: String containing the SPARQL update query
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
+ *
+ *
+ * Executes asynchronously a SPARQL update and returns the names of the generated blank nodes.
+ *
+ * See the [method@Tracker.SparqlConnection.update_blank] documentation to
+ * learn the differences with [method@Tracker.SparqlConnection.update].
+ *
+ * Deprecated: 3.5: See [method@Tracker.SparqlConnection.update_blank].
  */
 void
 tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connection,
@@ -444,19 +512,19 @@ tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connectio
 
 /**
  * tracker_sparql_connection_update_blank_finish:
- * @connection: a #TrackerSparqlConnection
- * @res: a #GAsyncResult with the result of the operation
- * @error: #GError for error reporting.
+ * @connection: A `TrackerSparqlConnection`
+ * @res: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
+ *
+ * Finishes the operation started with [method@Tracker.SparqlConnection.update_blank_async].
  *
- * Finishes the asynchronous SPARQL update operation, and returns
- * the URNs of the generated nodes, if any. See the
- * tracker_sparql_connection_update_blank() documentation for the interpretation
- * of the returned #GVariant.
+ * This method returns the URNs of the generated nodes, if any. See the
+ * [method@Tracker.SparqlConnection.update_blank] documentation for the interpretation
+ * of the returned [type@GLib.Variant].
  *
- * Returns: a #GVariant with the generated URNs, which should be freed with
- * g_variant_unref() when no longer used.
+ * Returns: a [type@GLib.Variant] with the generated URNs.
  *
- * Deprecated: 3.5: See tracker_sparql_connection_update_blank().
+ * Deprecated: 3.5: See [method@Tracker.SparqlConnection.update_blank].
  */
 GVariant *
 tracker_sparql_connection_update_blank_finish (TrackerSparqlConnection  *connection,
@@ -474,14 +542,21 @@ tracker_sparql_connection_update_blank_finish (TrackerSparqlConnection  *connect
 
 /**
  * tracker_sparql_connection_update_resource:
- * @connection: a #TrackerSparqlConnection
+ * @connection: A `TrackerSparqlConnection`
  * @graph: (nullable): RDF graph where the resource should be inserted/updated, or %NULL for the default graph
- * @resource: a #TrackerResource
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @error: pointer to a #GError, or %NULL
+ * @resource: A [class@Tracker.Resource]
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
+ *
+ * Inserts a resource as described by @resource on the given @graph.
  *
- * Inserts a resource as described by @resource, on the graph described by @graph.
- * This operation blocks until done.
+ * This method is synchronous and will block until the update
+ * is finished. See [method@Tracker.SparqlConnection.update_resource_async]
+ * for an asynchronous variant.
+ *
+ * It is recommented to consider the usage of [class@Tracker.Batch]
+ * to cluster database updates. Frequent isolated SPARQL updates
+ * through this method will have a degraded performance in comparison.
  *
  * Returns: #TRUE if there were no errors.
  *
@@ -508,16 +583,19 @@ tracker_sparql_connection_update_resource (TrackerSparqlConnection  *connection,
 
 /**
  * tracker_sparql_connection_update_resource_async:
- * @connection: a #TrackerSparqlConnection
+ * @connection: A `TrackerSparqlConnection`
  * @graph: (nullable): RDF graph where the resource should be inserted/updated, or %NULL for the default graph
- * @resource: a #TrackerResource
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @callback: the #GAsyncReadyCallback called when the operation completes
- * @user_data: data passed to @callback
+ * @resource: A [class@Tracker.Resource]
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
+ *
+ * Inserts asynchronously a resource as described by @resource on the given @graph.
  *
- * Inserts a resource as described by @resource, on the graph described by @graph.
- * This operation is executed asynchronously, when finished @callback will be
- * executed.
+ * It is recommented to consider the usage of [class@Tracker.Batch]
+ * to cluster database updates. Frequent isolated SPARQL updates
+ * through this method will have a degraded performance in comparison.
  *
  * Since: 3.1
  **/
@@ -544,11 +622,11 @@ tracker_sparql_connection_update_resource_async (TrackerSparqlConnection *connec
 
 /**
  * tracker_sparql_connection_update_resource_finish:
- * @connection: a #TrackerSparqlConnection
- * @res: a #GAsyncResult with the result of the operation
- * @error: pointer to a #GError, or %NULL
+ * @connection: A `TrackerSparqlConnection`
+ * @res: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Finishes a tracker_sparql_connection_update_resource_async() operation.
+ * Finishes the operation started with [method@Tracker.SparqlConnection.update_resource_async].
  *
  * Returns: #TRUE if there were no errors.
  *
@@ -570,13 +648,12 @@ tracker_sparql_connection_update_resource_finish (TrackerSparqlConnection  *conn
 
 /**
  * tracker_sparql_connection_get_namespace_manager:
- * @connection: a #TrackerSparqlConnection
+ * @connection: A `TrackerSparqlConnection`
  *
- * Retrieves a #TrackerNamespaceManager that contains all
+ * Returns a [class@Tracker.NamespaceManager] that contains all
  * prefixes in the ontology of @connection.
  *
- * Returns: (transfer none): a #TrackerNamespaceManager for this
- * connection. This object is owned by @connection and must not be freed.
+ * Returns: (transfer none): a [class@Tracker.NamespaceManager] with the prefixes of @connection.
  */
 TrackerNamespaceManager *
 tracker_sparql_connection_get_namespace_manager (TrackerSparqlConnection *connection)
@@ -593,16 +670,18 @@ tracker_sparql_connection_get_namespace_manager (TrackerSparqlConnection *connec
 
 /**
  * tracker_sparql_connection_query_statement:
- * @connection: a #TrackerSparqlConnection
- * @sparql: the SPARQL query
- * @cancellable: a #GCancellable used to cancel the operation, or %NULL
- * @error: a #TrackerSparqlError or %NULL if no error occured
+ * @connection: A `TrackerSparqlConnection`
+ * @sparql: The SPARQL query
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
  *
- * Prepares the given SELECT/DESCRIBE/CONSTRUCT @sparql as a #TrackerSparqlStatement.
- * This prepared statement can be executed through tracker_sparql_statement_execute()
- * or tracker_sparql_statement_serialize_async() families of functions.
+ * Prepares the given `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL query as a
+ * [class@Tracker.SparqlStatement].
  *
- * Returns: (transfer full) (nullable): a prepared statement
+ * This prepared statement can be executed through [method@Tracker.SparqlStatement.execute]
+ * or [method@Tracker.SparqlStatement.serialize_async] families of functions.
+ *
+ * Returns: (transfer full) (nullable): A prepared statement
  */
 TrackerSparqlStatement *
 tracker_sparql_connection_query_statement (TrackerSparqlConnection  *connection,
@@ -623,16 +702,17 @@ tracker_sparql_connection_query_statement (TrackerSparqlConnection  *connection,
 
 /**
  * tracker_sparql_connection_update_statement:
- * @connection: a #TrackerSparqlConnection
- * @sparql: the SPARQL update
- * @cancellable: a #GCancellable used to cancel the operation, or %NULL
- * @error: a #TrackerSparqlError or %NULL if no error occured
+ * @connection: A `TrackerSparqlConnection`
+ * @sparql: The SPARQL update
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
+ *
+ * Prepares the given `INSERT`/`DELETE` SPARQL as a [class@Tracker.SparqlStatement].
  *
- * Prepares the given INSERT/DELETE/LOAD/CLEAR/DROP/ADD/MOVE/COPY/CREATE @sparql
- * as a #TrackerSparqlStatement. This prepared statement can be executed through
- * the tracker_sparql_statement_update() family of functions.
+ * This prepared statement can be executed through
+ * the [method@Tracker.SparqlStatement.update] family of functions.
  *
- * Returns: (transfer full) (nullable): a prepared statement
+ * Returns: (transfer full) (nullable): A prepared statement
  *
  * Since: 3.5
  */
@@ -658,35 +738,39 @@ tracker_sparql_connection_update_statement (TrackerSparqlConnection  *connection
 
 /**
  * tracker_sparql_connection_create_notifier:
- * @connection: a #TrackerSparqlConnection
+ * @connection: A `TrackerSparqlConnection`
+ *
+ * Creates a new [class@Tracker.Notifier] to receive notifications about changes in @connection.
  *
- * Creates a new #TrackerNotifier to notify about changes in @connection.
- * See #TrackerNotifier documentation for information about how to use this
+ * See [class@Tracker.Notifier] documentation for information about how to use this
  * object.
  *
- * Returns: (transfer full): a newly created notifier. Free with g_object_unref()
- *          when no longer needed.
+ * Connections to HTTP endpoints will return %NULL.
+ *
+ * Returns: (transfer full) (nullable): A newly created notifier.
  **/
 TrackerNotifier *
 tracker_sparql_connection_create_notifier (TrackerSparqlConnection *connection)
 {
 	g_return_val_if_fail (TRACKER_IS_SPARQL_CONNECTION (connection), NULL);
 
+	if (!TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->create_notifier)
+		return NULL;
+
 	return TRACKER_SPARQL_CONNECTION_GET_CLASS (connection)->create_notifier (connection);
 }
 
 /**
  * tracker_sparql_connection_close:
- * @connection: a #TrackerSparqlConnection
+ * @connection: A `TrackerSparqlConnection`
+ *
+ * Closes a SPARQL connection.
  *
- * Closes a SPARQL connection. No other API calls than g_object_unref()
- * should happen after this call.
+ * No other API calls than g_object_unref() should happen after this call.
  *
  * This call is blocking. All pending updates will be flushed, and the
  * store databases will be closed orderly. All ongoing SELECT queries
  * will be cancelled. Notifiers will no longer emit events.
- *
- * Since: 3.0
  */
 void
 tracker_sparql_connection_close (TrackerSparqlConnection *connection)
@@ -698,17 +782,15 @@ tracker_sparql_connection_close (TrackerSparqlConnection *connection)
 
 /**
  * tracker_sparql_connection_close_async:
- * @connection: a #TrackerSparqlConnection
- * @cancellable: a #GCancellable, or %NULL
- * @callback: user-defined #GAsyncReadyCallback to be called when
- *            asynchronous operation is finished.
- * @user_data: user-defined data to be passed to @callback
+ * @connection: A `TrackerSparqlConnection`
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
  *
- * Closes a connection asynchronously. No other API calls than g_object_unref()
- * should happen after this call. See tracker_sparql_connection_close() for more
- * information.
+ * Closes a SPARQL connection asynchronously.
  *
- * Since: 3.0
+ * No other API calls than g_object_unref() should happen after this call.
  **/
 void
 tracker_sparql_connection_close_async (TrackerSparqlConnection *connection,
@@ -726,15 +808,13 @@ tracker_sparql_connection_close_async (TrackerSparqlConnection *connection,
 
 /**
  * tracker_sparql_connection_close_finish:
- * @connection: a #TrackerSparqlConnection
- * @res: the #GAsyncResult
- * @error: pointer to a #GError
+ * @connection: A `TrackerSparqlConnection`
+ * @res: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Finishes the asynchronous connection close.
+ * Finishes the operation started with [method@Tracker.SparqlConnection.close_async].
  *
  * Returns: %FALSE if some error occurred, %TRUE otherwise
- *
- * Since: 3.0
  **/
 gboolean
 tracker_sparql_connection_close_finish (TrackerSparqlConnection  *connection,
@@ -749,12 +829,13 @@ tracker_sparql_connection_close_finish (TrackerSparqlConnection  *connection,
 
 /**
  * tracker_sparql_connection_create_batch:
- * @connection: a #TrackerSparqlConnection
+ * @connection: a `TrackerSparqlConnection`
+ *
+ * Creates a new [class@Tracker.Batch] to store and execute SPARQL updates.
  *
- * Creates a new batch to store and execute update commands. If the connection
- * is readonly or cannot issue SPARQL updates, %NULL will be returned.
+ * If the connection is readonly or cannot issue SPARQL updates, %NULL will be returned.
  *
- * Returns: (transfer full): (nullable): A new #TrackerBatch
+ * Returns: (transfer full): (nullable): A new [class@Tracker.Batch]
  **/
 TrackerBatch *
 tracker_sparql_connection_create_batch (TrackerSparqlConnection *connection)
@@ -769,15 +850,19 @@ tracker_sparql_connection_create_batch (TrackerSparqlConnection *connection)
 
 /**
  * tracker_sparql_connection_load_statement_from_gresource:
- * @connection: a #TrackerSparqlConnection
- * @resource_path: the resource path of the file to parse.
- * @cancellable: a #GCancellable, or %NULL
- * @error: return location for an error, or %NULL
+ * @connection: A `TrackerSparqlConnection`
+ * @resource_path: The resource path of the file to parse.
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
+ *
+ * Prepares a [class@Tracker.SparqlStatement] for the SPARQL contained as a [struct@Gio.Resource]
+ * file at @resource_path.
  *
- * Prepares a #TrackerSparqlStatement for the SPARQL query contained as a resource
- * file at @resource_path. SPARQL Query files typically have the .rq extension.
+ * SPARQL Query files typically have the .rq extension. This will use
+ * [method@Tracker.SparqlConnection.query_statement] or [method@Tracker.SparqlConnection.update_statement]
+ * underneath to indistinctly return SPARQL query or update statements.
  *
- * Returns: (transfer full) (nullable): a prepared statement
+ * Returns: (transfer full) (nullable): A prepared statement
  *
  * Since: 3.3
  **/
@@ -828,17 +913,19 @@ tracker_sparql_connection_load_statement_from_gresource (TrackerSparqlConnection
 
 /**
  * tracker_sparql_connection_serialize_async:
- * @connection: a #TrackerSparqlConnection
- * @flags: serialization flags
- * @format: output RDF format
+ * @connection: A `TrackerSparqlConnection`
+ * @flags: Serialization flags
+ * @format: Output RDF format
  * @query: SPARQL query
- * @cancellable: a #GCancellable
- * @callback: the #GAsyncReadyCallback called when the operation completes
- * @user_data: data passed to @callback
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
  *
- * Serializes data into the specified RDF format. @query must be either a
- * `DESCRIBE` or `CONSTRUCT` query. This is an asynchronous operation,
- * @callback will be invoked when the data is available for reading.
+ * Serializes a `DESCRIBE` or `CONSTRUCT` query into the specified RDF format.
+ *
+ * This is an asynchronous operation, @callback will be invoked when
+ * the data is available for reading.
  *
  * The SPARQL endpoint may not support the specified format, in that case
  * an error will be raised.
@@ -875,14 +962,13 @@ tracker_sparql_connection_serialize_async (TrackerSparqlConnection *connection,
 
 /**
  * tracker_sparql_connection_serialize_finish:
- * @connection: a #TrackerSparqlConnection
- * @result: the #GAsyncResult
- * @error: location for returned errors, or %NULL
+ * @connection: A `TrackerSparqlConnection`
+ * @result: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Finishes a tracker_sparql_connection_serialize_async() operation.
- * In case of error, %NULL will be returned and @error will be set.
+ * Finishes the operation started with [method@Tracker.SparqlConnection.serialize_async].
  *
- * Returns: (transfer full): a #GInputStream to read RDF content.
+ * Returns: (transfer full): A [class@Gio.InputStream] to read RDF content.
  *
  * Since: 3.3
  **/
@@ -902,22 +988,23 @@ tracker_sparql_connection_serialize_finish (TrackerSparqlConnection  *connection
 
 /**
  * tracker_sparql_connection_deserialize_async:
- * @connection: a #TrackerSparqlConnection
- * @flags: deserialization flags
+ * @connection: A `TrackerSparqlConnection`
+ * @flags: Deserialization flags
  * @format: RDF format of data in stream
- * @default_graph: default graph that will receive the RDF data
- * @stream: input stream with RDF data
- * @cancellable: a #GCancellable
- * @callback: the #GAsyncReadyCallback called when the operation completes
- * @user_data: data passed to @callback
- *
- * Incorporates the contents of the RDF data contained in @stream into the
- * data stored by @connection. This is an asynchronous operation,
- * @callback will be invoked when the data has been fully inserted to
- * @connection.
- *
- * RDF data will be inserted in the given @default_graph if one is provided,
- * or the default graph if @default_graph is %NULL. Any RDF data that has a
+ * @default_graph: Default graph that will receive the RDF data
+ * @stream: Input stream with RDF data
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
+ *
+ * Loads the RDF data contained in @stream into the given @connection.
+
+ * This is an asynchronous operation, @callback will be invoked when the
+ * data has been fully inserted to @connection.
+ *
+ * The RDF data will be inserted in the given @default_graph if one is provided,
+ * or the anonymous graph if @default_graph is %NULL. Any RDF data that has a
  * graph specified (e.g. using the `GRAPH` clause in the Trig format) will
  * be inserted in the specified graph instead of @default_graph.
  *
@@ -955,12 +1042,11 @@ tracker_sparql_connection_deserialize_async (TrackerSparqlConnection *connection
 
 /**
  * tracker_sparql_connection_deserialize_finish:
- * @connection: a #TrackerSparqlConnection
- * @result: the #GAsyncResult
- * @error: location for returned errors, or %NULL
+ * @connection: A `TrackerSparqlConnection`
+ * @result: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Finishes a tracker_sparql_connection_deserialize_async() operation.
- * In case of error, %NULL will be returned and @error will be set.
+ * Finishes the operation started with [method@Tracker.SparqlConnection.deserialize_async].
  *
  * Returns: %TRUE if all data was inserted successfully.
  *
@@ -982,14 +1068,21 @@ tracker_sparql_connection_deserialize_finish (TrackerSparqlConnection  *connecti
 
 /**
  * tracker_sparql_connection_map_connection:
- * @connection: a #TrackerSparqlConnection
- * @handle_name: handle name for @service_connection
- * @service_connection: a #TrackerSparqlConnection to use from @connection
+ * @connection: A `TrackerSparqlConnection`
+ * @handle_name: Handle name for @service_connection
+ * @service_connection: a `TrackerSparqlConnection` to use from @connection
+ *
+ * Maps a `TrackerSparqlConnection` onto another through a `private:@handle_name` URI.
  *
- * Maps @service_connection so it is available as a "private:@handle_name" URI
- * in @connection. This can be accessed via the SERVICE SPARQL syntax in
+ * This can be accessed via the SERVICE SPARQL syntax in
  * queries from @connection. E.g.:
  *
+ * ```c
+ * tracker_sparql_connection_map_connection (connection,
+ *                                           "other-connection",
+ *                                           other_connection);
+ * ```
+ *
  * ```sparql
  * SELECT ?u {
  *   SERVICE <private:other-connection> {
@@ -999,11 +1092,11 @@ tracker_sparql_connection_deserialize_finish (TrackerSparqlConnection  *connecti
  * ```
  *
  * This is useful to interrelate data from multiple
- * #TrackerSparqlConnection instances maintained by the same process,
+ * `TrackerSparqlConnection` instances maintained by the same process,
  * without creating a public endpoint for @service_connection.
  *
- * @connection may only be a #TrackerSparqlConnection created via
- * tracker_sparql_connection_new() and tracker_sparql_connection_new_async().
+ * @connection may only be a `TrackerSparqlConnection` created via
+ * [ctor@Tracker.SparqlConnection.new] and [func@Tracker.SparqlConnection.new_async].
  *
  * Since: 3.3
  **/
@@ -1028,11 +1121,12 @@ tracker_sparql_connection_map_connection (TrackerSparqlConnection *connection,
  * tracker_sparql_connection_remote_new:
  * @uri_base: Base URI of the remote connection
  *
- * Connects to a remote SPARQL endpoint. The connection is made using the libsoup
- * HTTP library. The connection will normally use the http:// or https:// protocol.
+ * Creates a connection to a remote HTTP SPARQL endpoint.
+ *
+ * The connection is made using the libsoup HTTP library. The connection will
+ * normally use the `https://` or `http://` protocols.
  *
- * Returns: (transfer full): a new remote #TrackerSparqlConnection. Call
- * g_object_unref() on the object when no longer used.
+ * Returns: (transfer full): a new remote `TrackerSparqlConnection`.
  */
 TrackerSparqlConnection *
 tracker_sparql_connection_remote_new (const gchar *uri_base)
@@ -1042,39 +1136,47 @@ tracker_sparql_connection_remote_new (const gchar *uri_base)
 
 /**
  * tracker_sparql_connection_new:
- * @flags: values from #TrackerSparqlConnectionFlags
- * @store: (nullable): the directory that contains the database as a #GFile, or %NULL
- * @ontology: (nullable): the directory that contains the database schemas as a #GFile, or %NULL
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @error: pointer to a #GError
+ * @flags: Connection flags to define the SPARQL connection behavior
+ * @store: (nullable): The directory that contains the database as a [iface@Gio.File], or %NULL
+ * @ontology: (nullable): The directory that contains the database schemas as a [iface@Gio.File], or %NULL
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
  *
- * Creates or opens a database.
+ * Creates or opens a process-local database.
  *
  * This method should only be used for databases owned by the current process.
  * To connect to databases managed by other processes, use
- * tracker_sparql_connection_bus_new().
+ * [ctor@Tracker.SparqlConnection.bus_new].
  *
  * If @store is %NULL, the database will be created in memory.
  *
- * The @ontologies parameter must point to a location containing suitable
- * `.ontology` files in Turtle format. These control the database schema that
- * is used. You can use the default Nepomuk ontologies by calling
- * tracker_sparql_get_ontology_nepomuk ().
- *
- * If you open an existing database using a different @ontology to the one it
- * was created with, Tracker will attempt to migrate the existing data to the
- * new schema. This may raise an error. In particular, not all migrations are
- * possible without causing data loss and Tracker will refuse to delete data
- * during a migration.
- *
- * You can also pass %NULL for @ontologies to mean "use the ontologies that the
- * database was created with". This will fail if the database doesn't already
- * exist.
- *
- * Returns: (transfer full): a new #TrackerSparqlConnection. Call
- * g_object_unref() on the object when no longer used.
- *
- * Since: 3.0
+ * If defined, the @ontology argument must point to a location containing
+ * suitable `.ontology` files in Turtle format. These define the structure of
+ * the triple store. You can learn more about [ontologies](ontologies.html),
+ * or you can use the stock Nepomuk ontologies by calling
+ * [func@Tracker.sparql_get_ontology_nepomuk].
+ *
+ * If opening an existing database, it is possible to pass %NULL as the
+ * @ontology location, the ontology will be introspected from the database.
+ * Passing a %NULL @ontology will raise an error if the database does not exist.
+ *
+ * If a database is opened without the #TRACKER_SPARQL_CONNECTION_FLAG_READONLY
+ * flag enabled, and the given @ontology holds differences with the current
+ * data layout, migration to the new structure will be attempted. This operation
+ * may raise an error. In particular, not all migrations are possible without
+ * causing data loss and Tracker will refuse to delete data during a migration.
+ * The database is always left in a consistent state, either prior or posterior
+ * to migration.
+ *
+ * It is considered a developer error to ship ontologies that contain format
+ * errors, or that fail at migrations.
+ *
+ * It is encouraged to use `resource:///` URI locations for @ontology wherever
+ * possible, so the triple store structure is tied to the executable binary,
+ * and in order to minimize disk seeks during `TrackerSparqlConnection`
+ * initialization.
+ *
+ * Returns: (transfer full): a new `TrackerSparqlConnection`.
  */
 TrackerSparqlConnection *
 tracker_sparql_connection_new (TrackerSparqlConnectionFlags   flags,
@@ -1110,16 +1212,17 @@ new_async_cb (GObject      *source,
 
 /**
  * tracker_sparql_connection_new_async:
- * @flags: values from #TrackerSparqlConnectionFlags
- * @store: (nullable): the directory that contains the database as a #GFile, or %NULL
- * @ontology: (nullable): the directory that contains the database schemas as a #GFile, or %NULL
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @callback: the #GAsyncReadyCallback called when the operation completes
- * @user_data: data passed to @callback
+ * @flags: Connection flags to define the SPARQL connection behavior
+ * @store: (nullable): The directory that contains the database as a [iface@Gio.File], or %NULL
+ * @ontology: (nullable): The directory that contains the database schemas as a [iface@Gio.File], or %NULL
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
  *
- * Asynchronous version of tracker_sparql_connection_new().
+ * Creates or opens a process-local database asynchronously.
  *
- * Since: 3.0
+ * See [ctor@Tracker.SparqlConnection.new] for more information.
  */
 
 void
@@ -1145,12 +1248,10 @@ tracker_sparql_connection_new_async (TrackerSparqlConnectionFlags  flags,
 
 /**
  * tracker_sparql_connection_new_finish:
- * @result: the #GAsyncResult
- * @error: pointer to a #GError
- *
- * Completion function for tracker_sparql_connection_new_async().
+ * @result: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Since: 3.0
+ * Finishes the operation started with [func@Tracker.SparqlConnection.new_async].
  */
 TrackerSparqlConnection *
 tracker_sparql_connection_new_finish (GAsyncResult  *res,
@@ -1168,16 +1269,13 @@ tracker_sparql_connection_new_finish (GAsyncResult  *res,
  * tracker_sparql_connection_bus_new:
  * @service_name: The name of the D-Bus service to connect to.
  * @object_path: (nullable): The path to the object, or %NULL to use the default.
- * @dbus_connection: (nullable): The #GDBusConnection to use, or %NULL to use the session bus
- * @error: pointer to a #GError
+ * @dbus_connection: (nullable): The [type@Gio.DBusConnection] to use, or %NULL to use the session bus
+ * @error: Error location
  *
  * Connects to a database owned by another process on the
- * local machine.
+ * local machine via DBus.
  *
- * Returns: (transfer full): a new #TrackerSparqlConnection. Call g_object_unref() on the
- * object when no longer used.
- *
- * Since: 3.0
+ * Returns: (transfer full): a new `TrackerSparqlConnection`.
  */
 TrackerSparqlConnection *
 tracker_sparql_connection_bus_new (const gchar      *service,
@@ -1218,13 +1316,14 @@ bus_new_cb (GObject      *source,
  * tracker_sparql_connection_bus_new_async:
  * @service_name: The name of the D-Bus service to connect to.
  * @object_path: (nullable): The path to the object, or %NULL to use the default.
- * @dbus_connection: (nullable): The #GDBusConnection to use, or %NULL to use the session bus
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @callback: the #GAsyncReadyCallback called when the operation completes
- * @user_data: data passed to @callback
+ * @dbus_connection: (nullable): The [class@Gio.DBusConnection] to use, or %NULL to use the session bus
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: User-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
+ * @user_data: User-defined data to be passed to @callback
  *
- * Connects to a database owned by another process on the
- * local machine. This is an asynchronous operation.
+ * Connects asynchronously to a database owned by another process on the
+ * local machine via DBus.
  *
  * Since: 3.1
  */
@@ -1255,13 +1354,12 @@ tracker_sparql_connection_bus_new_async (const gchar         *service,
 
 /**
  * tracker_sparql_connection_bus_new_finish:
- * @result: the #GAsyncResult
- * @error: pointer to a #GError
+ * @result: A [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Completion function for tracker_sparql_connection_bus_new_async().
+ * Finishes the operation started with [func@Tracker.SparqlConnection.bus_new_async].
  *
- * Returns: (transfer full): a new #TrackerSparqlConnection. Call g_object_unref() on the
- * object when no longer used.
+ * Returns: (transfer full): a new `TrackerSparqlConnection`.
  *
  * Since: 3.1
  */
diff --git a/src/libtracker-sparql/tracker-connection.h b/src/libtracker-sparql/tracker-connection.h
index d0923c9cd..f31c37890 100644
--- a/src/libtracker-sparql/tracker-connection.h
+++ b/src/libtracker-sparql/tracker-connection.h
@@ -55,6 +55,12 @@ typedef enum {
 	TRACKER_SPARQL_CONNECTION_FLAGS_ANONYMOUS_BNODES      = 1 << 5,
 } TrackerSparqlConnectionFlags;
 
+/**
+ * TrackerSerializeFlags:
+ * @TRACKER_SERIALIZE_FLAGS_NONE: No flags.
+ *
+ * Flags affecting serialization into a RDF data format.
+ */
 typedef enum {
 	TRACKER_SERIALIZE_FLAGS_NONE = 0,
 } TrackerSerializeFlags;
@@ -63,18 +69,12 @@ typedef enum {
  * TrackerDeserializeFlags:
  * @TRACKER_DESERIALIZE_FLAGS_NONE: No flags.
  *
- * Flags affecting deserialization of RDF.
+ * Flags affecting deserialization from a RDF data format.
  */
 typedef enum {
 	TRACKER_DESERIALIZE_FLAGS_NONE = 0,
 } TrackerDeserializeFlags;
 
-/**
- * TrackerSparqlConnection:
- *
- * The <structname>TrackerSparqlConnection</structname> object represents a
- * SPARQL connection.
- */
 #define TRACKER_TYPE_SPARQL_CONNECTION tracker_sparql_connection_get_type ()
 #define TRACKER_SPARQL_TYPE_CONNECTION TRACKER_TYPE_SPARQL_CONNECTION
 
diff --git a/src/libtracker-sparql/tracker-cursor.c b/src/libtracker-sparql/tracker-cursor.c
index d7eb83685..42a531aeb 100644
--- a/src/libtracker-sparql/tracker-cursor.c
+++ b/src/libtracker-sparql/tracker-cursor.c
@@ -17,16 +17,31 @@
  * Boston, MA  02110-1301, USA.
  */
 /**
- * SECTION: tracker-sparql-cursor
- * @short_description: Iteration of the query results
- * @title: TrackerSparqlCursor
- * @stability: Stable
- * @include: tracker-sparql.h
+ * TrackerSparqlCursor:
  *
- * #TrackerSparqlCursor is an object which provides methods to iterate the
- * results of a query to the Tracker Store.
+ * `TrackerSparqlCursor` provides the methods to iterate the results of a SPARQL query.
  *
- * It is possible to use a given #TrackerSparqlCursor in other threads than
+ * Cursors are obtained through e.g. [method@Tracker.SparqlStatement.execute]
+ * or [method@Tracker.SparqlConnection.query] after the SPARQL query has been
+ * executed.
+ *
+ * When created, a cursor does not point to any element, [method@Tracker.SparqlCursor.next]
+ * is necessary to iterate one by one to the first (and following) results.
+ * When the cursor iterated across all rows in the result set, [method@Tracker.SparqlCursor.next]
+ * will return %FALSE with no error set.
+ *
+ * On each row, it is possible to extract the result values through the
+ * [method@Tracker.SparqlCursor.get_integer], [method@Tracker.SparqlCursor.get_string], etc... family
+ * of methods. The column index of those functions starts at 0. The number of columns is
+ * dependent on the SPARQL query issued, but may be checked at runtime through the
+ * [method@Tracker.SparqlCursor.get_n_columns] method.
+ *
+ * After a cursor is iterated, it is recommended to call [method@Tracker.SparqlCursor.close]
+ * explicitly to free up resources for other users of the same [class@Tracker.SparqlConnection],
+ * this is especially important in garbage collected languages. These resources
+ * will be also implicitly freed on cursor object finalization.
+ *
+ * It is possible to use a given `TrackerSparqlCursor` in other threads than
  * the one it was created from. It must be however used from just one thread
  * at any given time.
  */
@@ -187,7 +202,7 @@ tracker_sparql_cursor_class_init (TrackerSparqlCursorClass *klass)
 	/**
 	 * TrackerSparqlCursor:connection:
 	 *
-	 * The #TrackerSparqlConnection used to retrieve the results.
+	 * The [class@Tracker.SparqlConnection] used to retrieve the results.
 	 */
 	props[PROP_CONNECTION] =
 		g_param_spec_object ("connection",
@@ -199,9 +214,9 @@ tracker_sparql_cursor_class_init (TrackerSparqlCursorClass *klass)
 		                     G_PARAM_READABLE |
 		                     G_PARAM_WRITABLE);
 	/**
-	 * TrackerSparqlCursor:n_columns:
+	 * TrackerSparqlCursor:n-columns:
 	 *
-	 * Number of columns available in the results to iterate.
+	 * Number of columns available in the result set.
 	 */
 	props[PROP_N_COLUMNS] =
 		g_param_spec_int ("n-columns",
@@ -216,12 +231,12 @@ tracker_sparql_cursor_class_init (TrackerSparqlCursorClass *klass)
 
 /**
  * tracker_sparql_cursor_get_connection:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
  *
- * Returns the #TrackerSparqlConnection associated with this
- * #TrackerSparqlCursor.
+ * Returns the [class@Tracker.SparqlConnection] associated with this
+ * `TrackerSparqlCursor`.
  *
- * Returns: (transfer none): the cursor #TrackerSparqlConnection. The
+ * Returns: (transfer none): the cursor [class@Tracker.SparqlConnection]. The
  * returned object must not be unreferenced by the caller.
  */
 TrackerSparqlConnection *
@@ -248,14 +263,15 @@ tracker_sparql_cursor_set_connection (TrackerSparqlCursor     *cursor,
 
 /**
  * tracker_sparql_cursor_get_n_columns:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
+ *
+ * Retrieves the number of columns available in the result set.
  *
  * This method should only be called after a successful
- * tracker_sparql_cursor_next(); otherwise its return value
+ * [method@Tracker.SparqlCursor.next], otherwise its return value
  * will be undefined.
  *
- * Returns: a #gint representing the number of columns available in the
- * results to iterate.
+ * Returns: The number of columns returned in the result set.
  */
 gint
 tracker_sparql_cursor_get_n_columns (TrackerSparqlCursor *cursor)
@@ -267,15 +283,19 @@ tracker_sparql_cursor_get_n_columns (TrackerSparqlCursor *cursor)
 
 /**
  * tracker_sparql_cursor_get_string:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
  * @column: column number to retrieve (first one is 0)
  * @length: (out) (nullable): length of the returned string, or %NULL
  *
  * Retrieves a string representation of the data in the current
  * row in @column.
  *
+ * Any type may be converted to a string. If the value is not bound
+ * (See [method@Tracker.SparqlCursor.is_bound]) this method will return %NULL.
+ *
  * Returns: (nullable): a string which must not be freed. %NULL is returned if
- * the column is not in the [0,#n_columns] range.
+ * the column is not in the `[0, n_columns]` range, or if the row/column
+ * refer to a nullable optional value in the result set.
  */
 const gchar *
 tracker_sparql_cursor_get_string (TrackerSparqlCursor *cursor,
@@ -291,12 +311,15 @@ tracker_sparql_cursor_get_string (TrackerSparqlCursor *cursor,
 
 /**
  * tracker_sparql_cursor_get_boolean:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
  * @column: column number to retrieve (first one is 0)
  *
  * Retrieve a boolean for the current row in @column.
  *
- * Returns: a #gboolean.
+ * If the row/column do not have a boolean value, the result is
+ * undefined, see [method@Tracker.SparqlCursor.get_value_type].
+ *
+ * Returns: a boolean value.
  */
 gboolean
 tracker_sparql_cursor_get_boolean (TrackerSparqlCursor *cursor,
@@ -310,12 +333,15 @@ tracker_sparql_cursor_get_boolean (TrackerSparqlCursor *cursor,
 
 /**
  * tracker_sparql_cursor_get_double:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
  * @column: column number to retrieve (first one is 0)
  *
  * Retrieve a double for the current row in @column.
  *
- * Returns: a double.
+ * If the row/column do not have a integer or double value, the result is
+ * undefined, see [method@Tracker.SparqlCursor.get_value_type].
+ *
+ * Returns: a double value.
  */
 gdouble
 tracker_sparql_cursor_get_double (TrackerSparqlCursor *cursor,
@@ -329,12 +355,15 @@ tracker_sparql_cursor_get_double (TrackerSparqlCursor *cursor,
 
 /**
  * tracker_sparql_cursor_get_integer:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
  * @column: column number to retrieve (first one is 0)
  *
  * Retrieve an integer for the current row in @column.
  *
- * Returns: a #gint64.
+ * If the row/column do not have an integer value, the result is
+ * undefined, see [method@Tracker.SparqlCursor.get_value_type].
+ *
+ * Returns: a 64-bit integer value.
  */
 gint64
 tracker_sparql_cursor_get_integer (TrackerSparqlCursor *cursor,
@@ -348,12 +377,23 @@ tracker_sparql_cursor_get_integer (TrackerSparqlCursor *cursor,
 
 /**
  * tracker_sparql_cursor_get_value_type:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
  * @column: column number to retrieve (first one is 0)
  *
- * The data type bound to the current row in @column is returned.
+ * Returns the data type bound to the current row and the given @column.
+ *
+ * If the column is unbound, the value will be %TRACKER_SPARQL_VALUE_TYPE_UNBOUND.
+ * See also [method@Tracker.SparqlCursor.is_bound].
  *
- * Returns: a #TrackerSparqlValueType.
+ * Values of type #TRACKER_SPARQL_VALUE_TYPE_RESOURCE and
+ * #TRACKER_SPARQL_VALUE_TYPE_BLANK_NODE can be considered equivalent, the
+ * difference is the resource being referenced as a named IRI or a blank
+ * node.
+ *
+ * All other [enum@Tracker.SparqlValueType] value types refer to literal values.
+ *
+ * Returns: a [enum@Tracker.SparqlValueType] expressing the content type of
+ *   the given column for the current row.
  */
 TrackerSparqlValueType
 tracker_sparql_cursor_get_value_type (TrackerSparqlCursor *cursor,
@@ -368,12 +408,17 @@ tracker_sparql_cursor_get_value_type (TrackerSparqlCursor *cursor,
 
 /**
  * tracker_sparql_cursor_get_variable_name:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
  * @column: column number to retrieve (first one is 0)
  *
- * Retrieves the variable name for the current row in @column.
+ * Retrieves the name of the given @column.
+ *
+ * This name will be defined at the SPARQL query, either
+ * implicitly from the names of the variables returned in
+ * the resultset, or explicitly through the `AS ?var` SPARQL
+ * syntax.
  *
- * Returns: a string which must not be freed.
+ * Returns: (nullable): The name of the given column.
  */
 const gchar *
 tracker_sparql_cursor_get_variable_name (TrackerSparqlCursor *cursor,
@@ -387,12 +432,14 @@ tracker_sparql_cursor_get_variable_name (TrackerSparqlCursor *cursor,
 
 /**
  * tracker_sparql_cursor_get_datetime:
- * @cursor: a #TrackerSparqlCursor
- * @column: column number to retrieve (first one is 0)
+ * @cursor: a `TrackerSparqlCursor`
+ * @column: Column number to retrieve (first one is 0)
+ *
+ * Retrieves a [type@GLib.DateTime] pointer for the current row in @column.
  *
- * Retrieve an GDateTime pointer for the current row in @column.
+ * Returns: (transfer full) (nullable): [type@GLib.DateTime] object, or %NULL if the given column does not
+ *   contain a [xsd:date](xsd-ontology.html#xsd:date) or [xsd:dateTime](xsd-ontology.html#xsd:dateTime).
  *
- * Returns: (transfer full) (nullable): #GDateTime object, or %NULL if the given column does not contain a xsd:date or xsd:dateTime
  * Since: 3.2
  */
 GDateTime *
@@ -407,9 +454,9 @@ tracker_sparql_cursor_get_datetime (TrackerSparqlCursor *cursor,
 
 /**
  * tracker_sparql_cursor_close:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
  *
- * Closes the iterator, making it invalid.
+ * Closes the cursor. The object can only be freed after this call.
  */
 void
 tracker_sparql_cursor_close (TrackerSparqlCursor *cursor)
@@ -421,10 +468,12 @@ tracker_sparql_cursor_close (TrackerSparqlCursor *cursor)
 
 /**
  * tracker_sparql_cursor_is_bound:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
  * @column: column number to retrieve (first one is 0)
  *
- * If the current row and @column are bound to a value, %TRUE is returned.
+ * Returns whether the given @column has a bound value in the current row.
+ *
+ * This may not be the case through e.g. the `OPTIONAL { }` SPARQL syntax.
  *
  * Returns: a %TRUE or %FALSE.
  */
@@ -439,14 +488,17 @@ tracker_sparql_cursor_is_bound (TrackerSparqlCursor *cursor,
 
 /**
  * tracker_sparql_cursor_next:
- * @cursor: a #TrackerSparqlCursor
- * @cancellable: a #GCancellable used to cancel the operation
- * @error: #GError for error reporting.
+ * @cursor: a `TrackerSparqlCursor`
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
+ *
+ * Iterates the cursor to the next result.
  *
- * Iterates to the next result. This is completely synchronous and
- * it may block.
+ * If the cursor was not started, it will point to the first result after
+ * this call. This operation is completely synchronous and it may block,
+ * see [method@Tracker.SparqlCursor.next_async] for an asynchronous variant.
  *
- * Returns: %FALSE if no more results found, otherwise %TRUE.
+ * Returns: %FALSE if there are no more results or if an error is found, otherwise %TRUE.
  */
 gboolean
 tracker_sparql_cursor_next (TrackerSparqlCursor  *cursor,
@@ -472,13 +524,21 @@ tracker_sparql_cursor_next (TrackerSparqlCursor  *cursor,
 
 /**
  * tracker_sparql_cursor_next_async:
- * @cursor: a #TrackerSparqlCursor
- * @cancellable: a #GCancellable used to cancel the operation
- * @callback: user-defined #GAsyncReadyCallback to be called when
+ * @cursor: a `TrackerSparqlCursor`
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when
  *            asynchronous operation is finished.
  * @user_data: user-defined data to be passed to @callback
  *
- * Iterates, asynchronously, to the next result.
+ * Iterates the cursor asyncronously to the next result.
+ *
+ * If the cursor was not started, it will point to the first result after
+ * this operation completes.
+ *
+ * In the period between this call and the corresponding
+ * [method@Tracker.SparqlCursor.next_finish] call, the other cursor methods
+ * should not be used, nor their results trusted. The cursor should only
+ * be iterated once at a time.
  */
 void
 tracker_sparql_cursor_next_async (TrackerSparqlCursor  *cursor,
@@ -497,13 +557,14 @@ tracker_sparql_cursor_next_async (TrackerSparqlCursor  *cursor,
 
 /**
  * tracker_sparql_cursor_next_finish:
- * @cursor: a #TrackerSparqlCursor
- * @res: a #GAsyncResult with the result of the operation
- * @error: #GError for error reporting.
+ * @cursor: a `TrackerSparqlCursor`
+ * @res: a [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Finishes the asynchronous iteration to the next result.
+ * Finishes the asynchronous iteration to the next result started with
+ * [method@Tracker.SparqlCursor.next_async].
  *
- * Returns: %FALSE if no more results found, otherwise %TRUE.
+ * Returns: %FALSE if there are no more results or if an error is found, otherwise %TRUE.
  */
 gboolean
 tracker_sparql_cursor_next_finish (TrackerSparqlCursor  *cursor,
@@ -529,12 +590,12 @@ tracker_sparql_cursor_next_finish (TrackerSparqlCursor  *cursor,
 
 /**
  * tracker_sparql_cursor_rewind:
- * @cursor: a #TrackerSparqlCursor
+ * @cursor: a `TrackerSparqlCursor`
  *
  * Resets the iterator to point back to the first result.
  *
  * Deprecated: 3.5: This function only works on cursors
- * from direct #TrackerSparqlConnection objects and cannot work
+ * from direct [class@Tracker.SparqlConnection] objects and cannot work
  * reliably across all cursor types. Issue a different query to
  * obtain a new cursor.
  */
diff --git a/src/libtracker-sparql/tracker-cursor.h b/src/libtracker-sparql/tracker-cursor.h
index 2316202e4..f96c44129 100644
--- a/src/libtracker-sparql/tracker-cursor.h
+++ b/src/libtracker-sparql/tracker-cursor.h
@@ -28,12 +28,6 @@
 
 G_BEGIN_DECLS
 
-/**
- * TrackerSparqlCursor:
- *
- * The <structname>TrackerSparqlCursor</structname> object represents an
- * iterator of results.
- */
 #define TRACKER_TYPE_SPARQL_CURSOR tracker_sparql_cursor_get_type ()
 #define TRACKER_SPARQL_TYPE_CURSOR TRACKER_TYPE_SPARQL_CURSOR
 TRACKER_AVAILABLE_IN_ALL
diff --git a/src/libtracker-sparql/tracker-endpoint-dbus.c b/src/libtracker-sparql/tracker-endpoint-dbus.c
index fab046622..542765c78 100644
--- a/src/libtracker-sparql/tracker-endpoint-dbus.c
+++ b/src/libtracker-sparql/tracker-endpoint-dbus.c
@@ -20,23 +20,42 @@
  */
 
 /**
- * SECTION: tracker-endpoint-dbus
- * @short_description: DBus endpoint
- * @title: TrackerEndpointDBus
- * @stability: Stable
- * @include: libtracker-sparql/tracker-sparql.h
+ * TrackerEndpointDBus:
  *
- * #TrackerEndpointDBus is an endpoint implementation that exports
- * a local #TrackerSparqlConnection so it is accessible in the given
- * bus connection.
+ * `TrackerEndpointDBus` makes the RDF data in a [class@Tracker.SparqlConnection]
+ * accessible to other processes via DBus.
+ *
+ * This object is a [class@Tracker.Endpoint] subclass that exports
+ * a [class@Tracker.SparqlConnection] so its RDF data is accessible to other
+ * processes through the given [class@Gio.DBusConnection].
+ *
+ * ```c
+ * // This process already has org.example.Endpoint bus name
+ * endpoint = tracker_endpoint_dbus_new (sparql_connection,
+ *                                       dbus_connection,
+ *                                       NULL,
+ *                                       NULL,
+ *                                       &error);
+ *
+ * // From another process
+ * connection = tracker_sparql_connection_bus_new ("org.example.Endpoint",
+ *                                                 NULL,
+ *                                                 dbus_connection,
+ *                                                 &error);
+ * ```
+ *
+ * The `TrackerEndpointDBus` will manage a DBus object at the given path
+ * with the `org.freedesktop.Tracker3.Endpoint` interface, if no path is
+ * given the object will be at the default `/org/freedesktop/Tracker3/Endpoint`
+ * location.
  *
  * Access to these endpoints may be transparently managed through
  * the Tracker portal service for applications sandboxed via Flatpak, and
  * access to data constrained to the graphs defined in the applications
  * manifest.
  *
- * A #TrackerEndpointDBus may be created on a different thread/main
- * context than the one creating the #TrackerSparqlConnection.
+ * A `TrackerEndpointDBus` may be created on a different thread/main
+ * context from the one that created [class@Tracker.SparqlConnection].
  */
 
 #include "config.h"
@@ -1375,12 +1394,22 @@ tracker_endpoint_dbus_class_init (TrackerEndpointDBusClass *klass)
 	object_class->set_property = tracker_endpoint_dbus_set_property;
 	object_class->get_property = tracker_endpoint_dbus_get_property;
 
+	/**
+	 * TrackerEndpointDBus:dbus-connection:
+	 *
+	 * The [class@Gio.DBusConnection] where the connection is proxied through.
+	 */
 	props[PROP_DBUS_CONNECTION] =
 		g_param_spec_object ("dbus-connection",
 		                     "DBus connection",
 		                     "DBus connection",
 		                     G_TYPE_DBUS_CONNECTION,
 		                     G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY);
+	/**
+	 * TrackerEndpointDBus:object-path:
+	 *
+	 * The DBus object path that this endpoint manages.
+	 */
 	props[PROP_OBJECT_PATH] =
 		g_param_spec_string ("object-path",
 		                     "DBus object path",
@@ -1399,16 +1428,16 @@ tracker_endpoint_dbus_init (TrackerEndpointDBus *endpoint)
 
 /**
  * tracker_endpoint_dbus_new:
- * @sparql_connection: a #TrackerSparqlConnection
- * @dbus_connection: a #GDBusConnection
- * @object_path: (nullable): the object path to use, or %NULL for the default
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @error: pointer to a #GError
+ * @sparql_connection: The [class@Tracker.SparqlConnection] being made public
+ * @dbus_connection: #GDBusConnection to expose the DBus object over
+ * @object_path: (nullable): The object path to use, or %NULL to use the default
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
  *
  * Registers a Tracker endpoint object at @object_path on @dbus_connection.
- * The default object path is "/org/freedesktop/Tracker3/Endpoint".
+ * The default object path is `/org/freedesktop/Tracker3/Endpoint`.
  *
- * Returns: (transfer full): a #TrackerEndpointDBus object.
+ * Returns: (transfer full): a `TrackerEndpointDBus` object.
  */
 TrackerEndpointDBus *
 tracker_endpoint_dbus_new (TrackerSparqlConnection  *sparql_connection,
diff --git a/src/libtracker-sparql/tracker-endpoint-dbus.h b/src/libtracker-sparql/tracker-endpoint-dbus.h
index 8c999f3ec..5f47eac9a 100644
--- a/src/libtracker-sparql/tracker-endpoint-dbus.h
+++ b/src/libtracker-sparql/tracker-endpoint-dbus.h
@@ -38,12 +38,6 @@ G_BEGIN_DECLS
 #define TRACKER_IS_ENDPOINT_DBUS_CLASS(c)  (G_TYPE_CHECK_CLASS_TYPE ((c),  TRACKER_TYPE_ENDPOINT_DBUS))
 #define TRACKER_ENDPOINT_DBUS_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), TRACKER_TYPE_ENDPOINT_DBUS, TrackerEndpointDBusClass))
 
-/**
- * TrackerEndpointDBus:
- *
- * The <structname>TrackerEndpointDBus</structname> object represents a public
- * connection to a #TrackerSparqlConnection on a DBus object path.
- */
 typedef struct _TrackerEndpointDBus TrackerEndpointDBus;
 
 G_DEFINE_AUTOPTR_CLEANUP_FUNC (TrackerEndpointDBus, g_object_unref)
diff --git a/src/libtracker-sparql/tracker-endpoint-http.c b/src/libtracker-sparql/tracker-endpoint-http.c
index e38bb78bb..6ae2340ae 100644
--- a/src/libtracker-sparql/tracker-endpoint-http.c
+++ b/src/libtracker-sparql/tracker-endpoint-http.c
@@ -20,33 +20,49 @@
  */
 
 /**
- * SECTION: tracker-endpoint-http
- * @short_description: HTTP endpoint
- * @title: TrackerEndpointHttp
- * @stability: Stable
- * @include: libtracker-sparql/tracker-sparql.h
+ * TrackerEndpointHttp:
  *
- * #TrackerEndpointHttp is an endpoint implementation that exports
- * a local #TrackerSparqlConnection so it is accessible via HTTP
- * requests.
+ * `TrackerEndpointHttp` makes the RDF data in a [class@Tracker.SparqlConnection]
+ * accessible to other hosts via HTTP.
  *
- * Access to these endpoints may be managed via the
- * #TrackerEndpointHttp::block-remote-address signal, the boolean
+ * This object is a [class@Tracker.Endpoint] subclass that exports
+ * a [class@Tracker.SparqlConnection] so its RDF data is accessible via HTTP
+ * requests on the given port. This endpoint implementation is compliant
+ * with the [SPARQL protocol specifications](https://www.w3.org/TR/2013/REC-sparql11-protocol-20130321/)
+ * and may interoperate with other implementations.
+ *
+ * ```c
+ * // This host has "example.local" hostname
+ * endpoint = tracker_endpoint_http_new (sparql_connection,
+ *                                       8080,
+ *                                       tls_certificate,
+ *                                       NULL,
+ *                                       &error);
+ *
+ * // From another host
+ * connection = tracker_sparql_connection_remote_new ("http://example.local:8080/sparql");
+ * ```
+ *
+ * Access to HTTP endpoints may be managed via the
+ * [signal@Tracker.EndpointHttp::block-remote-address] signal, the boolean
  * return value expressing whether the connection is blocked or not.
  * Inspection of the requester address is left up to the user. The
  * default value allows all requests independently of their provenance,
  * users are encouraged to add a handler.
  *
- * If the provided #GTlsCertificate is %NULL, the endpoint will allow
+ * If the provided [class@Gio.TlsCertificate] is %NULL, the endpoint will allow
  * plain HTTP connections. Users are encouraged to provide a certificate
  * in order to use HTTPS.
  *
- * As a security measure, and in compliance with the SPARQL 1.1 specifications,
- * the HTTP endpoint does not support database updates or modifications in any
- * way. The database is completely owned by the host.
+ * As a security measure, and in compliance specifications,
+ * the HTTP endpoint does not handle database updates or modifications in any
+ * way. The database content is considered to be entirely managed by the
+ * process that creates the HTTP endpoint and owns the [class@Tracker.SparqlConnection].
  *
- * A #TrackerEndpointHttp may be created on a different thread/main
- * context than the one creating the #TrackerSparqlConnection.
+ * A `TrackerEndpointHttp` may be created on a different thread/main
+ * context from the one that created [class@Tracker.SparqlConnection].
+ *
+ * Since: 3.1
  */
 
 #include "config.h"
@@ -388,7 +404,7 @@ tracker_endpoint_http_class_init (TrackerEndpointHttpClass *klass)
 
 	/**
 	 * TrackerEndpointHttp::block-remote-address:
-	 * @self: The #TrackerNotifier
+	 * @self: The `TrackerEndpointHttp`
 	 * @address: The socket address of the remote connection
 	 *
 	 * Allows control over the connections stablished. The given
@@ -404,6 +420,11 @@ tracker_endpoint_http_class_init (TrackerEndpointHttpClass *klass)
 		              g_signal_accumulator_first_wins, NULL, NULL,
 		              G_TYPE_BOOLEAN, 1, G_TYPE_SOCKET_ADDRESS);
 
+	/**
+	 * TrackerEndpointHttp:http-port:
+	 *
+	 * HTTP port used to listen requests.
+	 */
 	props[PROP_HTTP_PORT] =
 		g_param_spec_uint ("http-port",
 		                   "HTTP Port",
@@ -411,6 +432,11 @@ tracker_endpoint_http_class_init (TrackerEndpointHttpClass *klass)
 		                   0, G_MAXUINT,
 		                   8080,
 		                   G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY);
+	/**
+	 * TrackerEndpointHttp:http-certificate:
+	 *
+	 * [class@Gio.TlsCertificate] to encrypt the communication.
+	 */
 	props[PROP_HTTP_CERTIFICATE] =
 		g_param_spec_object ("http-certificate",
 		                     "HTTP certificate",
@@ -429,17 +455,17 @@ tracker_endpoint_http_init (TrackerEndpointHttp *endpoint)
 
 /**
  * tracker_endpoint_http_new:
- * @sparql_connection: a #TrackerSparqlConnection
- * @port: HTTP port to listen to
- * @certificate: (nullable): certificate to use for encription, or %NULL
- * @cancellable: (nullable): a #GCancellable, or %NULL
- * @error: pointer to a #GError
+ * @sparql_connection: The [class@Tracker.SparqlConnection] being made public
+ * @port: HTTP port to handle incoming requests
+ * @certificate: (nullable): Optional [type@Gio.TlsCertificate] to use for encription
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
  *
  * Sets up a Tracker endpoint to listen via HTTP, in the given @port.
  * If @certificate is not %NULL, HTTPS may be used to connect to the
  * endpoint.
  *
- * Returns: (transfer full): a #TrackerEndpointDBus object.
+ * Returns: (transfer full): a `TrackerEndpointHttp` object.
  *
  * Since: 3.1
  **/
diff --git a/src/libtracker-sparql/tracker-endpoint-http.h b/src/libtracker-sparql/tracker-endpoint-http.h
index be6e6f408..a3c5a9dfa 100644
--- a/src/libtracker-sparql/tracker-endpoint-http.h
+++ b/src/libtracker-sparql/tracker-endpoint-http.h
@@ -33,17 +33,8 @@ G_BEGIN_DECLS
 
 #define TRACKER_TYPE_ENDPOINT_HTTP         (tracker_endpoint_http_get_type())
 #define TRACKER_ENDPOINT_HTTP(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), TRACKER_TYPE_ENDPOINT_HTTP, TrackerEndpointHttp))
-#define TRACKER_ENDPOINT_HTTP_CLASS(c)     (G_TYPE_CHECK_CLASS_CAST ((c), TRACKER_TYPE_ENDPOINT_HTTP, TrackerEndpointHttpClass))
 #define TRACKER_IS_ENDPOINT_HTTP(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), TRACKER_TYPE_ENDPOINT_HTTP))
-#define TRACKER_IS_ENDPOINT_HTTP_CLASS(c)  (G_TYPE_CHECK_CLASS_TYPE ((c),  TRACKER_TYPE_ENDPOINT_HTTP))
-#define TRACKER_ENDPOINT_HTTP_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), TRACKER_TYPE_ENDPOINT_HTTP, TrackerEndpointHttpClass))
 
-/**
- * TrackerEndpointHttp:
- *
- * The <structname>TrackerEndpointHttp</structname> object represents a public
- * connection to a #TrackerSparqlConnection on a HTTP port.
- */
 typedef struct _TrackerEndpointHttp TrackerEndpointHttp;
 
 G_DEFINE_AUTOPTR_CLEANUP_FUNC (TrackerEndpointHttp, g_object_unref)
diff --git a/src/libtracker-sparql/tracker-endpoint.c b/src/libtracker-sparql/tracker-endpoint.c
index f404e3f0c..10f3cb8be 100644
--- a/src/libtracker-sparql/tracker-endpoint.c
+++ b/src/libtracker-sparql/tracker-endpoint.c
@@ -39,20 +39,21 @@ typedef struct {
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (TrackerEndpoint, tracker_endpoint, G_TYPE_OBJECT)
 
 /**
- * SECTION: tracker-endpoint
- * @short_description: Expose a database outside the process
- * @title: TrackerEndpoint
- * @stability: Stable
- * @include: tracker-endpoint.h
+ * TrackerEndpoint:
  *
- * #TrackerEndpoint allows sharing data, either with other processes on the
- * system via a Tracker-specific D-Bus API, or remote peers via the HTTP
- * SPARQL protocol.
+ * `TrackerEndpoint` is a helper object to make RDF triple stores represented
+ * by a [class@Tracker.SparqlConnection] publicly available to other processes/hosts.
  *
- * When it is shared in this way, other peers can connect to your database using
- * tracker_sparql_connection_bus_new() or tracker_sparql_connection_remote_new(),
- * and can also fetch data directly from SPARQL queries using the
- * <userinput>SELECT { SERVICE ... }</userinput> syntax.
+ * This is a base abstract object, see [class@Tracker.EndpointDBus] to make
+ * RDF triple stores available to other processes in the same machine, and
+ * [class@Tracker.EndpointHttp] to make it available to other hosts in the
+ * network.
+ *
+ * When the RDF triple store represented by a [class@Tracker.SparqlConnection]
+ * is made public this way, other peers may connect to the database using
+ * [ctor@Tracker.SparqlConnection.bus_new] or [ctor@Tracker.SparqlConnection.remote_new]
+ * to access this endpoint exclusively, or they may use the `SERVICE <uri> { ... }` SPARQL
+ * syntax from their own [class@Tracker.SparqlConnection]s to expand their data set.
  */
 
 static void
@@ -113,6 +114,11 @@ tracker_endpoint_class_init (TrackerEndpointClass *klass)
 	object_class->set_property = tracker_endpoint_set_property;
 	object_class->get_property = tracker_endpoint_get_property;
 
+	/**
+	 * TrackerEndpoint:sparql-connection:
+	 *
+	 * The [class@Tracker.SparqlConnection] being proxied by this endpoint.
+	 */
 	props[PROP_SPARQL_CONNECTION] =
 		g_param_spec_object ("sparql-connection",
 		                     "Sparql connection",
@@ -129,9 +135,10 @@ tracker_endpoint_init (TrackerEndpoint *endpoint)
 
 /**
  * tracker_endpoint_get_sparql_connection:
- * @endpoint: a #TrackerEndpoint
+ * @endpoint: a `TrackerEndpoint`
  *
- * Returns the #TrackerSparqlConnection that this endpoint proxies.
+ * Returns the [class@Tracker.SparqlConnection] that this endpoint proxies
+ * to a wider audience.
  *
  * Returns: (transfer none): The proxied SPARQL connection
  **/
diff --git a/src/libtracker-sparql/tracker-endpoint.h b/src/libtracker-sparql/tracker-endpoint.h
index b764f5e35..4bcddda84 100644
--- a/src/libtracker-sparql/tracker-endpoint.h
+++ b/src/libtracker-sparql/tracker-endpoint.h
@@ -32,12 +32,6 @@
 
 G_BEGIN_DECLS
 
-/**
- * TrackerEndpoint:
- *
- * The <structname>TrackerEndpoint</structname> object represents a public
- * connection to a #TrackerSparqlConnection.
- */
 #define TRACKER_TYPE_ENDPOINT tracker_endpoint_get_type()
 TRACKER_AVAILABLE_IN_ALL
 G_DECLARE_DERIVABLE_TYPE (TrackerEndpoint, tracker_endpoint, TRACKER, ENDPOINT, GObject)
diff --git a/src/libtracker-sparql/tracker-error.c b/src/libtracker-sparql/tracker-error.c
index e2d1aa374..c9964382b 100644
--- a/src/libtracker-sparql/tracker-error.c
+++ b/src/libtracker-sparql/tracker-error.c
@@ -43,11 +43,6 @@ static const GDBusErrorEntry tracker_sparql_error_entries[] =
 
 G_STATIC_ASSERT (G_N_ELEMENTS (tracker_sparql_error_entries) == TRACKER_SPARQL_N_ERRORS);
 
-/**
- * tracker_sparql_error_quark:
- *
- * Returns: The error domain quark used for Tracker errors.
- **/
 GQuark
 tracker_sparql_error_quark (void)
 {
diff --git a/src/libtracker-sparql/tracker-error.h b/src/libtracker-sparql/tracker-error.h
index 3ea9729a2..40ff3a709 100644
--- a/src/libtracker-sparql/tracker-error.h
+++ b/src/libtracker-sparql/tracker-error.h
@@ -27,14 +27,6 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION: tracker-sparql-error
- * @short_description: Error codes
- * @title: TrackerSparqlError
- * @stability: Stable
- * @include: tracker-sparql.h
- */
-
-/**
  * TrackerSparqlError:
  * @TRACKER_SPARQL_ERROR_CONSTRAINT: Subject is not in the domain of a property or
  *                             trying to set multiple values for a single valued
@@ -56,7 +48,7 @@ G_BEGIN_DECLS
  * @TRACKER_SPARQL_ERROR_LAST: The total number of error codes.
  *
  * Error domain for Tracker Sparql. Errors in this domain will be from the
- * #TrackerSparqlError enumeration. See #GError for more information on error
+ * [error@Tracker.SparqlError] enumeration. See [struct@GLib.Error] for more information on error
  * domains.
  */
 typedef enum {
@@ -79,7 +71,7 @@ typedef enum {
 } TrackerSparqlError;
 
 #define TRACKER_SPARQL_N_ERRORS TRACKER_SPARQL_ERROR_LAST
-#define TRACKER_SPARQL_ERROR tracker_sparql_error_quark ()
+#define TRACKER_SPARQL_ERROR (tracker_sparql_error_quark ())
 
 TRACKER_AVAILABLE_IN_ALL
 GQuark tracker_sparql_error_quark (void);
diff --git a/src/libtracker-sparql/tracker-namespace-manager.c b/src/libtracker-sparql/tracker-namespace-manager.c
index f2eabdf00..2e13e3a8c 100644
--- a/src/libtracker-sparql/tracker-namespace-manager.c
+++ b/src/libtracker-sparql/tracker-namespace-manager.c
@@ -47,21 +47,19 @@ G_DEFINE_TYPE_WITH_PRIVATE (TrackerNamespaceManager, tracker_namespace_manager,
 #define GET_PRIVATE(object)  (tracker_namespace_manager_get_instance_private (object))
 
 /**
- * SECTION: tracker-namespace-manager
- * @short_description: A set of well-known namespaces, and known abbreviations for them
- * @title: TrackerNamespaceManager
- * @stability: Stable
- * @include: libtracker-sparql/tracker-sparql.h
+ * TrackerNamespaceManager:
  *
- * #TrackerNamespaceManager keeps track of namespaces. It allows you to assign
- * short prefixes for them to avoid typing full URLs all the time.
+ * `TrackerNamespaceManager` object represents a mapping between namespaces and
+ * their shortened prefixes.
  *
- * The syntax used is that of Compact URIs (CURIEs) as defined here:
- * (https://www.w3.org/TR/2010/NOTE-curie-20101216)
+ * This object keeps track of namespaces, and allows you to assign
+ * short prefixes for them to avoid frequent use of full namespace IRIs. The syntax
+ * used is that of [Compact URIs (CURIEs)](https://www.w3.org/TR/2010/NOTE-curie-20101216).
  *
- * Usually you will want to use the default namespace manager, as returned by
- * tracker_namespace_manager_get_default(). This has a set of well-known
- * prefixes predefined.
+ * Usually you will want to use a namespace manager obtained through
+ * [method@Tracker.SparqlConnection.get_namespace_manager] from the
+ * [class@Tracker.SparqlConnection] that manages the RDF data, as that will
+ * contain all prefixes and namespaces that are pre-defined by its ontology.
  */
 
 static void finalize     (GObject *object);
@@ -101,9 +99,9 @@ finalize (GObject *object)
 /**
  * tracker_namespace_manager_new:
  *
- * Creates a new #TrackerNamespaceManager instance.
+ * Creates a new, empty `TrackerNamespaceManager` instance.
  *
- * Returns: a new #TrackerNamespaceManager instance
+ * Returns: a new `TrackerNamespaceManager` instance
  */
 TrackerNamespaceManager *
 tracker_namespace_manager_new ()
@@ -118,16 +116,16 @@ tracker_namespace_manager_new ()
 /**
  * tracker_namespace_manager_get_default:
  *
- * Returns the global #TrackerNamespaceManager that contains a set of well-known
- * namespaces and prefixes, such as rdf:, rdfs:, nie:, tracker:, etc.
+ * Returns the global `TrackerNamespaceManager` that contains a set of well-known
+ * namespaces and prefixes, such as `rdf:`, `rdfs:`, `nie:`, `tracker:`, etc.
  *
  * Note that the list of prefixes and namespaces is hardcoded in
  * libtracker-sparql. It may not correspond with the installed set of
  * ontologies, if they have been modified since they were installed.
  *
- * Returns: (transfer none): a global, shared #TrackerNamespaceManager instance
+ * Returns: (transfer none): a global, shared `TrackerNamespaceManager` instance
  *
- * Deprecated: 3.3: Use tracker_sparql_connection_get_namespace_manager() instead.
+ * Deprecated: 3.3: Use [method@Tracker.SparqlConnection.get_namespace_manager] instead.
  */
 TrackerNamespaceManager *
 tracker_namespace_manager_get_default ()
@@ -164,12 +162,12 @@ tracker_namespace_manager_get_default ()
 
 /**
  * tracker_namespace_manager_has_prefix:
- * @self: a #TrackerNamespaceManager
+ * @self: a `TrackerNamespaceManager`
  * @prefix: a string
  *
  * Returns whether @prefix is known.
  *
- * Returns: %TRUE if the #TrackerNamespaceManager knows about @prefix, %FALSE otherwise
+ * Returns: %TRUE if the `TrackerNamespaceManager` knows about @prefix, %FALSE otherwise
  */
 gboolean
 tracker_namespace_manager_has_prefix (TrackerNamespaceManager *self,
@@ -186,13 +184,13 @@ tracker_namespace_manager_has_prefix (TrackerNamespaceManager *self,
 
 /**
  * tracker_namespace_manager_lookup_prefix:
- * @self: a #TrackerNamespaceManager
+ * @self: a `TrackerNamespaceManager`
  * @prefix: a string
  *
  * Looks up the namespace URI corresponding to @prefix, or %NULL if the prefix
  * is not known.
  *
- * Returns: (nullable): a string owned by the #TrackerNamespaceManager, or %NULL
+ * Returns: (nullable): a string owned by the `TrackerNamespaceManager`, or %NULL
  */
 const char *
 tracker_namespace_manager_lookup_prefix (TrackerNamespaceManager *self,
@@ -209,7 +207,7 @@ tracker_namespace_manager_lookup_prefix (TrackerNamespaceManager *self,
 
 /**
  * tracker_namespace_manager_add_prefix:
- * @self: a #TrackerNamespaceManager
+ * @self: A `TrackerNamespaceManager`
  * @prefix: a short, unique prefix to identify @namespace
  * @ns: the URL of the given namespace
  *
@@ -218,9 +216,9 @@ tracker_namespace_manager_lookup_prefix (TrackerNamespaceManager *self,
  * Only one prefix is allowed for a given namespace, and all prefixes must
  * be unique.
  *
- * Since 3.3, This function may not be used on #TrackerNamespaceManager
- * instances that were obtained through
- * tracker_sparql_connection_get_namespace_manager().
+ * Since 3.3, The `TrackerNamespaceManager` instances obtained through
+ * [method@Tracker.SparqlConnection.get_namespace_manager] are "sealed",
+ * this API call should not performed on those.
  */
 void
 tracker_namespace_manager_add_prefix (TrackerNamespaceManager *self,
@@ -270,14 +268,14 @@ tracker_namespace_manager_add_prefix (TrackerNamespaceManager *self,
 
 /**
  * tracker_namespace_manager_expand_uri:
- * @self: a #TrackerNamespaceManager
+ * @self: a `TrackerNamespaceManager`
  * @compact_uri: a URI or compact URI
  *
  * If @compact_uri begins with one of the prefixes known to this
- * #TrackerNamespaceManager, then the return value will be the
+ * `TrackerNamespaceManager`, then the return value will be the
  * expanded URI. Otherwise, a copy of @compact_uri will be returned.
  *
- * Returns: a newly-allocated string
+ * Returns: The possibly expanded URI in a newly-allocated string.
  */
 char *
 tracker_namespace_manager_expand_uri (TrackerNamespaceManager *self,
@@ -314,11 +312,11 @@ tracker_namespace_manager_expand_uri (TrackerNamespaceManager *self,
 
 /**
  * tracker_namespace_manager_compress_uri:
- * @self: a #TrackerNamespaceManager
+ * @self: a `TrackerNamespaceManager`
  * @uri: a URI or compact URI
  *
  * If @uri begins with one of the namespaces known to this
- * #TrackerNamespaceManager, then the return value will be the
+ * `TrackerNamespaceManager`, then the return value will be the
  * compressed URI. Otherwise, %NULL will be returned.
  *
  * Returns: (transfer full): (nullable): the compressed URI
@@ -360,9 +358,10 @@ tracker_namespace_manager_compress_uri (TrackerNamespaceManager *self,
 
 /**
  * tracker_namespace_manager_print_turtle:
- * @self: a #TrackerNamespaceManager
+ * @self: a `TrackerNamespaceManager`
  *
- * Writes out all namespaces as Turtle @prefix statements.
+ * Writes out all namespaces as `@prefix` statements in
+ * the [Turtle](https://www.w3.org/TR/turtle/) RDF format.
  *
  * Returns: a newly-allocated string
  */
@@ -391,7 +390,7 @@ tracker_namespace_manager_print_turtle (TrackerNamespaceManager *self)
 
 /**
  * tracker_namespace_manager_foreach:
- * @self: a #TrackerNamespaceManager
+ * @self: a `TrackerNamespaceManager`
  * @func: (scope call): the function to call for each prefix / URI pair
  * @user_data: user data to pass to the function
  *
diff --git a/src/libtracker-sparql/tracker-namespace-manager.h b/src/libtracker-sparql/tracker-namespace-manager.h
index 04e081356..f418cc71d 100644
--- a/src/libtracker-sparql/tracker-namespace-manager.h
+++ b/src/libtracker-sparql/tracker-namespace-manager.h
@@ -30,12 +30,6 @@ G_BEGIN_DECLS
 
 #include <libtracker-sparql/tracker-version.h>
 
-/**
- * TrackerNamespaceManager:
- *
- * The <structname>TrackerNamespaceManager</structname> object represents a
- * mapping of prefixes and namespaces.
- */
 #define TRACKER_TYPE_NAMESPACE_MANAGER (tracker_namespace_manager_get_type())
 TRACKER_AVAILABLE_IN_ALL
 G_DECLARE_FINAL_TYPE (TrackerNamespaceManager, tracker_namespace_manager, TRACKER, NAMESPACE_MANAGER, GObject)
diff --git a/src/libtracker-sparql/tracker-notifier.c b/src/libtracker-sparql/tracker-notifier.c
index 78056c2c0..1ac26e019 100644
--- a/src/libtracker-sparql/tracker-notifier.c
+++ b/src/libtracker-sparql/tracker-notifier.c
@@ -18,30 +18,36 @@
  */
 
 /**
- * SECTION: tracker-notifier
- * @title: TrackerNotifier
- * @short_description: Listen to changes in the Tracker database
- * @stability: Stable
- * @include: libtracker-sparql/tracker-sparql.h
+ * TrackerNotifier:
  *
- * #TrackerNotifier is an object that receives notifications about
- * changes to the Tracker database. A #TrackerNotifier is created
- * through tracker_sparql_connection_create_notifier(), after the notifier
- * is created, events can be listened for by connecting to the
- * #TrackerNotifier::events signal.
+ * `TrackerNotifier` allows receiving notification on changes
+ * in the data stored by a [class@Tracker.SparqlConnection].
  *
- * # Known caveats
+ * This object may be created through [method@Tracker.SparqlConnection.create_notifier],
+ * events can then be listened for by connecting to the
+ * [signal@Tracker.Notifier::events] signal.
  *
- * * The %TRACKER_NOTIFIER_EVENT_DELETE events will be received after the
- *   resource has been deleted. At that time queries on those elements will
- *   not bring any metadata. Only the ID/URN obtained through the event
- *   remain meaningful.
- * * Notifications of files being moved across indexed folders will
- *   appear as %TRACKER_NOTIFIER_EVENT_UPDATE events, containing
- *   the new location (if requested). The older location is no longer
- *   known to Tracker, this may make tracking of elements in specific
- *   folders hard using solely the #TrackerNotifier/Tracker data
- *   available at event notification time.
+ * Not every change is notified, only RDF resources with a
+ * class that has the [nrl:notify](nrl-ontology.html#nrl:notify)
+ * property defined by the ontology will be notified upon changes.
+ *
+ * Database changes are communicated through [struct@Tracker.NotifierEvent] events on
+ * individual graph/resource pairs. The event type obtained through
+ * [method@Tracker.NotifierEvent.get_event_type] will determine the type of event.
+ * Insertion of new resources is notified through
+ * %TRACKER_NOTIFIER_EVENT_CREATE events, deletion of
+ * resources is notified through %TRACKER_NOTIFIER_EVENT_DELETE
+ * events, and changes on any property of the resource is notified
+ * through %TRACKER_NOTIFIER_EVENT_UPDATE events.
+ *
+ * The events happen in reaction to database changes, after a `TrackerNotifier`
+ * received an event of type %TRACKER_NOTIFIER_EVENT_DELETE, the resource will
+ * not exist anymore and only the information in the [struct@Tracker.NotifierEvent]
+ * will remain.
+ *
+ * Similarly, when receiving an event of type %TRACKER_NOTIFIER_EVENT_UPDATE,
+ * the resource will have already changed, so the data previous to the update is
+ * no longer available.
  */
 
 #include "config.h"
@@ -745,10 +751,10 @@ tracker_notifier_class_init (TrackerNotifierClass *klass)
 
 	/**
 	 * TrackerNotifier::events:
-	 * @self: The #TrackerNotifier
+	 * @self: The `TrackerNotifier`
 	 * @service: The SPARQL service that originated the events, %NULL for the local store
 	 * @graph: The graph where the events happened on, %NULL for the default anonymous graph
-	 * @events: (element-type TrackerNotifierEvent): A #GPtrArray of #TrackerNotifierEvent
+	 * @events: (transfer none) (type GLib.PtrArray) (element-type TrackerNotifierEvent): A [type@GLib.PtrArray] of [struct@Tracker.NotifierEvent]
 	 *
 	 * Notifies of changes in the Tracker database.
 	 */
@@ -793,23 +799,26 @@ tracker_notifier_init (TrackerNotifier *notifier)
 
 /**
  * tracker_notifier_signal_subscribe:
- * @notifier: a #TrackerNotifier
- * @connection: a #GDBusConnection
+ * @notifier: A `TrackerNotifier`
+ * @connection: A [class@Gio.DBusConnection]
  * @service: DBus service name to subscribe to events for
  * @object_path: (nullable): DBus object path to subscribe to events for, or %NULL
- * @graph: (nullable): graph to listen events for, or %NULL
+ * @graph: (nullable): Graph to listen events for, or %NULL
  *
- * Listens to notification events from a remote SPARQL endpoint as a DBus
- * service (see #TrackerEndpointDBus). If the @object_path argument is
- * %NULL, the default "/org/freedesktop/Tracker3/Endpoint" path will be
+ * Listens to notification events from a remote DBus SPARQL endpoint.
+ *
+ * If the @object_path argument is %NULL, the default
+ * `/org/freedesktop/Tracker3/Endpoint` path will be
  * used. If @graph is %NULL, all graphs will be listened for.
  *
  * The signal subscription can be removed with
- * tracker_notifier_signal_unsubscribe().
+ * [method@Tracker.Notifier.signal_unsubscribe].
  *
- * Returns: An ID for this subscription
+ * Note that this call is not necessary to receive notifications on
+ * a connection obtained through [ctor@Tracker.SparqlConnection.bus_new],
+ * only to listen to update notifications from additional DBus endpoints.
  *
- * Since: 3.0
+ * Returns: An ID for this subscription
  **/
 guint
 tracker_notifier_signal_subscribe (TrackerNotifier *notifier,
@@ -874,13 +883,12 @@ tracker_notifier_signal_subscribe (TrackerNotifier *notifier,
 
 /**
  * tracker_notifier_signal_unsubscribe:
- * @notifier: a #TrackerNotifier
- * @handler_id: a handler ID obtained with tracker_notifier_signal_subscribe()
+ * @notifier: A `TrackerNotifier`
+ * @handler_id: A signal subscription handler ID
  *
- * Undoes a DBus signal subscription, the @handler_id argument was previously
- * obtained with a tracker_notifier_signal_subscribe() call.
+ * Undoes a signal subscription done through [method@Tracker.Notifier.signal_subscribe].
  *
- * Since: 3.0
+ * The @handler_id argument was previously obtained during signal subscription creation.
  **/
 void
 tracker_notifier_signal_unsubscribe (TrackerNotifier *notifier,
@@ -908,7 +916,7 @@ _tracker_notifier_get_connection (TrackerNotifier *notifier)
 
 /**
  * tracker_notifier_event_get_event_type:
- * @event: A #TrackerNotifierEvent
+ * @event: A `TrackerNotifierEvent`
  *
  * Returns the event type.
  *
@@ -923,7 +931,7 @@ tracker_notifier_event_get_event_type (TrackerNotifierEvent *event)
 
 /**
  * tracker_notifier_event_get_id:
- * @event: A #TrackerNotifierEvent
+ * @event: A `TrackerNotifierEvent`
  *
  * Returns the tracker:id of the element being notified upon. This is a #gint64
  * which is used as efficient internal identifier for the resource.
@@ -939,13 +947,13 @@ tracker_notifier_event_get_id (TrackerNotifierEvent *event)
 
 /**
  * tracker_notifier_event_get_urn:
- * @event: A #TrackerNotifierEvent
+ * @event: A `TrackerNotifierEvent`
  *
  * Returns the Uniform Resource Name of the element. This is Tracker's
  * public identifier for the resource.
  *
  * This URN is an unique string identifier for the resource being
- * notified upon, typically of the form "urn:uuid:...".
+ * notified upon, typically of the form `urn:uuid:...`.
  *
  * Returns: The element URN
  **/
diff --git a/src/libtracker-sparql/tracker-notifier.h b/src/libtracker-sparql/tracker-notifier.h
index 962d03198..aff34e3c4 100644
--- a/src/libtracker-sparql/tracker-notifier.h
+++ b/src/libtracker-sparql/tracker-notifier.h
@@ -32,12 +32,6 @@ G_BEGIN_DECLS
 #define TRACKER_TYPE_NOTIFIER (tracker_notifier_get_type ())
 #define TRACKER_TYPE_NOTIFIER_EVENT (tracker_notifier_event_get_type ())
 
-/**
- * TrackerNotifier:
- *
- * The <structname>TrackerNotifier</structname> object allows subscribing
- * to changes in the stored data.
- */
 TRACKER_AVAILABLE_IN_ALL
 G_DECLARE_DERIVABLE_TYPE (TrackerNotifier, tracker_notifier, TRACKER, NOTIFIER, GObject)
 
diff --git a/src/libtracker-sparql/tracker-ontologies.h b/src/libtracker-sparql/tracker-ontologies.h
index 8713b4fb6..bb678b67f 100644
--- a/src/libtracker-sparql/tracker-ontologies.h
+++ b/src/libtracker-sparql/tracker-ontologies.h
@@ -18,17 +18,6 @@
  * Boston, MA  02110-1301, USA.
  */
 
-/**
- * SECTION: tracker-ontologies
- * @short_description: Utility prefix definitions for common ontologies
- * @title: Utility Ontology Defines
- * @stability: Stable
- * @include: libtracker-sparql/tracker-sparql.h
- *
- * Utility defines for the common namespace prefixes.
- */
-
-
 #ifndef __LIBTRACKER_SPARQL_ONTOLOGIES_H__
 #define __LIBTRACKER_SPARQL_ONTOLOGIES_H__
 
diff --git a/src/libtracker-sparql/tracker-resource.c b/src/libtracker-sparql/tracker-resource.c
index ab579135b..1d06d0841 100644
--- a/src/libtracker-sparql/tracker-resource.c
+++ b/src/libtracker-sparql/tracker-resource.c
@@ -47,14 +47,37 @@ G_DEFINE_TYPE_WITH_PRIVATE (TrackerResource, tracker_resource, G_TYPE_OBJECT)
 #define GET_PRIVATE(object)  (tracker_resource_get_instance_private (object))
 
 /**
- * SECTION: tracker-resource
- * @short_description: Represents a single Tracker resource
- * @title: TrackerResource
- * @stability: Stable
- * @include: tracker-resource.h
- *
- * #TrackerResource keeps track of a set of properties for a given resource.
- * The resulting data can be serialized in several ways.
+ * TrackerResource:
+ *
+ * `TrackerResource` is an in-memory representation of RDF data about a given resource.
+ *
+ * This object keeps track of a set of properties for a given resource, and can
+ * also link to other `TrackerResource` objects to form trees or graphs of RDF
+ * data. See [method@Tracker.Resource.set_relation] and [method@Tracker.Resource.set_uri]
+ * on how to link a `TrackerResource` to other RDF data.
+ *
+ * `TrackerResource` may also hold data about literal values, added through
+ * the specialized [method@Tracker.Resource.set_int64], [method@Tracker.Resource.set_string],
+ * etc family of functions, or the generic [method@Tracker.Resource.set_gvalue] method.
+ *
+ * Since RDF properties may be multi-valued, for every `set` call there exists
+ * another `add` call (e.g. [method@Tracker.Resource.add_int64], [method@Tracker.Resource.add_string]
+ * and so on). The `set` methods do also reset any previously value the
+ * property might hold for the given resource.
+ *
+ * Resources may have an IRI set at creation through [ctor@Tracker.Resource.new],
+ * or set afterwards through [method@Tracker.Resource.set_identifier]. Resources
+ * without a name will represent a blank node, and will be dealt with as such
+ * during database insertions.
+ *
+ * `TrackerResource` performs no validation on the data being coherent as per
+ * any ontology. Errors will be found out at the time of using the TrackerResource
+ * for e.g. database updates.
+ *
+ * Once the RDF data is built in memory, the (tree of) `TrackerResource` may be
+ * converted to a RDF format through [method@Tracker.Resource.print_rdf], or
+ * directly inserted into a database through [method@Tracker.Batch.add_resource]
+ * or [method@Tracker.SparqlConnection.update_resource].
  */
 
 static char *
@@ -65,13 +88,6 @@ generate_blank_node_identifier (void)
 	return g_strdup_printf("_:%" G_GINT64_FORMAT, counter++);
 }
 
-/**
- * TrackerResource:
- *
- * The <structname>TrackerResource</structname> object represents information
- * about a given resource.
- */
-
 enum {
 	PROP_0,
 
@@ -247,7 +263,7 @@ set_property (GObject      *object,
  *
  * Creates a TrackerResource instance.
  *
- * Returns: a newly created #TrackerResource. Free with g_object_unref() when done
+ * Returns: a newly created `TrackerResource`.
  */
 TrackerResource *
 tracker_resource_new (const char *identifier)
@@ -269,18 +285,17 @@ tracker_resource_new (const char *identifier)
 
 /**
  * tracker_resource_set_gvalue:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to set
- * @value: an initialised #GValue
+ * @value: an initialised [struct@GObject.Value]
  *
- * State that the only value for the given property is 'value'. Any existing
- * values for 'property' will be removed.
+ * Replace any previously existing value for @property_uri with @value.
  *
  * When serialising to SPARQL, any properties that were set with this function
  * will get a corresponding DELETE statement to remove any existing values in
  * the database.
  *
- * You can pass any kind of GValue for @value, but serialization functions will
+ * You can pass any kind of [struct@GObject.Value] for @value, but serialization functions will
  * normally only be able to serialize URIs/relationships and fundamental value
  * types (string, int, etc.).
  */
@@ -382,52 +397,65 @@ value_set_uri (GValue      *value,
 
 /**
  * tracker_resource_set_boolean:
- * @self: the #TrackerResource
- * @property_uri: a string identifying the property to modify
- * @value: the property object
+ * @self: The `TrackerResource`
+ * @property_uri: A string identifying the property to modify
+ * @value: The property boolean value
  *
- * Sets a single-valued boolean object.
+ * Sets a boolean property. Replaces any previous value.
+ *
+ * This method corresponds to [xsd:boolean](xsd-ontology.html#xsd:boolean).
  */
 SET_PROPERTY_FOR_GTYPE (tracker_resource_set_boolean, gboolean, G_TYPE_BOOLEAN, g_value_set_boolean, validate_boolean)
 
 /**
  * tracker_resource_set_double:
- * @self: the #TrackerResource
- * @property_uri: a string identifying the property to modify
- * @value: the property object
+ * @self: The `TrackerResource`
+ * @property_uri: A string identifying the property to modify
+ * @value: The property object
+ *
+ * Sets a numeric property with double precision. Replaces any previous value.
  *
- * Sets a single-valued double object.
+ * This method corresponds to [xsd:double](xsd-ontology.html#xsd:double).
  */
 SET_PROPERTY_FOR_GTYPE (tracker_resource_set_double, double, G_TYPE_DOUBLE, g_value_set_double, validate_double)
 
 /**
  * tracker_resource_set_int:
- * @self: the #TrackerResource
- * @property_uri: a string identifying the property to modify
- * @value: the property object
+ * @self: The `TrackerResource`
+ * @property_uri: A string identifying the property to modify
+ * @value: The property object
  *
- * Sets a single-valued integer object.
+ * Sets a numeric property with integer precision. Replaces any previous value.
+ *
+ * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer).
  */
 SET_PROPERTY_FOR_GTYPE (tracker_resource_set_int, int, G_TYPE_INT, g_value_set_int, validate_int)
 
 /**
  * tracker_resource_set_int64:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @value: the property object
  *
- * Sets a single-valued integer object.
+ * Sets a numeric property with 64-bit integer precision. Replaces any previous value.
+ *
+ * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer).
  */
 SET_PROPERTY_FOR_GTYPE (tracker_resource_set_int64, gint64, G_TYPE_INT64, g_value_set_int64, validate_int64)
 
 /**
  * tracker_resource_set_relation:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @resource: the property object
  *
- * Sets a single-valued resource object as a #TrackerResource. This
- * function produces similar RDF to tracker_resource_set_uri(),
+ * Sets a resource property as a `TrackerResource`. Replaces any previous value.
+ *
+ * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range)
+ * that points to a non-literal class (i.e. a subclass of
+ * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)).
+ *
+ * This function produces similar RDF to [method@Tracker.Resource.set_uri],
  * although in this function the URI will depend on the identifier
  * set on @resource.
  */
@@ -435,59 +463,76 @@ SET_PROPERTY_FOR_GTYPE (tracker_resource_set_relation, TrackerResource *, TRACKE
 
 /**
  * tracker_resource_set_take_relation:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @resource: (transfer full): the property object
  *
- * Sets a single-valued resource object as a #TrackerResource. This
- * function produces similar RDF to tracker_resource_set_uri(),
+ * Sets a resource property as a `TrackerResource`. Replaces any previous value.
+ * Takes ownership on the given @resource.
+ *
+ * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range)
+ * that points to a non-literal class (i.e. a subclass of
+ * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)).
+ *
+ * This function produces similar RDF to [method@Tracker.Resource.set_uri],
  * although in this function the URI will depend on the identifier
- * set on @resource. This function takes ownership of @resource.
+ * set on @resource.
  */
 SET_PROPERTY_FOR_GTYPE (tracker_resource_set_take_relation, TrackerResource *, TRACKER_TYPE_RESOURCE, g_value_take_object, validate_pointer)
 
 /**
  * tracker_resource_set_string:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @value: the property object
  *
- * Sets a single-valued string object.
+ * Sets a string property. Replaces any previous value.
+ *
+ * This method corresponds to [xsd:string](xsd-ontology.html#xsd:string).
  */
 SET_PROPERTY_FOR_GTYPE (tracker_resource_set_string, const char *, G_TYPE_STRING, g_value_set_string, validate_pointer)
 
 /**
  * tracker_resource_set_uri:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @value: the property object
  *
- * Sets a single-valued resource object as a string URI. This function
- * produces similar RDF to tracker_resource_set_relation(), although
+ * Sets a resource property as an URI string. Replaces any previous value.
+ *
+ * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range)
+ * that points to a non-literal class (i.e. a subclass of
+ * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)).
+ *
+ * This function produces similar RDF to [method@Tracker.Resource.set_relation], although
  * it requires that the URI is previously known.
  */
 SET_PROPERTY_FOR_GTYPE (tracker_resource_set_uri, const char *, TRACKER_TYPE_URI, value_set_uri, validate_pointer)
 
 /**
  * tracker_resource_set_datetime:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @value: the property object
  *
- * Sets a single-valued GDateTime as a #TrackerResource
+ * Sets a date property as a [type@GLib.DateTime]. Replaces any previous value.
+ *
+ * This method corresponds to [xsd:date](xsd-ontology.html#xsd:date) and
+ * [xsd:dateTime](xsd-ontology.html#xsd:dateTime).
+ *
  * Since: 3.2
  */
 SET_PROPERTY_FOR_GTYPE (tracker_resource_set_datetime, GDateTime *, G_TYPE_DATE_TIME, g_value_set_boxed, validate_pointer)
 
 /**
  * tracker_resource_add_gvalue:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to set
- * @value: an initialised #GValue
+ * @value: an initialised [struct@GObject.Value]
  *
- * Add 'value' to the list of values for given property.
+ * Add @value to the list of values for given property.
  *
- * You can pass any kind of GValue for @value, but serialization functions will
+ * You can pass any kind of [struct@GObject.Value] for @value, but serialization functions will
  * normally only be able to serialize URIs/relationships and fundamental value
  * types (string, int, etc.).
  */
@@ -595,52 +640,80 @@ tracker_resource_add_gvalue (TrackerResource *self,
 
 /**
  * tracker_resource_add_boolean:
- * @self: the #TrackerResource
- * @property_uri: a string identifying the property to modify
- * @value: the property object
+ * @self: The `TrackerResource`
+ * @property_uri: A string identifying the property to modify
+ * @value: The property boolean value
+ *
+ * Adds a boolean property. Previous values for the same property are kept.
+ *
+ * This method is meant for RDF properties allowing multiple values, see
+ * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality).
  *
- * Adds a boolean object to a multi-valued property.
+ * This method corresponds to [xsd:boolean](xsd-ontology.html#xsd:boolean).
  */
 ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_boolean, gboolean, G_TYPE_BOOLEAN, g_value_set_boolean, validate_boolean)
 
 /**
  * tracker_resource_add_double:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @value: the property object
  *
- * Adds a double object to a multi-valued property.
+ * Adds a numeric property with double precision. Previous values for the same property are kept.
+ *
+ * This method is meant for RDF properties allowing multiple values, see
+ * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality).
+ *
+ * This method corresponds to [xsd:double](xsd-ontology.html#xsd:double).
  */
 ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_double, double, G_TYPE_DOUBLE, g_value_set_double, validate_double)
 
 /**
  * tracker_resource_add_int:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @value: the property object
  *
- * Adds an integer object to a multi-valued property.
+ * Adds a numeric property with integer precision. Previous values for the same property are kept.
+ *
+ * This method is meant for RDF properties allowing multiple values, see
+ * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality).
+ *
+ * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer).
  */
 ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_int, int, G_TYPE_INT, g_value_set_int, validate_int)
 
 /**
  * tracker_resource_add_int64:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @value: the property object
  *
- * Adds an integer object to a multi-valued property.
+ * Adds a numeric property with 64-bit integer precision. Previous values for the same property are kept.
+ *
+ * This method is meant for RDF properties allowing multiple values, see
+ * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality).
+ *
+ * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer).
  */
 ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_int64, gint64, G_TYPE_INT64, g_value_set_int64, validate_int64)
 
 /**
  * tracker_resource_add_relation:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @resource: the property object
  *
- * Adds a resource object to a multi-valued property. This
- * function produces similar RDF to tracker_resource_add_uri(),
+ * Adds a resource property as a `TrackerResource`. Previous values for the same property are kept.
+ *
+ * This method is meant for RDF properties allowing multiple values, see
+ * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality).
+ *
+ * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range)
+ * that points to a non-literal class (i.e. a subclass of
+ * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)).
+ *
+ * This method produces similar RDF to [method@Tracker.Resource.add_uri],
  * although in this function the URI will depend on the identifier
  * set on @resource.
  */
@@ -648,12 +721,21 @@ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_relation, TrackerResource *, TRACKE
 
 /**
  * tracker_resource_add_take_relation:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @resource: (transfer full): the property object
  *
- * Adds a resource object to a multi-valued property. This
- * function produces similar RDF to tracker_resource_add_uri(),
+ * Adds a resource property as a `TrackerResource`. Previous values for the same property are kept.
+ * Takes ownership on the given @resource.
+ *
+ * This method is meant to RDF properties allowing multiple values, see
+ * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality).
+ *
+ * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range)
+ * that points to a non-literal class (i.e. a subclass of
+ * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)).
+ *
+ * This function produces similar RDF to [method@Tracker.Resource.add_uri],
  * although in this function the URI will depend on the identifier
  * set on @resource. This function takes ownership of @resource.
  */
@@ -662,46 +744,67 @@ ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_take_relation, TrackerResource *, T
 
 /**
  * tracker_resource_add_string:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @value: the property object
  *
- * Adds a string object to a multi-valued property.
+ * Adds a string property. Previous values for the same property are kept.
+ *
+ * This method is meant for RDF properties allowing multiple values, see
+ * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality).
+ *
+ * This method corresponds to [xsd:string](xsd-ontology.html#xsd:string).
  */
 ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_string, const char *, G_TYPE_STRING, g_value_set_string, validate_pointer)
 
 /**
  * tracker_resource_add_uri:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @value: the property object
  *
- * Adds a resource object to a multi-valued property. This function
- * produces similar RDF to tracker_resource_add_relation(), although
+ * Adds a resource property as an URI string. Previous values for the same property are kept.
+ *
+ * This method applies to properties with a [rdfs:range](rdf-ontology.html#rdfs:range)
+ * that points to a non-literal class (i.e. a subclass of
+ * [rdfs:Resource](rdf-ontology.html#rdfs:Resource)).
+ *
+ * This method is meant for RDF properties allowing multiple values, see
+ * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality).
+ *
+ * This function produces similar RDF to [method@Tracker.Resource.add_relation], although
  * it requires that the URI is previously known.
  */
 ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_uri, const char *, TRACKER_TYPE_URI, value_set_uri, validate_pointer)
 
 /**
  * tracker_resource_add_datetime:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to modify
  * @value: the property object
  *
- * Adds GDateTime object to the multi-valued property.
+ * Adds a date property as a [type@GLib.DateTime]. Previous values for the
+ * same property are kept.
+ *
+ * This method is meant for RDF properties allowing multiple values, see
+ * [nrl:maxCardinality](nrl-ontology.html#nrl:maxCardinality).
+ *
+ * This method corresponds to [xsd:date](xsd-ontology.html#xsd:date) and
+ * [xsd:dateTime](xsd-ontology.html#xsd:dateTime).
+ *
  * Since: 3.2
  */
 ADD_PROPERTY_FOR_GTYPE (tracker_resource_add_datetime, GDateTime *, G_TYPE_DATE_TIME, g_value_set_boxed, validate_pointer)
 
 /**
  * tracker_resource_get_values:
- * @self: the #TrackerResource
+ * @self: the `TrackerResource`
  * @property_uri: a string identifying the property to look up
  *
  * Returns the list of all known values of the given property.
  *
- * Returns: (transfer container) (element-type GValue) (nullable): a #GList of
- * #GValue instances. The list should be freed with g_list_free()
+ * Returns: (transfer container) (element-type GValue) (nullable): a [struct@GLib.List] of
+ *   [struct@GObject.Value] instances. The list should be freed with [func@GLib.List.free]
  */
 GList *tracker_resource_get_values (TrackerResource *self,
                                     const char      *property_uri)
@@ -771,7 +874,7 @@ GList *tracker_resource_get_values (TrackerResource *self,
 
 /**
  * tracker_resource_get_first_boolean:
- * @self: A #TrackerResource
+ * @self: A `TrackerResource`
  * @property_uri: a string identifying the property to look up
  *
  * Returns the first boolean object previously assigned to a property.
@@ -782,7 +885,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_boolean, gboolean, G_TYPE_BOO
 
 /**
  * tracker_resource_get_first_double:
- * @self: A #TrackerResource
+ * @self: A `TrackerResource`
  * @property_uri: a string identifying the property to look up
  *
  * Returns the first double object previously assigned to a property.
@@ -793,7 +896,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_double, double, G_TYPE_DOUBLE
 
 /**
  * tracker_resource_get_first_int:
- * @self: A #TrackerResource
+ * @self: A `TrackerResource`
  * @property_uri: a string identifying the property to look up
  *
  * Returns the first integer object previously assigned to a property.
@@ -804,7 +907,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_int, int, G_TYPE_INT, g_value
 
 /**
  * tracker_resource_get_first_int64:
- * @self: A #TrackerResource
+ * @self: A `TrackerResource`
  * @property_uri: a string identifying the property to look up
  *
  * Returns the first integer object previously assigned to a property.
@@ -815,7 +918,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_int64, gint64, G_TYPE_INT64,
 
 /**
  * tracker_resource_get_first_relation:
- * @self: A #TrackerResource
+ * @self: A `TrackerResource`
  * @property_uri: a string identifying the property to look up
  *
  * Returns the first resource object previously assigned to a property.
@@ -826,7 +929,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_relation, TrackerResource *,
 
 /**
  * tracker_resource_get_first_string:
- * @self: A #TrackerResource
+ * @self: A `TrackerResource`
  * @property_uri: a string identifying the property to look up
  *
  * Returns the first string object previously assigned to a property.
@@ -837,7 +940,7 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_string, const char *, G_TYPE_
 
 /**
  * tracker_resource_get_first_uri:
- * @self: A #TrackerResource
+ * @self: A `TrackerResource`
  * @property_uri: a string identifying the property to look up
  *
  * Returns the first resource object previously assigned to a property.
@@ -848,10 +951,10 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_uri, const char *, TRACKER_TY
 
 /**
  * tracker_resource_get_first_datetime:
- * @self: A #TrackerResource
+ * @self: A `TrackerResource`
  * @property_uri: a string identifying the property to look up
  *
- * Returns the first resource object previously assigned to a property.
+ * Returns the first [type@GLib.DateTime] previously assigned to a property.
  *
  * Returns: (transfer none) (nullable): the first GDateTime object
  * Since: 3.2
@@ -860,12 +963,12 @@ GET_PROPERTY_FOR_GTYPE (tracker_resource_get_first_datetime, GDateTime *, G_TYPE
 
 /**
  * tracker_resource_get_identifier:
- * @self: A #TrackerResource
+ * @self: A `TrackerResource`
  *
  * Returns the identifier of a resource.
  *
- * If the identifier was set to NULL, the identifier returned will be a unique
- * SPARQL blank node identifier, such as "_:123".
+ * If the identifier was set to NULL, the identifier returned will be a locally
+ * unique SPARQL blank node identifier, such as `_:123`.
  *
  * Returns: (nullable): a string owned by the resource
  */
@@ -886,16 +989,16 @@ tracker_resource_get_identifier (TrackerResource *self)
 
 /**
  * tracker_resource_set_identifier:
- * @self: a #TrackerResource
+ * @self: A `TrackerResource`
  * @identifier: (nullable): a string identifying the resource
  *
- * Changes the identifier of a #TrackerResource. The identifier should be a
+ * Changes the identifier of a `TrackerResource`. The identifier should be a
  * URI or compact URI, but this is not necessarily enforced. Invalid
  * identifiers may cause errors when serializing the resource or trying to
  * insert the results in a database.
  *
  * If the identifier is set to %NULL, a SPARQL blank node identifier such as
- * "_:123" is assigned to the resource.
+ * `_:123` is assigned to the resource.
  */
 void
 tracker_resource_set_identifier (TrackerResource *self,
@@ -913,10 +1016,10 @@ tracker_resource_set_identifier (TrackerResource *self,
 
 /**
  * tracker_resource_identifier_compare_func:
- * @resource: a #TrackerResource
+ * @resource: a `TrackerResource`
  * @identifier: a string identifying the resource
  *
- * A helper function that compares a #TrackerResource by its identifier
+ * A helper function that compares a `TrackerResource` by its identifier
  * string.
  *
  * Returns: an integer less than, equal to, or greater than zero, if the
@@ -934,8 +1037,8 @@ tracker_resource_identifier_compare_func (TrackerResource *resource,
 
 /**
  * tracker_resource_compare:
- * @a: A #TrackerResource
- * @b: A second #TrackerResource to compare
+ * @a: A `TrackerResource`
+ * @b: A second `TrackerResource` to compare
  *
  * Compare the identifiers of two TrackerResource instances. The resources
  * are considered identical if they have the same identifier.
@@ -959,14 +1062,11 @@ tracker_resource_compare (TrackerResource *a,
 
 /**
  * tracker_resource_get_properties:
- * @resource: a #TrackerResource
+ * @resource: a `TrackerResource`
  *
  * Gets the list of properties defined in @resource
  *
  * Returns: (transfer container) (element-type utf8): The list of properties.
- *          The list should be freed with g_list_free().
- *
- * Since: 3.0
  **/
 GList *
 tracker_resource_get_properties (TrackerResource *resource)
@@ -1191,7 +1291,7 @@ generate_turtle_property (const char              *property,
 
 /**
  * tracker_resource_print_turtle:
- * @self: a #TrackerResource
+ * @self: a `TrackerResource`
  * @namespaces: (allow-none): a set of prefixed URLs, or %NULL to use the
  *     Nepomuk set
  *
@@ -1201,12 +1301,12 @@ generate_turtle_property (const char              *property,
  * <https://www.w3.org/TR/2014/REC-turtle-20140225/>
  *
  * The @namespaces object is used to expand any compact URI values. In most
- * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager()
+ * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager]
  * from the connection that is the intended recipient of this data.
  *
  * Returns: a newly-allocated string
  *
- * Deprecated: 3.4: Use tracker_resource_print_rdf() instead.
+ * Deprecated: 3.4: Use [method@Tracker.Resource.print_rdf] instead.
  */
 char *
 tracker_resource_print_turtle (TrackerResource         *self,
@@ -1423,7 +1523,7 @@ generate_sparql_insert_pattern (TrackerResource    *resource,
 
 /**
  * tracker_resource_print_sparql_update:
- * @self: a #TrackerResource
+ * @self: a `TrackerResource`
  * @namespaces: (allow-none): a set of prefixed URLs, or %NULL to use the
  *     Nepomuk set
  * @graph_id: (allow-none): the URN of the graph the data should be added to,
@@ -1433,7 +1533,7 @@ generate_sparql_insert_pattern (TrackerResource    *resource,
  * stored in @resource.
  *
  * The @namespaces object is used to expand any compact URI values. In most
- * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager()
+ * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager]
  * from the connection that is the intended recipient of this data.
  *
  * Returns: a newly-allocated string containing a SPARQL update command.
@@ -1502,7 +1602,7 @@ tracker_resource_print_sparql_update (TrackerResource         *resource,
 
 /**
  * tracker_resource_print_jsonld:
- * @self: a #TrackerResource
+ * @self: a `TrackerResource`
  * @namespaces: (nullable): a set of prefixed URLs, or %NULL to use the
  *     Nepomuk set
  *
@@ -1512,12 +1612,12 @@ tracker_resource_print_sparql_update (TrackerResource         *resource,
  * serialization format.
  *
  * The @namespaces object is used to expand any compact URI values. In most
- * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager()
+ * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager]
  * from the connection that is the intended recipient of this data.
  *
  * Returns: a newly-allocated string containing JSON-LD data.
  *
- * Deprecated: 3.5: Use tracker_resource_print_rdf()
+ * Deprecated: 3.5: Use [method@Tracker.Resource.print_rdf] instead.
  */
 char *
 tracker_resource_print_jsonld (TrackerResource         *self,
@@ -1553,7 +1653,7 @@ convert_format (TrackerRdfFormat format)
 
 /**
  * tracker_resource_print_rdf:
- * @self: a #TrackerResource
+ * @self: a `TrackerResource`
  * @namespaces: a set of prefixed URLs
  * @format: RDF format of the printed string
  * @graph: (nullable): target graph of the resource RDF, or %NULL for the
@@ -1562,7 +1662,7 @@ convert_format (TrackerRdfFormat format)
  * Serialize all the information in @resource into the selected RDF format.
  *
  * The @namespaces object is used to expand any compact URI values. In most
- * cases you should pass the one returned by tracker_sparql_connection_get_namespace_manager()
+ * cases you should pass the one returned by [method@Tracker.SparqlConnection.get_namespace_manager]
  * from the connection that is the intended recipient of this data.
  *
  * Returns: a newly-allocated string containing RDF data in the requested format.
@@ -1675,11 +1775,11 @@ tracker_serialize_single_value (TrackerResource         *resource,
 
 /**
  * tracker_resource_serialize:
- * @resource: A #TrackerResource
+ * @resource: A `TrackerResource`
  *
- * Serializes a #TrackerResource to a #GVariant in a lossless way.
+ * Serializes a `TrackerResource` to a [type@GLib.Variant] in a lossless way.
  * All child resources are subsequently serialized. It is implied
- * that both ends use a common #TrackerNamespaceManager.
+ * that both ends use a common [class@Tracker.NamespaceManager].
  *
  * Returns: (transfer floating) (nullable): A variant describing the resource,
  *          the reference is floating.
@@ -1751,11 +1851,11 @@ tracker_resource_serialize (TrackerResource *resource)
 
 /**
  * tracker_resource_deserialize:
- * @variant: a #GVariant
+ * @variant: a [type@GLib.Variant]
  *
- * Deserializes a #TrackerResource previously serialized with
- * tracker_resource_serialize(). It is implied that both ends
- * use a common #TrackerNamespaceManager.
+ * Deserializes a `TrackerResource` previously serialized with
+ * [method@Tracker.Resource.serialize]. It is implied that both ends
+ * use a common [class@Tracker.NamespaceManager].
  *
  * Returns: (transfer full) (nullable): A TrackerResource, or %NULL if
  *          deserialization fails.
@@ -1872,7 +1972,7 @@ tracker_resource_deserialize (GVariant *variant)
 
 /**
  * tracker_resource_get_property_overwrite:
- * @resource: a #TrackerResource
+ * @resource: a `TrackerResource`
  * @property_uri: a string identifying the property to query
  *
  * Returns whether the prior values for this property would be deleted
diff --git a/src/libtracker-sparql/tracker-sparql-enum-types.h.template b/src/libtracker-sparql/tracker-sparql-enum-types.h.template
index c0afe7b37..a7aced5a8 100644
--- a/src/libtracker-sparql/tracker-sparql-enum-types.h.template
+++ b/src/libtracker-sparql/tracker-sparql-enum-types.h.template
@@ -1,10 +1,11 @@
 /*** BEGIN file-header ***/
 
-#ifndef __TRACKER_NOTIFY_ENUM_TYPES_H__
-#define __TRACKER_NOTIFY_ENUM_TYPES_H__
+#ifndef __TRACKER_SPARQL_ENUM_TYPES_H__
+#define __TRACKER_SPARQL_ENUM_TYPES_H__
 
 #include <glib-object.h>
 #include <libtracker-sparql/tracker-version.h>
+#include <libtracker-sparql/tracker-error.h>
 
 G_BEGIN_DECLS
 /*** END file-header ***/
@@ -16,12 +17,12 @@ G_BEGIN_DECLS
 
 /*** BEGIN value-header ***/
 TRACKER_AVAILABLE_IN_ALL
-GType @enum_name@_get_type (void) G_GNUC_CONST;
+GType @enum_name@_get_type (void);
 #define TRACKER_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
 /*** END value-header ***/
 
 /*** BEGIN file-tail ***/
 G_END_DECLS
 
-#endif /* __TRACKER_ENUMS_TYPES_H__ */
+#endif /* __TRACKER_SPARQL_ENUMS_TYPES_H__ */
 /*** END file-tail ***/
diff --git a/src/libtracker-sparql/tracker-statement.c b/src/libtracker-sparql/tracker-statement.c
index 7a6c26aaf..8497af779 100644
--- a/src/libtracker-sparql/tracker-statement.c
+++ b/src/libtracker-sparql/tracker-statement.c
@@ -17,30 +17,38 @@
  * Boston, MA  02110-1301, USA.
  */
 /**
- * SECTION: tracker-sparql-statement
- * @short_description: Prepared statements
- * @title: TrackerSparqlStatement
- * @stability: Stable
- * @include: tracker-sparql.h
- *
- * The <structname>TrackerSparqlStatement</structname> object represents
- * a SPARQL query. This query may contain parameterized variables
- * (expressed as ~var in the syntax), which may be mapped to arbitrary
- * values prior to execution. This statement may be reused for future
+ * TrackerSparqlStatement:
+ *
+ * `TrackerSparqlStatement` represents a prepared statement for a SPARQL query.
+ *
+ * The SPARQL query will be internally compiled into the format that is most
+ * optimal to execute the query many times. For connections created
+ * through [ctor@Tracker.SparqlConnection.new] that will be a
+ * SQLite compiled statement.
+ *
+ * The SPARQL query may contain parameterized variables expressed via the
+ * `~` prefix in the SPARQL syntax (e.g. `~var`), these may happen anywhere
+ * in the SPARQL where a literal or variable would typically happen. These
+ * parameterized variables may be mapped to arbitrary values prior to
+ * execution. The `TrackerSparqlStatement` may be reused for future
  * queries with different values.
  *
- * The argument bindings may be changed through tracker_sparql_statement_bind_int(),
- * tracker_sparql_statement_bind_boolean(), tracker_sparql_statement_bind_double()
- * and tracker_sparql_statement_bind_string(). Those functions receive
- * a @name argument corresponding for the variable name in the SPARQL query
- * (eg. "var" for ~var) and a @value to map the variable to.
+ * The argument bindings may be changed through the [method@Tracker.SparqlStatement.bind_int],
+ * [method@Tracker.SparqlStatement.bind_int], etc... family of functions. Those functions
+ * receive a @name argument corresponding for the variable name in the SPARQL query
+ * (eg. `"var"` for `~var`) and a value to map the variable to.
  *
  * Once all arguments have a value, the query may be executed through
- * tracker_sparql_statement_execute() or tracker_sparql_statement_execute_async().
+ * [method@Tracker.SparqlStatement.execute_async] or [method@Tracker.SparqlStatement.execute].
  *
- * It is possible to use a given #TrackerSparqlStatement in other threads than
- * the one it was created from. It must be however used from just one thread
- * at any given time.
+ * It is possible to use any `TrackerSparqlStatement` from other threads than
+ * the one it was created from. However, binding values and executing the
+ * statement must only happen from one thread at a time. It is possible to reuse
+ * the `TrackerSparqlStatement` right after [method@Tracker.SparqlStatement.execute_async]
+ * was called, there is no need to wait for [method@Tracker.SparqlStatement.execute_finish].
+ *
+ * In some circumstances, it is possible that the query needs to be recompiled
+ * from the SPARQL source. This will happen transparently.
  */
 #include "config.h"
 
@@ -135,7 +143,7 @@ tracker_sparql_statement_class_init (TrackerSparqlStatementClass *klass)
 	/**
 	 * TrackerSparqlStatement:connection:
 	 *
-	 * The #TrackerSparqlConnection used to perform the query.
+	 * The [class@Tracker.SparqlConnection] the statement was created for.
 	 */
 	props[PROP_CONNECTION] =
 		g_param_spec_object ("connection",
@@ -166,9 +174,9 @@ tracker_sparql_statement_class_init (TrackerSparqlStatementClass *klass)
 
 /**
  * tracker_sparql_statement_get_connection:
- * @stmt: a #TrackerSparqlStatement
+ * @stmt: a `TrackerSparqlStatement`
  *
- * Returns the #TrackerSparqlConnection that this statement was created from.
+ * Returns the [class@Tracker.SparqlConnection] that this statement was created for.
  *
  * Returns: (transfer none): The SPARQL connection of this statement.
  **/
@@ -184,7 +192,7 @@ tracker_sparql_statement_get_connection (TrackerSparqlStatement *stmt)
 
 /**
  * tracker_sparql_statement_get_sparql:
- * @stmt: a #TrackerSparqlStatement
+ * @stmt: a `TrackerSparqlStatement`
  *
  * Returns the SPARQL string that this prepared statement holds.
  *
@@ -202,11 +210,11 @@ tracker_sparql_statement_get_sparql (TrackerSparqlStatement *stmt)
 
 /**
  * tracker_sparql_statement_bind_boolean:
- * @stmt: a #TrackerSparqlStatement
+ * @stmt: a `TrackerSparqlStatement`
  * @name: variable name
  * @value: value
  *
- * Binds the boolean @value to variable @name.
+ * Binds the boolean @value to the parameterized variable given by @name.
  */
 void
 tracker_sparql_statement_bind_boolean (TrackerSparqlStatement *stmt,
@@ -223,11 +231,11 @@ tracker_sparql_statement_bind_boolean (TrackerSparqlStatement *stmt,
 
 /**
  * tracker_sparql_statement_bind_int:
- * @stmt: a #TrackerSparqlStatement
+ * @stmt: a `TrackerSparqlStatement`
  * @name: variable name
  * @value: value
  *
- * Binds the integer @value to variable @name.
+ * Binds the integer @value to the parameterized variable given by @name.
  */
 void
 tracker_sparql_statement_bind_int (TrackerSparqlStatement *stmt,
@@ -244,11 +252,11 @@ tracker_sparql_statement_bind_int (TrackerSparqlStatement *stmt,
 
 /**
  * tracker_sparql_statement_bind_double:
- * @stmt: a #TrackerSparqlStatement
+ * @stmt: a `TrackerSparqlStatement`
  * @name: variable name
  * @value: value
  *
- * Binds the double @value to variable @name.
+ * Binds the double @value to the parameterized variable given by @name.
  */
 void
 tracker_sparql_statement_bind_double (TrackerSparqlStatement *stmt,
@@ -265,11 +273,11 @@ tracker_sparql_statement_bind_double (TrackerSparqlStatement *stmt,
 
 /**
  * tracker_sparql_statement_bind_string:
- * @stmt: a #TrackerSparqlStatement
+ * @stmt: a `TrackerSparqlStatement`
  * @name: variable name
  * @value: value
  *
- * Binds the string @value to variable @name.
+ * Binds the string @value to the parameterized variable given by @name.
  */
 void
 tracker_sparql_statement_bind_string (TrackerSparqlStatement *stmt,
@@ -287,11 +295,12 @@ tracker_sparql_statement_bind_string (TrackerSparqlStatement *stmt,
 
 /**
  * tracker_sparql_statement_bind_datetime:
- * @stmt: a #TrackerSparqlStatement
+ * @stmt: a `TrackerSparqlStatement`
  * @name: variable name
  * @value: value
  *
- * Binds the GDateTime @value to variable @name.
+ * Binds the [type@GLib.DateTime] @value to the parameterized variable given by @name.
+ *
  * Since: 3.2
  */
 
@@ -311,18 +320,24 @@ tracker_sparql_statement_bind_datetime (TrackerSparqlStatement *stmt,
 
 /**
  * tracker_sparql_statement_execute:
- * @stmt: a #TrackerSparqlStatement
- * @cancellable: a #GCancellable used to cancel the operation
- * @error: #GError for error reporting.
+ * @stmt: a `TrackerSparqlStatement`
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
  *
- * Executes the SPARQL query with the currently bound values.
+ * Executes the `SELECT` or `ASK` SPARQL query with the currently bound values.
  *
- * This function should only be called on #TrackerSparqlStatement objects
- * obtained through tracker_sparql_connection_query_statement() or
+ * This function also works for `DESCRIBE` and `CONSTRUCT` queries that
+ * retrieve data from the triple store. These query forms that return
+ * RDF data are however more useful together with [method@Tracker.SparqlStatement.serialize_async].
+ *
+ * This function should only be called on `TrackerSparqlStatement` objects
+ * obtained through [method@Tracker.SparqlConnection.query_statement] or
  * SELECT/CONSTRUCT/DESCRIBE statements loaded through
- * tracker_sparql_connection_load_statement_from_gresource().
+ * [method@Tracker.SparqlConnection.load_statement_from_gresource].
+ * An error will be raised if this method is called on a `INSERT` or `DELETE`
+ * SPARQL query.
  *
- * Returns: (transfer full): A #TrackerSparqlCursor
+ * Returns: (transfer full): A `TrackerSparqlCursor` with the query results.
  */
 TrackerSparqlCursor *
 tracker_sparql_statement_execute (TrackerSparqlStatement  *stmt,
@@ -348,18 +363,24 @@ tracker_sparql_statement_execute (TrackerSparqlStatement  *stmt,
 
 /**
  * tracker_sparql_statement_execute_async:
- * @stmt: a #TrackerSparqlStatement
- * @cancellable: a #GCancellable used to cancel the operation
- * @callback: user-defined #GAsyncReadyCallback to be called when
- *            asynchronous operation is finished.
+ * @stmt: a `TrackerSparqlStatement`
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
  * @user_data: user-defined data to be passed to @callback
  *
- * Asynchronously executes the SPARQL query with the currently bound values.
+ * Executes asynchronously the `SELECT` or `ASK` SPARQL query with the currently bound values.
+ *
+ * This function also works for `DESCRIBE` and `CONSTRUCT` queries that
+ * retrieve data from the triple store. These query forms that return
+ * RDF data are however more useful together with [method@Tracker.SparqlStatement.serialize_async].
  *
- * This function should only be called on #TrackerSparqlStatement objects
- * obtained through tracker_sparql_connection_query_statement() or
+ * This function should only be called on `TrackerSparqlStatement` objects
+ * obtained through [method@Tracker.SparqlConnection.query_statement] or
  * SELECT/CONSTRUCT/DESCRIBE statements loaded through
- * tracker_sparql_connection_load_statement_from_gresource().
+ * [method@Tracker.SparqlConnection.load_statement_from_gresource].
+ * An error will be raised if this method is called on a `INSERT` or `DELETE`
+ * SPARQL query.
  */
 void
 tracker_sparql_statement_execute_async (TrackerSparqlStatement *stmt,
@@ -378,14 +399,14 @@ tracker_sparql_statement_execute_async (TrackerSparqlStatement *stmt,
 
 /**
  * tracker_sparql_statement_execute_finish:
- * @stmt: a #TrackerSparqlStatement
- * @res: The #GAsyncResult from the callback used to return the #TrackerSparqlCursor
- * @error: The error which occurred or %NULL
+ * @stmt: a `TrackerSparqlStatement`
+ * @res: a [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
  * Finishes the asynchronous operation started through
- * tracker_sparql_statement_execute_async().
+ * [method@Tracker.SparqlStatement.execute_async].
  *
- * Returns: (transfer full): A #TrackerSparqlCursor
+ * Returns: (transfer full): A `TrackerSparqlCursor` with the query results.
  */
 TrackerSparqlCursor *
 tracker_sparql_statement_execute_finish (TrackerSparqlStatement  *stmt,
@@ -411,15 +432,18 @@ tracker_sparql_statement_execute_finish (TrackerSparqlStatement  *stmt,
 
 /**
  * tracker_sparql_statement_update:
- * @stmt: a #TrackerSparqlStatement
- * @cancellable: a #GCancellable used to cancel the operation
- * @error: #GError for error reporting.
+ * @stmt: a `TrackerSparqlStatement`
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @error: Error location
  *
- * Executes the SPARQL update with the currently bound values.
+ * Executes the `INSERT`/`DELETE` SPARQL query series with the currently bound values.
  *
- * This function should only be called on #TrackerSparqlStatement objects
- * obtained through tracker_sparql_connection_update_statement() or
- * update statements loaded through tracker_sparql_connection_load_statement_from_gresource().
+ * This function should only be called on `TrackerSparqlStatement` objects
+ * obtained through [method@Tracker.SparqlConnection.update_statement] or
+ * `INSERT`/`DELETE` statements loaded through
+ * [method@Tracker.SparqlConnection.load_statement_from_gresource].
+ * An error will be raised if this method is called on
+ * `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL queries.
  *
  * Returns: %TRUE if the update finished with no errors, %FALSE otherwise
  *
@@ -441,17 +465,20 @@ tracker_sparql_statement_update (TrackerSparqlStatement  *stmt,
 
 /**
  * tracker_sparql_statement_update_async:
- * @stmt: a #TrackerSparqlStatement
- * @cancellable: a #GCancellable used to cancel the operation
- * @callback: user-defined #GAsyncReadyCallback to be called when
- *            asynchronous operation is finished.
+ * @stmt: a `TrackerSparqlStatement`
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
  * @user_data: user-defined data to be passed to @callback
  *
- * Asynchronously executes the SPARQL update query with the currently bound values.
+ * Executes asynchronously the `INSERT`/`DELETE` SPARQL query series with the currently bound values.
  *
- * This function should only be called on #TrackerSparqlStatement objects
- * obtained through tracker_sparql_connection_update_statement() or
- * update statements loaded through tracker_sparql_connection_load_statement_from_gresource().
+ * This function should only be called on `TrackerSparqlStatement` objects
+ * obtained through [method@Tracker.SparqlConnection.update_statement] or
+ * `INSERT`/`DELETE` statements loaded through
+ * [method@Tracker.SparqlConnection.load_statement_from_gresource].
+ * An error will be raised if this method is called on
+ * `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL queries.
  *
  * Since: 3.5
  */
@@ -472,12 +499,12 @@ tracker_sparql_statement_update_async (TrackerSparqlStatement *stmt,
 
 /**
  * tracker_sparql_statement_update_finish:
- * @stmt: a #TrackerSparqlStatement
- * @result: The #GAsyncResult from the callback used to return the #TrackerSparqlCursor
- * @error: The error which occurred or %NULL
+ * @stmt: a `TrackerSparqlStatement`
+ * @result: a [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
  * Finishes the asynchronous update started through
- * tracker_sparql_statement_update_async().
+ * [method@Tracker.SparqlStatement.update_async].
  *
  * Returns: %TRUE if the update finished with no errors, %FALSE otherwise
  *
@@ -500,11 +527,9 @@ tracker_sparql_statement_update_finish (TrackerSparqlStatement  *stmt,
 
 /**
  * tracker_sparql_statement_clear_bindings:
- * @stmt: a #TrackerSparqlStatement
- *
- * Clears all boolean/string/integer/double bindings.
+ * @stmt: a `TrackerSparqlStatement`
  *
- * Since: 3.0
+ * Clears all bindings.
  */
 void
 tracker_sparql_statement_clear_bindings (TrackerSparqlStatement *stmt)
@@ -516,17 +541,18 @@ tracker_sparql_statement_clear_bindings (TrackerSparqlStatement *stmt)
 
 /**
  * tracker_sparql_statement_serialize_async:
- * @stmt: a #TrackerSparqlStatement
+ * @stmt: a `TrackerSparqlStatement`
  * @flags: serialization flags
  * @format: RDF format of the serialized data
- * @cancellable: (nullable): a #GCancellable used to cancel the operation
- * @callback: user-defined #GAsyncReadyCallback to be called when
- *            asynchronous operation is finished.
+ * @cancellable: (nullable): Optional [type@Gio.Cancellable]
+ * @callback: user-defined [type@Gio.AsyncReadyCallback] to be called when
+ *            the asynchronous operation is finished.
  * @user_data: user-defined data to be passed to @callback
  *
- * Serializes data into the specified RDF format. The query @stmt was
- * created from must be either a `DESCRIBE` or `CONSTRUCT` query, an
- * error will be raised otherwise.
+ * Serializes a `DESCRIBE` or `CONSTRUCT` query into the given RDF @format.
+ *
+ * The query @stmt was created from must be either a `DESCRIBE` or `CONSTRUCT`
+ * query, an error will be raised otherwise.
  *
  * This is an asynchronous operation, @callback will be invoked when the
  * data is available for reading.
@@ -535,7 +561,7 @@ tracker_sparql_statement_clear_bindings (TrackerSparqlStatement *stmt)
  * an error will be raised.
  *
  * The @flags argument is reserved for future expansions, currently
- * %TRACKER_SERIALIZE_FLAGS_NONE must be passed.
+ * #TRACKER_SERIALIZE_FLAGS_NONE must be passed.
  *
  * Since: 3.3
  **/
@@ -562,14 +588,14 @@ tracker_sparql_statement_serialize_async (TrackerSparqlStatement *stmt,
 
 /**
  * tracker_sparql_statement_serialize_finish:
- * @stmt: a #TrackerSparqlStatement
- * @result: the #GAsyncResult
- * @error: location for returned errors, or %NULL
+ * @stmt: a `TrackerSparqlStatement`
+ * @result: a [type@Gio.AsyncResult] with the result of the operation
+ * @error: Error location
  *
- * Finishes a tracker_sparql_statement_serialize_async() operation.
- * In case of error, %NULL will be returned and @error will be set.
+ * Finishes the asynchronous operation started through
+ * [method@Tracker.SparqlStatement.serialize_async].
  *
- * Returns: (transfer full): a #GInputStream to read RDF content.
+ * Returns: (transfer full): a [class@Gio.InputStream] to read RDF content.
  *
  * Since: 3.3
  **/
diff --git a/src/libtracker-sparql/tracker-statement.h b/src/libtracker-sparql/tracker-statement.h
index fc551e89a..3de04f797 100644
--- a/src/libtracker-sparql/tracker-statement.h
+++ b/src/libtracker-sparql/tracker-statement.h
@@ -28,12 +28,6 @@
 
 G_BEGIN_DECLS
 
-/**
- * TrackerSparqlStatement:
- *
- * The <structname>TrackerSparqlStatement</structname> object represents
- * a prepared query statement.
- */
 #define TRACKER_TYPE_SPARQL_STATEMENT tracker_sparql_statement_get_type ()
 #define TRACKER_SPARQL_TYPE_STATEMENT TRACKER_TYPE_SPARQL_STATEMENT
 TRACKER_AVAILABLE_IN_ALL
diff --git a/src/libtracker-sparql/tracker-uri.c b/src/libtracker-sparql/tracker-uri.c
index 9238c50cb..135f5ddf7 100644
--- a/src/libtracker-sparql/tracker-uri.c
+++ b/src/libtracker-sparql/tracker-uri.c
@@ -19,16 +19,6 @@
  * Boston, MA  02110-1301, USA.
  */
 
-/**
- * SECTION: tracker-uri
- * @short_description: URI utility functions
- * @title: URI Utilities
- * @stability: Stable
- * @include: libtracker-sparql/tracker-sparql.h
- *
- * Tracker defines some utility functions to deal with URI strings.
- */
-
 #include "config.h"
 
 #include <string.h>
@@ -163,14 +153,13 @@ find_conversion (const char  *format,
  *     <link linkend="string-precision">string precision pitfalls</link> documented in g_strdup_printf()
  * @args: the list of parameters to insert into the format string
  *
+ * Formats and escapes a string for use as a URI. This function takes a `va_list`.
+ *
  * Similar to the standard C vsprintf() function but safer, since it
  * calculates the maximum space required and allocates memory to hold
  * the result.
  *
- * The result is escaped using g_uri_escape_string().
- *
- * Returns: (transfer full): a newly-allocated string holding the result. The returned string
- * should be freed with g_free() when no longer needed.
+ * Returns: (transfer full): a newly-allocated string holding the result.
  */
 gchar *
 tracker_sparql_escape_uri_vprintf (const gchar *format,
@@ -269,7 +258,7 @@ cleanup:
  *     <link linkend="string-precision">string precision pitfalls</link> documented in g_strdup_printf()
  * @...: the parameters to insert into the format string
  *
- * Calls tracker_sparql_escape_uri_vprintf() with the @... supplied.
+ * Formats and escapes a string for use as a URI. This function takes variadic arguments.
  *
  * Returns: (transfer full): a newly-allocated string holding the result.The returned string
  * should be freed with g_free() when no longer needed.
@@ -291,10 +280,9 @@ tracker_sparql_escape_uri_printf (const gchar *format, ...)
  * tracker_sparql_escape_uri:
  * @uri: a string to be escaped, following the tracker sparql rules
  *
- * Calls tracker_sparql_escape_uri_printf().
+ * Escapes a string for use as a URI.
  *
- * Returns: (transfer full): a newly-allocated string holding the result. The returned string
- * should be freed with g_free() when no longer needed.
+ * Returns: (transfer full): a newly-allocated string holding the result.
  */
 gchar *
 tracker_sparql_escape_uri (const gchar *uri)
diff --git a/src/libtracker-sparql/tracker-utils.c b/src/libtracker-sparql/tracker-utils.c
index 063559793..1f4639a23 100644
--- a/src/libtracker-sparql/tracker-utils.c
+++ b/src/libtracker-sparql/tracker-utils.c
@@ -16,15 +16,6 @@
  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  * Boston, MA  02110-1301, USA.
  */
-/**
- * SECTION: tracker-misc
- * @short_description: miscellaneous functionality
- * @title: Utility Functions
- * @stability: Stable
- * @include: tracker-sparql.h
- *
- * Collection of Tracker utility functions.
- */
 
 #include "config.h"
 
@@ -37,9 +28,10 @@
  * @literal: a string to escape
  *
  * Escapes @literal so it is suitable for insertion in
- * SPARQL queries as string literals. Manual construction
- * of query strings based user input is best avoided at
- * all cost, use of #TrackerSparqlStatement is recommended
+ * SPARQL queries as string literals.
+ *
+ * Manual construction of query strings based user input is best
+ * avoided at all cost, use of #TrackerSparqlStatement is recommended
  * instead.
  *
  * Returns: (transfer full): the escaped string
diff --git a/src/libtracker-sparql/tracker-version.c b/src/libtracker-sparql/tracker-version.c
index 7fd829482..ce5f9bb0d 100644
--- a/src/libtracker-sparql/tracker-version.c
+++ b/src/libtracker-sparql/tracker-version.c
@@ -16,17 +16,6 @@
  * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  * Boston, MA  02110-1301, USA.
  */
-/**
- * SECTION: tracker-version
- * @short_description: variables and functions to check Tracker version
- * @title: Version Information
- * @stability: Stable
- * @include: tracker-sparql.h
- *
- * Tracker provides version information, primarily useful in configure checks
- * for builds that have a configure script. Applications will not typically use
- * the features described here.
- */
 
 #include "config.h"
 
@@ -47,9 +36,10 @@ const guint tracker_binary_age = TRACKER_BINARY_AGE;
  * @required_minor: the required minor version.
  * @required_micro: the required micro version.
  *
- * Checks that the Tracker library in use is compatible with the
- * given version. Generally you would pass in the constants
- * #TRACKER_MAJOR_VERSION, #TRACKER_MINOR_VERSION, #TRACKER_MICRO_VERSION
+ * Checks that the Tracker library in use is compatible with the given version.
+ *
+ * Generally you would pass in the constants
+ * [const@Tracker.MAJOR_VERSION], [const@Tracker.MINOR_VERSION], [const@Tracker.MICRO_VERSION]
  * as the three arguments to this function; that produces
  * a check that the library in use is compatible with
  * the version of Tracker the application or module was compiled
@@ -57,15 +47,13 @@ const guint tracker_binary_age = TRACKER_BINARY_AGE;
  *
  * Compatibility is defined by two things: first the version
  * of the running library is newer than the version
- * @required_major.required_minor.@required_micro. Second
+ * @required_major.@required_minor.@required_micro. Second
  * the running library must be binary compatible with the
- * version @required_major.required_minor.@required_micro
+ * version @required_major.@required_minor.@required_micro
  * (same major version.)
  *
  * Return value: %NULL if the Tracker library is compatible with the
  *   given version, or a string describing the version mismatch.
- *   The returned string is owned by Tracker and must not be modified
- *   or freed.
  **/
 const gchar *
 tracker_check_version (guint required_major,