@girs/tracker-3.0 3.0.0-3.1.0 → 3.6.0-3.2.2

package/tracker-3.0.d.ts

@@ -19,13 +19,13 @@ import type GLib from '@girs/glib-2.0';
 export namespace Tracker {
 
 /**
- * Flags affecting deserialization of RDF.
+ * Flags affecting deserialization from a RDF data format.
  */
 enum DeserializeFlags {
     /**
      * No flags.
      */
-    DESERIALIZE_FLAGS_NONE,
+    NONE,
 }
 /**
  * Notifier event types.
@@ -69,12 +69,18 @@ enum RdfFormat {
      */
     LAST,
 }
+/**
+ * Flags affecting serialization into a RDF data format.
+ */
 enum SerializeFlags {
-    SERIALIZE_FLAGS_NONE,
+    /**
+     * No flags.
+     */
+    NONE,
 }
 /**
  * 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.
  */
 enum SparqlError {
@@ -204,7 +210,7 @@ enum SparqlConnectionFlags {
      */
     FTS_ENABLE_UNACCENT,
     /**
-     * FTS Search terms are filtered through a stop word list.
+     * FTS Search terms are filtered through a stop word list. This flag is deprecated since Tracker 3.6, and will do nothing.
      */
     FTS_ENABLE_STOP_WORDS,
     /**
@@ -217,6 +223,24 @@ enum SparqlConnectionFlags {
      */
     ANONYMOUS_BNODES,
 }
+/**
+ * The major version of the Tracker library.
+ * 
+ * Like #tracker_major_version, but intended to be used at application compile time.
+ */
+const MAJOR_VERSION: number
+/**
+ * The micro version of the Tracker library.
+ * 
+ * Like #tracker_micro_version, but intended to be used at application compile time.
+ */
+const MICRO_VERSION: number
+/**
+ * The minor version of the Tracker library.
+ * 
+ * Like #tracker_minor_version, but intended to be used at application compile time.
+ */
+const MINOR_VERSION: number
 /**
  * The Prefix of the DC (Dublin Core) namespace
  */
@@ -274,9 +298,10 @@ const PREFIX_TRACKER: string | null
  */
 const PREFIX_XSD: string | null
 /**
- * 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
@@ -284,31 +309,32 @@ const PREFIX_XSD: string | null
  * 
  * 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.)
  * @param required_major the required major version.
  * @param required_minor the required minor version.
  * @param required_micro the required micro version.
- * @returns %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.
+ * @returns %NULL if the Tracker library is compatible with the   given version, or a string describing the version mismatch.
  */
 function check_version(required_major: number, required_minor: number, required_micro: number): string | null
 function sparql_error_quark(): GLib.Quark
 /**
  * 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.
  * @param literal a string to escape
  * @returns the escaped string
  */
 function sparql_escape_string(literal: string | null): string | null
 /**
- * Calls tracker_sparql_escape_uri_printf().
+ * Escapes a string for use as a URI.
  * @param uri a string to be escaped, following the tracker sparql rules
- * @returns a newly-allocated string holding the result. The returned string should be freed with g_free() when no longer needed.
+ * @returns a newly-allocated string holding the result.
  */
 function sparql_escape_uri(uri: string | null): string | null
 /**
@@ -330,7 +356,7 @@ module Batch {
         // Own constructor properties of Tracker-3.0.Tracker.Batch
 
         /**
-         * The #TrackerSparqlConnection the batch belongs to.
+         * The [class`Tracker`.SparqlConnection] the batch belongs to.
          */
         connection?: SparqlConnection | null
     }
@@ -342,7 +368,7 @@ interface Batch {
     // Own properties of Tracker-3.0.Tracker.Batch
 
     /**
-     * The #TrackerSparqlConnection the batch belongs to.
+     * The [class`Tracker`.SparqlConnection] the batch belongs to.
      */
     readonly connection: SparqlConnection
 
@@ -352,28 +378,42 @@ interface Batch {
 
     // Owm methods of Tracker-3.0.Tracker.Batch
 
+    /**
+     * Inserts the RDF data contained in `stream` as part of `batch`.
+     * 
+     * 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`.
+     * 
+     * The `flags` argument is reserved for future expansions, currently
+     * %TRACKER_DESERIALIZE_FLAGS_NONE must be passed.
+     * @param flags Deserialization flags
+     * @param format RDF format of data in stream
+     * @param default_graph Default graph that will receive the RDF data
+     * @param stream Input stream with RDF data
+     */
+    add_rdf(flags: DeserializeFlags, format: RdfFormat, default_graph: string | null, stream: Gio.InputStream): void
     /**
      * Adds the RDF represented by `resource` to `batch`.
      * @param graph RDF graph to insert the resource to
-     * @param resource a #TrackerResource
+     * @param resource A [class`Tracker`.Resource]
      */
     add_resource(graph: string | null, resource: Resource): void
     /**
      * Adds an SPARQL update string to `batch`.
-     * @param sparql a SPARQL update string
+     * @param sparql A SPARQL update string
      */
     add_sparql(sparql: string | null): void
     /**
-     * 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, };
      * 
@@ -383,45 +423,36 @@ interface 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().
-     * @param stmt a #TrackerSparqlStatement containing a SPARQL update
-     * @param variable_names the names of each bound parameter
-     * @param values the values of each bound parameter
+     * 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].
+     * @param stmt A [class`Tracker`.SparqlStatement] containing a SPARQL update
+     * @param variable_names The names of each bound parameter
+     * @param values The values of each bound parameter
      */
     add_statement(stmt: SparqlStatement, variable_names: string[], values: any[]): void
     /**
      * Executes the batch. This operations happens synchronously.
-     * @param cancellable a #GCancellable, or %NULL
+     * @param cancellable Optional [type`Gio`.Cancellable]
      * @returns %TRUE of there were no errors, %FALSE otherwise
      */
     execute(cancellable: Gio.Cancellable | null): boolean
     /**
      * Executes the batch. This operation happens asynchronously, when
      * finished `callback` will be executed.
-     * @param cancellable a #GCancellable, or %NULL
-     * @param callback user-defined #GAsyncReadyCallback to be called when            asynchronous operation is finished.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     execute_async(cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -432,18 +463,19 @@ interface Batch {
      * 
      * Executes the batch. This operation happens asynchronously, when
      * finished `callback` will be executed.
-     * @param cancellable a #GCancellable, or %NULL
+     * @param cancellable Optional [type`Gio`.Cancellable]
      * @returns A Promise of: %TRUE of there were no errors, %FALSE otherwise
      */
     execute_async(cancellable: Gio.Cancellable | null): globalThis.Promise<boolean>
     /**
-     * Finishes the operation started with tracker_batch_execute_async().
-     * @param res a #GAsyncResult with the result of the operation
+     * Finishes the operation started with [method`Tracker`.Batch.execute_async].
+     * @param res A [type`Gio`.AsyncResult] with the result of the operation
      * @returns %TRUE of there were no errors, %FALSE otherwise
      */
     execute_finish(res: Gio.AsyncResult): boolean
     /**
-     * Returns the #TrackerSparqlConnection that this batch was created from.
+     * Returns the [class`Tracker`.SparqlConnection] that this batch was created
+     * from.
      * @returns The SPARQL connection of this batch.
      */
     get_connection(): SparqlConnection
@@ -459,6 +491,26 @@ interface Batch {
     disconnect(id: number): void
 }
 
+/**
+ * `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.
+ * 
+ * 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.
+ * @class 
+ */
 class Batch extends GObject.Object {
 
     // Own properties of Tracker-3.0.Tracker.Batch
@@ -480,6 +532,9 @@ module Endpoint {
 
         // Own constructor properties of Tracker-3.0.Tracker.Endpoint
 
+        /**
+         * The [class`Tracker`.SparqlConnection] being proxied by this endpoint.
+         */
         sparql_connection?: SparqlConnection | null
     }
 
@@ -489,6 +544,9 @@ interface Endpoint {
 
     // Own properties of Tracker-3.0.Tracker.Endpoint
 
+    /**
+     * The [class`Tracker`.SparqlConnection] being proxied by this endpoint.
+     */
     readonly sparql_connection: SparqlConnection
 
     // Own fields of Tracker-3.0.Tracker.Endpoint
@@ -498,7 +556,8 @@ interface Endpoint {
     // Owm methods of Tracker-3.0.Tracker.Endpoint
 
     /**
-     * Returns the #TrackerSparqlConnection that this endpoint proxies.
+     * Returns the [class`Tracker`.SparqlConnection] that this endpoint proxies
+     * to a wider audience.
      * @returns The proxied SPARQL connection
      */
     get_sparql_connection(): SparqlConnection
@@ -515,8 +574,19 @@ interface Endpoint {
 }
 
 /**
- * The <structname>TrackerEndpoint</structname> object represents a public
- * connection to a #TrackerSparqlConnection.
+ * `TrackerEndpoint` is a helper object to make RDF triple stores represented
+ * by a [class`Tracker`.SparqlConnection] publicly available to other processes/hosts.
+ * 
+ * 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.
  * @class 
  */
 class Endpoint extends GObject.Object {
@@ -540,7 +610,13 @@ module EndpointDBus {
 
         // Own constructor properties of Tracker-3.0.Tracker.EndpointDBus
 
+        /**
+         * The [class`Gio`.DBusConnection] where the connection is proxied through.
+         */
         dbus_connection?: Gio.DBusConnection | null
+        /**
+         * The DBus object path that this endpoint manages.
+         */
         object_path?: string | null
     }
 
@@ -550,7 +626,13 @@ interface EndpointDBus extends Gio.Initable {
 
     // Own properties of Tracker-3.0.Tracker.EndpointDBus
 
+    /**
+     * The [class`Gio`.DBusConnection] where the connection is proxied through.
+     */
     readonly dbus_connection: Gio.DBusConnection
+    /**
+     * The DBus object path that this endpoint manages.
+     */
     readonly object_path: string | null
 
     // Class property signals of Tracker-3.0.Tracker.EndpointDBus
@@ -571,8 +653,40 @@ interface EndpointDBus extends Gio.Initable {
 }
 
 /**
- * The <structname>TrackerEndpointDBus</structname> object represents a public
- * connection to a #TrackerSparqlConnection on a DBus object path.
+ * `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 from the one that created [class`Tracker`.SparqlConnection].
  * @class 
  */
 class EndpointDBus extends Endpoint {
@@ -587,24 +701,24 @@ class EndpointDBus extends Endpoint {
     constructor(config?: EndpointDBus.ConstructorProperties) 
     /**
      * 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`.
      * @constructor 
-     * @param sparql_connection a #TrackerSparqlConnection
-     * @param dbus_connection a #GDBusConnection
-     * @param object_path the object path to use, or %NULL for the default
-     * @param cancellable a #GCancellable, or %NULL
-     * @returns a #TrackerEndpointDBus object.
+     * @param sparql_connection The [class`Tracker`.SparqlConnection] being made public
+     * @param dbus_connection #GDBusConnection to expose the DBus object over
+     * @param object_path The object path to use, or %NULL to use the default
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns a `TrackerEndpointDBus` object.
      */
     constructor(sparql_connection: SparqlConnection, dbus_connection: Gio.DBusConnection, object_path: string | null, cancellable: Gio.Cancellable | null) 
     /**
      * 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`.
      * @constructor 
-     * @param sparql_connection a #TrackerSparqlConnection
-     * @param dbus_connection a #GDBusConnection
-     * @param object_path the object path to use, or %NULL for the default
-     * @param cancellable a #GCancellable, or %NULL
-     * @returns a #TrackerEndpointDBus object.
+     * @param sparql_connection The [class`Tracker`.SparqlConnection] being made public
+     * @param dbus_connection #GDBusConnection to expose the DBus object over
+     * @param object_path The object path to use, or %NULL to use the default
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns a `TrackerEndpointDBus` object.
      */
     static new(sparql_connection: SparqlConnection, dbus_connection: Gio.DBusConnection, object_path: string | null, cancellable: Gio.Cancellable | null): EndpointDBus
     _init(config?: EndpointDBus.ConstructorProperties): void
@@ -628,7 +742,13 @@ module EndpointHttp {
 
         // Own constructor properties of Tracker-3.0.Tracker.EndpointHttp
 
+        /**
+         * [class`Gio`.TlsCertificate] to encrypt the communication.
+         */
         http_certificate?: Gio.TlsCertificate | null
+        /**
+         * HTTP port used to listen requests.
+         */
         http_port?: number | null
     }
 
@@ -638,7 +758,13 @@ interface EndpointHttp extends Gio.Initable {
 
     // Own properties of Tracker-3.0.Tracker.EndpointHttp
 
+    /**
+     * [class`Gio`.TlsCertificate] to encrypt the communication.
+     */
     readonly http_certificate: Gio.TlsCertificate
+    /**
+     * HTTP port used to listen requests.
+     */
     readonly http_port: number
 
     // Own signals of Tracker-3.0.Tracker.EndpointHttp
@@ -665,8 +791,45 @@ interface EndpointHttp extends Gio.Initable {
 }
 
 /**
- * The <structname>TrackerEndpointHttp</structname> object represents a public
- * connection to a #TrackerSparqlConnection on a HTTP port.
+ * `TrackerEndpointHttp` makes the RDF data in a [class`Tracker`.SparqlConnection]
+ * accessible to other hosts via HTTP.
+ * 
+ * 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 [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 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 from the one that created [class`Tracker`.SparqlConnection].
  * @class 
  */
 class EndpointHttp extends Endpoint {
@@ -684,11 +847,11 @@ class EndpointHttp extends Endpoint {
      * If `certificate` is not %NULL, HTTPS may be used to connect to the
      * endpoint.
      * @constructor 
-     * @param sparql_connection a #TrackerSparqlConnection
-     * @param port HTTP port to listen to
-     * @param certificate certificate to use for encription, or %NULL
-     * @param cancellable a #GCancellable, or %NULL
-     * @returns a #TrackerEndpointDBus object.
+     * @param sparql_connection The [class`Tracker`.SparqlConnection] being made public
+     * @param port HTTP port to handle incoming requests
+     * @param certificate Optional [type`Gio`.TlsCertificate] to use for encription
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns a `TrackerEndpointHttp` object.
      */
     constructor(sparql_connection: SparqlConnection, port: number, certificate: Gio.TlsCertificate | null, cancellable: Gio.Cancellable | null) 
     /**
@@ -696,11 +859,11 @@ class EndpointHttp extends Endpoint {
      * If `certificate` is not %NULL, HTTPS may be used to connect to the
      * endpoint.
      * @constructor 
-     * @param sparql_connection a #TrackerSparqlConnection
-     * @param port HTTP port to listen to
-     * @param certificate certificate to use for encription, or %NULL
-     * @param cancellable a #GCancellable, or %NULL
-     * @returns a #TrackerEndpointDBus object.
+     * @param sparql_connection The [class`Tracker`.SparqlConnection] being made public
+     * @param port HTTP port to handle incoming requests
+     * @param certificate Optional [type`Gio`.TlsCertificate] to use for encription
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns a `TrackerEndpointHttp` object.
      */
     static new(sparql_connection: SparqlConnection, port: number, certificate: Gio.TlsCertificate | null, cancellable: Gio.Cancellable | null): EndpointHttp
     _init(config?: EndpointHttp.ConstructorProperties): void
@@ -725,16 +888,16 @@ interface NamespaceManager {
      * 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.
      * @param prefix a short, unique prefix to identify `namespace`
      * @param ns the URL of the given namespace
      */
     add_prefix(prefix: string | null, ns: string | null): void
     /**
      * 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.
      * @param uri a URI or compact URI
      * @returns (nullable): the compressed URI
@@ -742,10 +905,10 @@ interface NamespaceManager {
     compress_uri(uri: string | null): string | null
     /**
      * 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.
      * @param compact_uri a URI or compact URI
-     * @returns a newly-allocated string
+     * @returns The possibly expanded URI in a newly-allocated string.
      */
     expand_uri(compact_uri: string | null): string | null
     /**
@@ -756,18 +919,19 @@ interface NamespaceManager {
     /**
      * Returns whether `prefix` is known.
      * @param prefix a string
-     * @returns %TRUE if the #TrackerNamespaceManager knows about @prefix, %FALSE otherwise
+     * @returns %TRUE if the `TrackerNamespaceManager` knows about @prefix, %FALSE otherwise
      */
     has_prefix(prefix: string | null): boolean
     /**
      * Looks up the namespace URI corresponding to `prefix,` or %NULL if the prefix
      * is not known.
      * @param prefix a string
-     * @returns a string owned by the #TrackerNamespaceManager, or %NULL
+     * @returns a string owned by the `TrackerNamespaceManager`, or %NULL
      */
     lookup_prefix(prefix: string | null): string | null
     /**
-     * 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
      */
     print_turtle(): string | null
@@ -781,8 +945,17 @@ interface NamespaceManager {
 }
 
 /**
- * The <structname>TrackerNamespaceManager</structname> object represents a
- * mapping of prefixes and namespaces.
+ * `TrackerNamespaceManager` object represents a mapping between namespaces and
+ * their shortened prefixes.
+ * 
+ * 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 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.
  * @class 
  */
 class NamespaceManager extends GObject.Object {
@@ -796,26 +969,26 @@ class NamespaceManager extends GObject.Object {
 
     constructor(config?: NamespaceManager.ConstructorProperties) 
     /**
-     * Creates a new #TrackerNamespaceManager instance.
+     * Creates a new, empty `TrackerNamespaceManager` instance.
      * @constructor 
-     * @returns a new #TrackerNamespaceManager instance
+     * @returns a new `TrackerNamespaceManager` instance
      */
     constructor() 
     /**
-     * Creates a new #TrackerNamespaceManager instance.
+     * Creates a new, empty `TrackerNamespaceManager` instance.
      * @constructor 
-     * @returns a new #TrackerNamespaceManager instance
+     * @returns a new `TrackerNamespaceManager` instance
      */
     static new(): NamespaceManager
     _init(config?: NamespaceManager.ConstructorProperties): void
     /**
-     * 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 a global, shared #TrackerNamespaceManager instance
+     * @returns a global, shared `TrackerNamespaceManager` instance
      */
     static get_default(): NamespaceManager
 }
@@ -862,24 +1035,30 @@ interface Notifier {
     // Owm methods of Tracker-3.0.Tracker.Notifier
 
     /**
-     * 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().
-     * @param connection a #GDBusConnection
+     * [method`Tracker`.Notifier.signal_unsubscribe].
+     * 
+     * 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.
+     * @param connection A [class`Gio`.DBusConnection]
      * @param service DBus service name to subscribe to events for
      * @param object_path DBus object path to subscribe to events for, or %NULL
-     * @param graph graph to listen events for, or %NULL
+     * @param graph Graph to listen events for, or %NULL
      * @returns An ID for this subscription
      */
     signal_subscribe(connection: Gio.DBusConnection, service: string | null, object_path: string | null, graph: string | null): number
     /**
-     * Undoes a DBus signal subscription, the `handler_id` argument was previously
-     * obtained with a tracker_notifier_signal_subscribe() call.
-     * @param handler_id a handler ID obtained with tracker_notifier_signal_subscribe()
+     * Undoes a signal subscription done through [method`Tracker`.Notifier.signal_subscribe].
+     * 
+     * The `handler_id` argument was previously obtained during signal subscription creation.
+     * @param handler_id A signal subscription handler ID
      */
     signal_unsubscribe(handler_id: number): void
 
@@ -901,8 +1080,37 @@ interface Notifier {
 }
 
 /**
- * The <structname>TrackerNotifier</structname> object allows subscribing
- * to changes in the stored data.
+ * `TrackerNotifier` allows receiving notification on changes
+ * in the data stored by a [class`Tracker`.SparqlConnection].
+ * 
+ * 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.
+ * 
+ * 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.
+ * 
+ * The [signal`Tracker`.Notifier::events] signal is emitted in the thread-default
+ * main context of the thread where the `TrackerNotifier` instance was created.
  * @class 
  */
 class Notifier extends GObject.Object {
@@ -952,48 +1160,83 @@ interface Resource {
     // Owm methods of Tracker-3.0.Tracker.Resource
 
     /**
-     * Adds a boolean object to a multi-valued property.
-     * @param property_uri a string identifying the property to modify
-     * @param value the property object
+     * 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).
+     * 
+     * This method corresponds to [xsd:boolean](xsd-ontology.html#xsd:boolean).
+     * @param property_uri A string identifying the property to modify
+     * @param value The property boolean value
      */
     add_boolean(property_uri: string | null, value: boolean): void
     /**
-     * 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).
      * @param property_uri a string identifying the property to modify
      * @param value the property object
      */
     add_datetime(property_uri: string | null, value: GLib.DateTime): void
     /**
-     * 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).
      * @param property_uri a string identifying the property to modify
      * @param value the property object
      */
     add_double(property_uri: string | null, value: number): void
     /**
-     * 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.).
      * @param property_uri a string identifying the property to set
-     * @param value an initialised #GValue
+     * @param value an initialised [struct`GObject`.Value]
      */
     add_gvalue(property_uri: string | null, value: any): void
     /**
-     * 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).
      * @param property_uri a string identifying the property to modify
      * @param value the property object
      */
     add_int(property_uri: string | null, value: number): void
     /**
-     * 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).
      * @param property_uri a string identifying the property to modify
      * @param value the property object
      */
     add_int64(property_uri: string | null, value: number): void
     /**
-     * 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`.
      * @param property_uri a string identifying the property to modify
@@ -1001,14 +1244,28 @@ interface Resource {
      */
     add_relation(property_uri: string | null, resource: Resource): void
     /**
-     * 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).
      * @param property_uri a string identifying the property to modify
      * @param value the property object
      */
     add_string(property_uri: string | null, value: string | null): void
     /**
-     * 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`.
      * @param property_uri a string identifying the property to modify
@@ -1016,8 +1273,16 @@ interface Resource {
      */
     add_take_relation(property_uri: string | null, resource: Resource): void
     /**
-     * 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.
      * @param property_uri a string identifying the property to modify
      * @param value the property object
@@ -1030,7 +1295,7 @@ interface Resource {
      */
     get_first_boolean(property_uri: string | null): boolean
     /**
-     * Returns the first resource object previously assigned to a property.
+     * Returns the first [type`GLib`.DateTime] previously assigned to a property.
      * @param property_uri a string identifying the property to look up
      * @returns the first GDateTime object
      */
@@ -1074,14 +1339,14 @@ interface Resource {
     /**
      * 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 a string owned by the resource
      */
     get_identifier(): string | null
     /**
      * Gets the list of properties defined in `resource`
-     * @returns The list of properties.          The list should be freed with g_list_free().
+     * @returns The list of properties.
      */
     get_properties(): string[]
     /**
@@ -1094,11 +1359,11 @@ interface Resource {
     /**
      * Returns the list of all known values of the given property.
      * @param property_uri a string identifying the property to look up
-     * @returns a #GList of #GValue instances. The list should be freed with g_list_free()
+     * @returns a [struct@GLib.List] of   [struct@GObject.Value] instances. The list should be freed with [func@GLib.List.free]
      */
     get_values(property_uri: string | null): any[] | null
     /**
-     * A helper function that compares a #TrackerResource by its identifier
+     * A helper function that compares a `TrackerResource` by its identifier
      * string.
      * @param identifier a string identifying the resource
      * @returns an integer less than, equal to, or greater than zero, if the          resource identifier is <, == or > than @identifier
@@ -1111,7 +1376,7 @@ interface 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.
      * @param namespaces a set of prefixed URLs, or %NULL to use the     Nepomuk set
      * @returns a newly-allocated string containing JSON-LD data.
@@ -1121,7 +1386,7 @@ interface Resource {
      * 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.
      * @param namespaces a set of prefixed URLs
      * @param format RDF format of the printed string
@@ -1134,7 +1399,7 @@ interface 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.
      * @param namespaces a set of prefixed URLs, or %NULL to use the     Nepomuk set
      * @param graph_id the URN of the graph the data should be added to,     or %NULL
@@ -1148,78 +1413,93 @@ interface Resource {
      * <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.
      * @param namespaces a set of prefixed URLs, or %NULL to use the     Nepomuk set
      * @returns a newly-allocated string
      */
     print_turtle(namespaces: NamespaceManager | null): string | null
     /**
-     * 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 A variant describing the resource,          the reference is floating.
      */
     serialize(): GLib.Variant | null
     /**
-     * Sets a single-valued boolean object.
-     * @param property_uri a string identifying the property to modify
-     * @param value the property object
+     * Sets a boolean property. Replaces any previous value.
+     * 
+     * This method corresponds to [xsd:boolean](xsd-ontology.html#xsd:boolean).
+     * @param property_uri A string identifying the property to modify
+     * @param value The property boolean value
      */
     set_boolean(property_uri: string | null, value: boolean): void
     /**
-     * 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).
      * @param property_uri a string identifying the property to modify
      * @param value the property object
      */
     set_datetime(property_uri: string | null, value: GLib.DateTime): void
     /**
-     * Sets a single-valued double object.
-     * @param property_uri a string identifying the property to modify
-     * @param value the property object
+     * Sets a numeric property with double precision. Replaces any previous value.
+     * 
+     * This method corresponds to [xsd:double](xsd-ontology.html#xsd:double).
+     * @param property_uri A string identifying the property to modify
+     * @param value The property object
      */
     set_double(property_uri: string | null, value: number): void
     /**
-     * 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.).
      * @param property_uri a string identifying the property to set
-     * @param value an initialised #GValue
+     * @param value an initialised [struct`GObject`.Value]
      */
     set_gvalue(property_uri: string | null, value: any): void
     /**
-     * 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.
      * @param identifier a string identifying the resource
      */
     set_identifier(identifier: string | null): void
     /**
-     * Sets a single-valued integer object.
-     * @param property_uri a string identifying the property to modify
-     * @param value the property object
+     * Sets a numeric property with integer precision. Replaces any previous value.
+     * 
+     * This method corresponds to [xsd:integer](xsd-ontology.html#xsd:integer).
+     * @param property_uri A string identifying the property to modify
+     * @param value The property object
      */
     set_int(property_uri: string | null, value: number): void
     /**
-     * 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).
      * @param property_uri a string identifying the property to modify
      * @param value the property object
      */
     set_int64(property_uri: string | null, value: number): void
     /**
-     * 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`.
      * @param property_uri a string identifying the property to modify
@@ -1227,23 +1507,36 @@ interface Resource {
      */
     set_relation(property_uri: string | null, resource: Resource): void
     /**
-     * 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).
      * @param property_uri a string identifying the property to modify
      * @param value the property object
      */
     set_string(property_uri: string | null, value: string | null): void
     /**
-     * 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`.
      * @param property_uri a string identifying the property to modify
      * @param resource the property object
      */
     set_take_relation(property_uri: string | null, resource: Resource): void
     /**
-     * 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.
      * @param property_uri a string identifying the property to modify
      * @param value the property object
@@ -1262,8 +1555,35 @@ interface Resource {
 }
 
 /**
- * The <structname>TrackerResource</structname> object represents information
- * about a given resource.
+ * `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].
  * @class 
  */
 class Resource extends GObject.Object {
@@ -1280,22 +1600,22 @@ class Resource extends GObject.Object {
      * Creates a TrackerResource instance.
      * @constructor 
      * @param identifier A string containing a URI, or %NULL.
-     * @returns a newly created #TrackerResource. Free with g_object_unref() when done
+     * @returns a newly created `TrackerResource`.
      */
     constructor(identifier: string | null) 
     /**
      * Creates a TrackerResource instance.
      * @constructor 
      * @param identifier A string containing a URI, or %NULL.
-     * @returns a newly created #TrackerResource. Free with g_object_unref() when done
+     * @returns a newly created `TrackerResource`.
      */
     static new(identifier: string | null): Resource
     _init(config?: Resource.ConstructorProperties): void
     /**
-     * Deserializes a #TrackerResource previously serialized with
-     * tracker_resource_serialize(). It is implied that both ends
-     * use a common #TrackerNamespaceManager.
-     * @param variant a #GVariant
+     * Deserializes a `TrackerResource` previously serialized with
+     * [method`Tracker`.Resource.serialize]. It is implied that both ends
+     * use a common [class`Tracker`.NamespaceManager].
+     * @param variant a [type`GLib`.Variant]
      * @returns A TrackerResource, or %NULL if          deserialization fails.
      */
     static deserialize(variant: GLib.Variant): Resource | null
@@ -1319,8 +1639,9 @@ interface SparqlConnection {
     // Owm methods of Tracker-3.0.Tracker.SparqlConnection
 
     /**
-     * Closes a SPARQL connection. No other API calls than g_object_unref()
-     * should happen after this call.
+     * Closes a SPARQL connection.
+     * 
+     * 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
@@ -1328,11 +1649,11 @@ interface SparqlConnection {
      */
     close(): void
     /**
-     * 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.
-     * @param cancellable a #GCancellable, or %NULL
-     * @param callback user-defined #GAsyncReadyCallback to be called when            asynchronous operation is finished.
+     * Closes a SPARQL connection asynchronously.
+     * 
+     * No other API calls than g_object_unref() should happen after this call.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     close_async(cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -1341,51 +1662,55 @@ interface SparqlConnection {
     /**
      * Promisified version of {@link close_async}
      * 
-     * 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.
-     * @param cancellable a #GCancellable, or %NULL
+     * Closes a SPARQL connection asynchronously.
+     * 
+     * No other API calls than g_object_unref() should happen after this call.
+     * @param cancellable Optional [type`Gio`.Cancellable]
      * @returns A Promise of: %FALSE if some error occurred, %TRUE otherwise
      */
     close_async(cancellable: Gio.Cancellable | null): globalThis.Promise<boolean>
     /**
-     * Finishes the asynchronous connection close.
-     * @param res the #GAsyncResult
+     * Finishes the operation started with [method`Tracker`.SparqlConnection.close_async].
+     * @param res A [type`Gio`.AsyncResult] with the result of the operation
      * @returns %FALSE if some error occurred, %TRUE otherwise
      */
     close_finish(res: Gio.AsyncResult): boolean
     /**
-     * Creates a new batch to store and execute update commands. If the connection
-     * is readonly or cannot issue SPARQL updates, %NULL will be returned.
-     * @returns (nullable): A new #TrackerBatch
+     * Creates a new [class`Tracker`.Batch] to store and execute SPARQL updates.
+     * 
+     * If the connection is readonly or cannot issue SPARQL updates, %NULL will be returned.
+     * @returns (nullable): A new [class@Tracker.Batch]
      */
     create_batch(): Batch
     /**
-     * Creates a new #TrackerNotifier to notify about changes in `connection`.
-     * See #TrackerNotifier documentation for information about how to use this
+     * Creates a new [class`Tracker`.Notifier] to receive notifications about changes in `connection`.
+     * 
+     * See [class`Tracker`.Notifier] documentation for information about how to use this
      * object.
-     * @returns a newly created notifier. Free with g_object_unref()          when no longer needed.
+     * 
+     * Connections to HTTP endpoints will return %NULL.
+     * @returns A newly created notifier.
      */
-    create_notifier(): Notifier
+    create_notifier(): Notifier | null
     /**
-     * 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`.
+     * 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`.
      * 
-     * 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
+     * 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`.
      * 
      * The `flags` argument is reserved for future expansions, currently
      * %TRACKER_DESERIALIZE_FLAGS_NONE must be passed.
-     * @param flags deserialization flags
+     * @param flags Deserialization flags
      * @param format RDF format of data in stream
-     * @param default_graph default graph that will receive the RDF data
-     * @param stream input stream with RDF data
-     * @param cancellable a #GCancellable
-     * @param callback the #GAsyncReadyCallback called when the operation completes
+     * @param default_graph Default graph that will receive the RDF data
+     * @param stream Input stream with RDF data
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     deserialize_async(flags: DeserializeFlags, format: RdfFormat, default_graph: string | null, stream: Gio.InputStream, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -1394,52 +1719,62 @@ interface SparqlConnection {
     /**
      * Promisified version of {@link deserialize_async}
      * 
-     * 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`.
+     * Loads the RDF data contained in `stream` into the given `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
+     * 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`.
      * 
      * The `flags` argument is reserved for future expansions, currently
      * %TRACKER_DESERIALIZE_FLAGS_NONE must be passed.
-     * @param flags deserialization flags
+     * @param flags Deserialization flags
      * @param format RDF format of data in stream
-     * @param default_graph default graph that will receive the RDF data
-     * @param stream input stream with RDF data
-     * @param cancellable a #GCancellable
+     * @param default_graph Default graph that will receive the RDF data
+     * @param stream Input stream with RDF data
+     * @param cancellable Optional [type`Gio`.Cancellable]
      * @returns A Promise of: %TRUE if all data was inserted successfully.
      */
     deserialize_async(flags: DeserializeFlags, format: RdfFormat, default_graph: string | null, stream: Gio.InputStream, cancellable: Gio.Cancellable | null): globalThis.Promise<boolean>
     /**
-     * Finishes a tracker_sparql_connection_deserialize_async() operation.
-     * In case of error, %NULL will be returned and `error` will be set.
-     * @param result the #GAsyncResult
+     * Finishes the operation started with [method`Tracker`.SparqlConnection.deserialize_async].
+     * @param result A [type`Gio`.AsyncResult] with the result of the operation
      * @returns %TRUE if all data was inserted successfully.
      */
     deserialize_finish(result: Gio.AsyncResult): boolean
     /**
-     * Retrieves a #TrackerNamespaceManager that contains all
+     * Returns a [class`Tracker`.NamespaceManager] that contains all
      * prefixes in the ontology of `connection`.
-     * @returns a #TrackerNamespaceManager for this connection. This object is owned by @connection and must not be freed.
+     * @returns a [class@Tracker.NamespaceManager] with the prefixes of @connection.
      */
     get_namespace_manager(): NamespaceManager
     /**
-     * Prepares a #TrackerSparqlStatement for the SPARQL query contained as a resource
-     * file at `resource_path`. SPARQL Query files typically have the .rq extension.
-     * @param resource_path the resource path of the file to parse.
-     * @param cancellable a #GCancellable, or %NULL
-     * @returns a prepared statement
+     * Prepares a [class`Tracker`.SparqlStatement] for the SPARQL contained as a [struct`Gio`.Resource]
+     * file at `resource_path`.
+     * 
+     * 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.
+     * @param resource_path The resource path of the file to parse.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns A prepared statement
      */
     load_statement_from_gresource(resource_path: string | null, cancellable: Gio.Cancellable | null): SparqlStatement | null
     /**
-     * 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
+     * Maps a `TrackerSparqlConnection` onto another through a `private:`handle_name`` URI.
+     * 
+     * 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> {
@@ -1449,32 +1784,45 @@ interface SparqlConnection {
      * ```
      * 
      * 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().
-     * @param handle_name handle name for `service_connection`
-     * @param service_connection a #TrackerSparqlConnection to use from `connection`
+     * `connection` may only be a `TrackerSparqlConnection` created via
+     * [ctor`Tracker`.SparqlConnection.new] and [func`Tracker`.SparqlConnection.new_async].
+     * @param handle_name Handle name for `service_connection`
+     * @param service_connection a `TrackerSparqlConnection` to use from `connection`
      */
     map_connection(handle_name: string | null, service_connection: SparqlConnection): void
     /**
-     * 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.
-     * @param sparql string containing the SPARQL query
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @returns 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.
+     * 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.
+     * @param sparql String containing the SPARQL query
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns a [class@Tracker.SparqlCursor] with the results.
      */
     query(sparql: string | null, cancellable: Gio.Cancellable | null): SparqlCursor
     /**
-     * Executes asynchronously a SPARQL query.
-     * @param sparql string containing the SPARQL query
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @param callback user-defined #GAsyncReadyCallback to be called when            asynchronous operation is finished.
+     * 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.
+     * @param sparql String containing the SPARQL query
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     query_async(sparql: string | null, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -1483,42 +1831,52 @@ interface SparqlConnection {
     /**
      * Promisified version of {@link query_async}
      * 
-     * Executes asynchronously a SPARQL query.
-     * @param sparql string containing the SPARQL query
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @returns A Promise of: 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.
+     * 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.
+     * @param sparql String containing the SPARQL query
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns A Promise of: a [class@Tracker.SparqlCursor] with the results.
      */
     query_async(sparql: string | null, cancellable: Gio.Cancellable | null): globalThis.Promise<SparqlCursor>
     /**
-     * Finishes the asynchronous SPARQL query operation.
-     * @param res a #GAsyncResult with the result of the operation
-     * @returns 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.
+     * Finishes the operation started with [method`Tracker`.SparqlConnection.query_async].
+     * @param res A [type`Gio`.AsyncResult] with the result of the operation
+     * @returns a [class@Tracker.SparqlCursor] with the results.
      */
     query_finish(res: Gio.AsyncResult): SparqlCursor
     /**
-     * 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.
-     * @param sparql the SPARQL query
-     * @param cancellable a #GCancellable used to cancel the operation, or %NULL
-     * @returns a prepared statement
+     * Prepares the given `SELECT`/`ASK`/`DESCRIBE`/`CONSTRUCT` SPARQL query as a
+     * [class`Tracker`.SparqlStatement].
+     * 
+     * This prepared statement can be executed through [method`Tracker`.SparqlStatement.execute]
+     * or [method`Tracker`.SparqlStatement.serialize_async] families of functions.
+     * @param sparql The SPARQL query
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns A prepared statement
      */
     query_statement(sparql: string | null, cancellable: Gio.Cancellable | null): SparqlStatement | null
     /**
-     * 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.
      * 
      * The `flags` argument is reserved for future expansions, currently
      * %TRACKER_SERIALIZE_FLAGS_NONE must be passed.
-     * @param flags serialization flags
-     * @param format output RDF format
+     * @param flags Serialization flags
+     * @param format Output RDF format
      * @param query SPARQL query
-     * @param cancellable a #GCancellable
-     * @param callback the #GAsyncReadyCallback called when the operation completes
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     serialize_async(flags: SerializeFlags, format: RdfFormat, query: string | null, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -1527,47 +1885,66 @@ interface SparqlConnection {
     /**
      * Promisified version of {@link serialize_async}
      * 
-     * 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.
      * 
      * The `flags` argument is reserved for future expansions, currently
      * %TRACKER_SERIALIZE_FLAGS_NONE must be passed.
-     * @param flags serialization flags
-     * @param format output RDF format
+     * @param flags Serialization flags
+     * @param format Output RDF format
      * @param query SPARQL query
-     * @param cancellable a #GCancellable
-     * @returns A Promise of: a #GInputStream to read RDF content.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns A Promise of: A [class@Gio.InputStream] to read RDF content.
      */
     serialize_async(flags: SerializeFlags, format: RdfFormat, query: string | null, cancellable: Gio.Cancellable | null): globalThis.Promise<Gio.InputStream>
     /**
-     * Finishes a tracker_sparql_connection_serialize_async() operation.
-     * In case of error, %NULL will be returned and `error` will be set.
-     * @param result the #GAsyncResult
-     * @returns a #GInputStream to read RDF content.
+     * Finishes the operation started with [method`Tracker`.SparqlConnection.serialize_async].
+     * @param result A [type`Gio`.AsyncResult] with the result of the operation
+     * @returns A [class@Gio.InputStream] to read RDF content.
      */
     serialize_finish(result: Gio.AsyncResult): Gio.InputStream
     /**
-     * Executes a SPARQL update. The API call is completely
-     * synchronous, so it may block.
+     * Executes a SPARQL update 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.
-     * @param sparql string containing the SPARQL update query
-     * @param cancellable a #GCancellable used to cancel the operation
+     * 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.
+     * @param sparql String containing the SPARQL update query
+     * @param cancellable Optional [type`Gio`.Cancellable]
      */
     update(sparql: string | null, cancellable: Gio.Cancellable | null): void
     /**
      * Executes asynchronously an array of SPARQL updates. All updates in the
      * array are handled within a single transaction.
-     * @param sparql an array of strings containing the SPARQL update queries
-     * @param sparql_length the amount of strings you pass as `sparql`
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @param callback user-defined #GAsyncReadyCallback to be called when            asynchronous operation is finished.
+     * 
+     * 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.
+     * @param sparql An array of strings containing the SPARQL update queries
+     * @param sparql_length The amount of strings you pass as `sparql`
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     update_array_async(sparql: string | null, sparql_length: number, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -1578,23 +1955,43 @@ interface SparqlConnection {
      * 
      * Executes asynchronously an array of SPARQL updates. All updates in the
      * array are handled within a single transaction.
-     * @param sparql an array of strings containing the SPARQL update queries
-     * @param sparql_length the amount of strings you pass as `sparql`
-     * @param cancellable a #GCancellable used to cancel the operation
+     * 
+     * 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.
+     * @param sparql An array of strings containing the SPARQL update queries
+     * @param sparql_length The amount of strings you pass as `sparql`
+     * @param cancellable Optional [type`Gio`.Cancellable]
      * @returns A Promise of: #TRUE if there were no errors.
      */
     update_array_async(sparql: string | null, sparql_length: number, cancellable: Gio.Cancellable | null): globalThis.Promise<boolean>
     /**
-     * Finishes the asynchronous SPARQL update_array operation.
-     * @param res a #GAsyncResult with the result of the operation
+     * Finishes the operation started with [method`Tracker`.SparqlConnection.update_array_async].
+     * @param res A [type`Gio`.AsyncResult] with the result of the operation
      * @returns #TRUE if there were no errors.
      */
     update_array_finish(res: Gio.AsyncResult): boolean
     /**
      * Executes asynchronously a SPARQL update.
-     * @param sparql string containing the SPARQL update query
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @param callback user-defined #GAsyncReadyCallback to be called when            asynchronous operation is finished.
+     * 
+     * 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.
+     * @param sparql String containing the SPARQL update query
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     update_async(sparql: string | null, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -1604,17 +2001,32 @@ interface SparqlConnection {
      * Promisified version of {@link update_async}
      * 
      * Executes asynchronously a SPARQL update.
-     * @param sparql string containing the SPARQL update query
-     * @param cancellable a #GCancellable used to cancel the operation
+     * 
+     * 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.
+     * @param sparql String containing the SPARQL update query
+     * @param cancellable Optional [type`Gio`.Cancellable]
      * @returns A Promise of the result of {@link update_async}
      */
     update_async(sparql: string | null, cancellable: Gio.Cancellable | null): globalThis.Promise<void>
     /**
-     * Executes a SPARQL update and returns the URNs of the generated nodes,
-     * if any. The API call is completely synchronous, so it may block.
+     * Executes a SPARQL update and returns the names of the generated blank nodes.
      * 
-     * The `sparql` query should be built with #TrackerResource, or
-     * its parts correctly escaped using tracker_sparql_escape_string(),
+     * 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 [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
@@ -1623,18 +2035,19 @@ interface SparqlConnection {
      * WHERE clause. The last array holds a string pair with the blank node name
      * (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.
-     * @param sparql string containing the SPARQL update query
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @returns a #GVariant with the generated URNs, which should be freed with g_variant_unref() when no longer used.
+     * @param sparql String containing the SPARQL update query
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns a [type@GLib.Variant] with the generated URNs.
      */
     update_blank(sparql: string | null, cancellable: Gio.Cancellable | null): GLib.Variant
     /**
-     * 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().
-     * @param sparql string containing the SPARQL update query
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @param callback user-defined #GAsyncReadyCallback to be called when            asynchronous operation is finished.
+     * 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].
+     * @param sparql String containing the SPARQL update query
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     update_blank_async(sparql: string | null, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -1643,45 +2056,56 @@ interface SparqlConnection {
     /**
      * Promisified version of {@link update_blank_async}
      * 
-     * 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().
-     * @param sparql string containing the SPARQL update query
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @returns A Promise of: a #GVariant with the generated URNs, which should be freed with g_variant_unref() when no longer used.
+     * 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].
+     * @param sparql String containing the SPARQL update query
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns A Promise of: a [type@GLib.Variant] with the generated URNs.
      */
     update_blank_async(sparql: string | null, cancellable: Gio.Cancellable | null): globalThis.Promise<GLib.Variant>
     /**
-     * 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.
-     * @param res a #GAsyncResult with the result of the operation
-     * @returns a #GVariant with the generated URNs, which should be freed with g_variant_unref() when no longer used.
+     * Finishes the operation started with [method`Tracker`.SparqlConnection.update_blank_async].
+     * 
+     * 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].
+     * @param res A [type`Gio`.AsyncResult] with the result of the operation
+     * @returns a [type@GLib.Variant] with the generated URNs.
      */
     update_blank_finish(res: Gio.AsyncResult): GLib.Variant
     /**
-     * Finishes the asynchronous SPARQL update operation.
-     * @param res a #GAsyncResult with the result of the operation
+     * Finishes the operation started with [method`Tracker`.SparqlConnection.update_async].
+     * @param res A [type`Gio`.AsyncResult] with the result of the operation
      */
     update_finish(res: Gio.AsyncResult): void
     /**
-     * Inserts a resource as described by `resource,` on the graph described by `graph`.
-     * This operation blocks until done.
+     * Inserts a resource as described by `resource` on the given `graph`.
+     * 
+     * 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.
      * @param graph RDF graph where the resource should be inserted/updated, or %NULL for the default graph
-     * @param resource a #TrackerResource
-     * @param cancellable a #GCancellable, or %NULL
+     * @param resource A [class`Tracker`.Resource]
+     * @param cancellable Optional [type`Gio`.Cancellable]
      * @returns #TRUE if there were no errors.
      */
     update_resource(graph: string | null, resource: Resource, cancellable: Gio.Cancellable | null): boolean
     /**
-     * Inserts a resource as described by `resource,` on the graph described by `graph`.
-     * This operation is executed asynchronously, when finished `callback` will be
-     * executed.
+     * Inserts asynchronously a resource as described by `resource` on the given `graph`.
+     * 
+     * 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.
      * @param graph RDF graph where the resource should be inserted/updated, or %NULL for the default graph
-     * @param resource a #TrackerResource
-     * @param cancellable a #GCancellable, or %NULL
-     * @param callback the #GAsyncReadyCallback called when the operation completes
+     * @param resource A [class`Tracker`.Resource]
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     update_resource_async(graph: string | null, resource: Resource, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -1690,28 +2114,31 @@ interface SparqlConnection {
     /**
      * Promisified version of {@link update_resource_async}
      * 
-     * Inserts a resource as described by `resource,` on the graph described by `graph`.
-     * This operation is executed asynchronously, when finished `callback` will be
-     * executed.
+     * Inserts asynchronously a resource as described by `resource` on the given `graph`.
+     * 
+     * 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.
      * @param graph RDF graph where the resource should be inserted/updated, or %NULL for the default graph
-     * @param resource a #TrackerResource
-     * @param cancellable a #GCancellable, or %NULL
+     * @param resource A [class`Tracker`.Resource]
+     * @param cancellable Optional [type`Gio`.Cancellable]
      * @returns A Promise of: #TRUE if there were no errors.
      */
     update_resource_async(graph: string | null, resource: Resource, cancellable: Gio.Cancellable | null): globalThis.Promise<boolean>
     /**
-     * Finishes a tracker_sparql_connection_update_resource_async() operation.
-     * @param res a #GAsyncResult with the result of the operation
+     * Finishes the operation started with [method`Tracker`.SparqlConnection.update_resource_async].
+     * @param res A [type`Gio`.AsyncResult] with the result of the operation
      * @returns #TRUE if there were no errors.
      */
     update_resource_finish(res: Gio.AsyncResult): boolean
     /**
-     * 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.
-     * @param sparql the SPARQL update
-     * @param cancellable a #GCancellable used to cancel the operation, or %NULL
-     * @returns a prepared statement
+     * Prepares the given `INSERT`/`DELETE` SPARQL as a [class`Tracker`.SparqlStatement].
+     * 
+     * This prepared statement can be executed through
+     * the [method`Tracker`.SparqlStatement.update] family of functions.
+     * @param sparql The SPARQL update
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns A prepared statement
      */
     update_statement(sparql: string | null, cancellable: Gio.Cancellable | null): SparqlStatement | null
 
@@ -1724,8 +2151,65 @@ interface SparqlConnection {
 }
 
 /**
- * The <structname>TrackerSparqlConnection</structname> object represents a
- * SPARQL connection.
+ * `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.
  * @class 
  */
 class SparqlConnection extends GObject.Object {
@@ -1740,115 +2224,141 @@ class SparqlConnection extends GObject.Object {
     constructor(config?: SparqlConnection.ConstructorProperties) 
     /**
      * Connects to a database owned by another process on the
-     * local machine.
+     * local machine via DBus.
      * @constructor 
      * @param service_name The name of the D-Bus service to connect to.
      * @param object_path The path to the object, or %NULL to use the default.
-     * @param dbus_connection The #GDBusConnection to use, or %NULL to use the session bus
-     * @returns a new #TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.
+     * @param dbus_connection The [type`Gio`.DBusConnection] to use, or %NULL to use the session bus
+     * @returns a new `TrackerSparqlConnection`.
      */
     static bus_new(service_name: string | null, object_path: string | null, dbus_connection: Gio.DBusConnection | null): SparqlConnection
     /**
-     * Completion function for tracker_sparql_connection_bus_new_async().
+     * Finishes the operation started with [func`Tracker`.SparqlConnection.bus_new_async].
      * @constructor 
-     * @param result the #GAsyncResult
-     * @returns a new #TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.
+     * @param result A [type`Gio`.AsyncResult] with the result of the operation
+     * @returns a new `TrackerSparqlConnection`.
      */
     static bus_new_finish(result: Gio.AsyncResult): SparqlConnection
     /**
-     * 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.
+     * 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.
      * @constructor 
-     * @param flags values from #TrackerSparqlConnectionFlags
-     * @param store the directory that contains the database as a #GFile, or %NULL
-     * @param ontology the directory that contains the database schemas as a #GFile, or %NULL
-     * @param cancellable a #GCancellable, or %NULL
-     * @returns a new #TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.
+     * @param flags Connection flags to define the SPARQL connection behavior
+     * @param store The directory that contains the database as a [iface`Gio`.File], or %NULL
+     * @param ontology The directory that contains the database schemas as a [iface`Gio`.File], or %NULL
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns a new `TrackerSparqlConnection`.
      */
     constructor(flags: SparqlConnectionFlags, store: Gio.File | null, ontology: Gio.File | null, cancellable: Gio.Cancellable | null) 
     /**
-     * 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.
+     * 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.
      * @constructor 
-     * @param flags values from #TrackerSparqlConnectionFlags
-     * @param store the directory that contains the database as a #GFile, or %NULL
-     * @param ontology the directory that contains the database schemas as a #GFile, or %NULL
-     * @param cancellable a #GCancellable, or %NULL
-     * @returns a new #TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.
+     * @param flags Connection flags to define the SPARQL connection behavior
+     * @param store The directory that contains the database as a [iface`Gio`.File], or %NULL
+     * @param ontology The directory that contains the database schemas as a [iface`Gio`.File], or %NULL
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns a new `TrackerSparqlConnection`.
      */
     static new(flags: SparqlConnectionFlags, store: Gio.File | null, ontology: Gio.File | null, cancellable: Gio.Cancellable | null): SparqlConnection
     /**
-     * Completion function for tracker_sparql_connection_new_async().
+     * Finishes the operation started with [func`Tracker`.SparqlConnection.new_async].
      * @constructor 
-     * @param result the #GAsyncResult
+     * @param result A [type`Gio`.AsyncResult] with the result of the operation
      */
     static new_finish(result: Gio.AsyncResult): SparqlConnection
     /**
-     * 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.
      * @constructor 
      * @param uri_base Base URI of the remote connection
-     * @returns a new remote #TrackerSparqlConnection. Call g_object_unref() on the object when no longer used.
+     * @returns a new remote `TrackerSparqlConnection`.
      */
     static remote_new(uri_base: string | null): SparqlConnection
     _init(config?: SparqlConnection.ConstructorProperties): void
     /**
-     * Asynchronous version of tracker_sparql_connection_new().
-     * @param flags values from #TrackerSparqlConnectionFlags
-     * @param store the directory that contains the database as a #GFile, or %NULL
-     * @param ontology the directory that contains the database schemas as a #GFile, or %NULL
-     * @param cancellable a #GCancellable, or %NULL
-     * @param callback the #GAsyncReadyCallback called when the operation completes
+     * Creates or opens a process-local database asynchronously.
+     * 
+     * See [ctor`Tracker`.SparqlConnection.new] for more information.
+     * @param flags Connection flags to define the SPARQL connection behavior
+     * @param store The directory that contains the database as a [iface`Gio`.File], or %NULL
+     * @param ontology The directory that contains the database schemas as a [iface`Gio`.File], or %NULL
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     static new_async(flags: SparqlConnectionFlags, store: Gio.File | null, ontology: Gio.File | null, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<SparqlConnection> | null): void
     /**
-     * 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.
      * @param service_name The name of the D-Bus service to connect to.
      * @param object_path The path to the object, or %NULL to use the default.
-     * @param dbus_connection The #GDBusConnection to use, or %NULL to use the session bus
-     * @param cancellable a #GCancellable, or %NULL
-     * @param callback the #GAsyncReadyCallback called when the operation completes
+     * @param dbus_connection The [class`Gio`.DBusConnection] to use, or %NULL to use the session bus
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback User-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     static bus_new_async(service_name: string | null, object_path: string | null, dbus_connection: Gio.DBusConnection | null, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<SparqlConnection> | null): void
 }
@@ -1862,7 +2372,7 @@ module SparqlCursor {
         // Own constructor properties of Tracker-3.0.Tracker.SparqlCursor
 
         /**
-         * The #TrackerSparqlConnection used to retrieve the results.
+         * The [class`Tracker`.SparqlConnection] used to retrieve the results.
          */
         connection?: SparqlConnection | null
     }
@@ -1874,9 +2384,12 @@ interface SparqlCursor {
     // Own properties of Tracker-3.0.Tracker.SparqlCursor
 
     /**
-     * The #TrackerSparqlConnection used to retrieve the results.
+     * The [class`Tracker`.SparqlConnection] used to retrieve the results.
      */
     readonly connection: SparqlConnection
+    /**
+     * Number of columns available in the result set.
+     */
     readonly n_columns: number
 
     // Own fields of Tracker-3.0.Tracker.SparqlCursor
@@ -1886,82 +2399,124 @@ interface SparqlCursor {
     // Owm methods of Tracker-3.0.Tracker.SparqlCursor
 
     /**
-     * Closes the iterator, making it invalid.
+     * Closes the cursor. The object can only be freed after this call.
      */
     close(): void
     /**
      * Retrieve a boolean for the current row in `column`.
+     * 
+     * If the row/column do not have a boolean value, the result is
+     * undefined, see [method`Tracker`.SparqlCursor.get_value_type].
      * @param column column number to retrieve (first one is 0)
-     * @returns a #gboolean.
+     * @returns a boolean value.
      */
     get_boolean(column: number): boolean
     /**
-     * Returns the #TrackerSparqlConnection associated with this
-     * #TrackerSparqlCursor.
-     * @returns the cursor #TrackerSparqlConnection. The returned object must not be unreferenced by the caller.
+     * Returns the [class`Tracker`.SparqlConnection] associated with this
+     * `TrackerSparqlCursor`.
+     * @returns the cursor [class@Tracker.SparqlConnection]. The returned object must not be unreferenced by the caller.
      */
     get_connection(): SparqlConnection
     /**
-     * Retrieve an GDateTime pointer for the current row in `column`.
-     * @param column column number to retrieve (first one is 0)
-     * @returns #GDateTime object, or %NULL if the given column does not contain a xsd:date or xsd:dateTime
+     * Retrieves a [type`GLib`.DateTime] pointer for the current row in `column`.
+     * @param column Column number to retrieve (first one is 0)
+     * @returns [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).
      */
     get_datetime(column: number): GLib.DateTime | null
     /**
      * Retrieve a double for the current row in `column`.
+     * 
+     * If the row/column do not have a integer or double value, the result is
+     * undefined, see [method`Tracker`.SparqlCursor.get_value_type].
      * @param column column number to retrieve (first one is 0)
-     * @returns a double.
+     * @returns a double value.
      */
     get_double(column: number): number
     /**
      * Retrieve an integer for the current row in `column`.
+     * 
+     * If the row/column do not have an integer value, the result is
+     * undefined, see [method`Tracker`.SparqlCursor.get_value_type].
      * @param column column number to retrieve (first one is 0)
-     * @returns a #gint64.
+     * @returns a 64-bit integer value.
      */
     get_integer(column: number): number
     /**
+     * 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.
      */
     get_n_columns(): number
     /**
      * 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.
      * @param column column number to retrieve (first one is 0)
-     * @returns a string which must not be freed. %NULL is returned if the column is not in the [0,#n_columns] range.
+     * @returns a string which must not be freed. %NULL is returned if the column is not in the `[0, n_columns]` range, or if the row/column refer to a nullable optional value in the result set.
      */
     get_string(column: number): [ /* returnType */ string | null, /* length */ number | null ]
     /**
-     * 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].
+     * 
+     * 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.
      * @param column column number to retrieve (first one is 0)
-     * @returns a #TrackerSparqlValueType.
+     * @returns a [enum@Tracker.SparqlValueType] expressing the content type of   the given column for the current row.
      */
     get_value_type(column: number): SparqlValueType
     /**
-     * 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.
      * @param column column number to retrieve (first one is 0)
-     * @returns a string which must not be freed.
+     * @returns The name of the given column.
      */
     get_variable_name(column: number): string | null
     /**
-     * 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.
      * @param column column number to retrieve (first one is 0)
      * @returns a %TRUE or %FALSE.
      */
     is_bound(column: number): boolean
     /**
-     * Iterates to the next result. This is completely synchronous and
-     * it may block.
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @returns %FALSE if no more results found, otherwise %TRUE.
+     * Iterates the cursor to the next result.
+     * 
+     * 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.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns %FALSE if there are no more results or if an error is found, otherwise %TRUE.
      */
     next(cancellable: Gio.Cancellable | null): boolean
     /**
-     * Iterates, asynchronously, to the next result.
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @param callback user-defined #GAsyncReadyCallback to be called when            asynchronous operation is finished.
+     * 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.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback user-defined [type`Gio`.AsyncReadyCallback] to be called when            asynchronous operation is finished.
      */
     next_async(cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -1970,15 +2525,24 @@ interface SparqlCursor {
     /**
      * Promisified version of {@link next_async}
      * 
-     * Iterates, asynchronously, to the next result.
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @returns A Promise of: %FALSE if no more results found, otherwise %TRUE.
+     * 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.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns A Promise of: %FALSE if there are no more results or if an error is found, otherwise %TRUE.
      */
     next_async(cancellable: Gio.Cancellable | null): globalThis.Promise<boolean>
     /**
-     * Finishes the asynchronous iteration to the next result.
-     * @param res a #GAsyncResult with the result of the operation
-     * @returns %FALSE if no more results found, otherwise %TRUE.
+     * Finishes the asynchronous iteration to the next result started with
+     * [method`Tracker`.SparqlCursor.next_async].
+     * @param res a [type`Gio`.AsyncResult] with the result of the operation
+     * @returns %FALSE if there are no more results or if an error is found, otherwise %TRUE.
      */
     next_finish(res: Gio.AsyncResult): boolean
     /**
@@ -2001,8 +2565,31 @@ interface SparqlCursor {
 }
 
 /**
- * The <structname>TrackerSparqlCursor</structname> object represents an
- * iterator of results.
+ * `TrackerSparqlCursor` provides the methods to iterate the results of a SPARQL query.
+ * 
+ * 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.
  * @class 
  */
 class SparqlCursor extends GObject.Object {
@@ -2027,7 +2614,7 @@ module SparqlStatement {
         // Own constructor properties of Tracker-3.0.Tracker.SparqlStatement
 
         /**
-         * The #TrackerSparqlConnection used to perform the query.
+         * The [class`Tracker`.SparqlConnection] the statement was created for.
          */
         connection?: SparqlConnection | null
         /**
@@ -2043,7 +2630,7 @@ interface SparqlStatement {
     // Own properties of Tracker-3.0.Tracker.SparqlStatement
 
     /**
-     * The #TrackerSparqlConnection used to perform the query.
+     * The [class`Tracker`.SparqlConnection] the statement was created for.
      */
     readonly connection: SparqlConnection
     /**
@@ -2058,59 +2645,71 @@ interface SparqlStatement {
     // Owm methods of Tracker-3.0.Tracker.SparqlStatement
 
     /**
-     * Binds the boolean `value` to variable `name`.
+     * Binds the boolean `value` to the parameterized variable given by `name`.
      * @param name variable name
      * @param value value
      */
     bind_boolean(name: string | null, value: boolean): void
     /**
-     * Binds the GDateTime `value` to variable `name`.
+     * Binds the [type`GLib`.DateTime] `value` to the parameterized variable given by `name`.
      * @param name variable name
      * @param value value
      */
     bind_datetime(name: string | null, value: GLib.DateTime): void
     /**
-     * Binds the double `value` to variable `name`.
+     * Binds the double `value` to the parameterized variable given by `name`.
      * @param name variable name
      * @param value value
      */
     bind_double(name: string | null, value: number): void
     /**
-     * Binds the integer `value` to variable `name`.
+     * Binds the integer `value` to the parameterized variable given by `name`.
      * @param name variable name
      * @param value value
      */
     bind_int(name: string | null, value: number): void
     /**
-     * Binds the string `value` to variable `name`.
+     * Binds the string `value` to the parameterized variable given by `name`.
      * @param name variable name
      * @param value value
      */
     bind_string(name: string | null, value: string | null): void
     /**
-     * Clears all boolean/string/integer/double bindings.
+     * Clears all bindings.
      */
     clear_bindings(): void
     /**
-     * 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().
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @returns A #TrackerSparqlCursor
+     * [method`Tracker`.SparqlConnection.load_statement_from_gresource].
+     * An error will be raised if this method is called on a `INSERT` or `DELETE`
+     * SPARQL query.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns A `TrackerSparqlCursor` with the query results.
      */
     execute(cancellable: Gio.Cancellable | null): SparqlCursor
     /**
-     * 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().
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @param callback user-defined #GAsyncReadyCallback to be called when            asynchronous operation is finished.
+     * [method`Tracker`.SparqlConnection.load_statement_from_gresource].
+     * An error will be raised if this method is called on a `INSERT` or `DELETE`
+     * SPARQL query.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback user-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     execute_async(cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -2119,25 +2718,31 @@ interface SparqlStatement {
     /**
      * Promisified version of {@link execute_async}
      * 
-     * 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 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().
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @returns A Promise of: A #TrackerSparqlCursor
+     * [method`Tracker`.SparqlConnection.load_statement_from_gresource].
+     * An error will be raised if this method is called on a `INSERT` or `DELETE`
+     * SPARQL query.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns A Promise of: A `TrackerSparqlCursor` with the query results.
      */
     execute_async(cancellable: Gio.Cancellable | null): globalThis.Promise<SparqlCursor>
     /**
      * Finishes the asynchronous operation started through
-     * tracker_sparql_statement_execute_async().
-     * @param res The #GAsyncResult from the callback used to return the #TrackerSparqlCursor
-     * @returns A #TrackerSparqlCursor
+     * [method`Tracker`.SparqlStatement.execute_async].
+     * @param res a [type`Gio`.AsyncResult] with the result of the operation
+     * @returns A `TrackerSparqlCursor` with the query results.
      */
     execute_finish(res: Gio.AsyncResult): SparqlCursor
     /**
-     * Returns the #TrackerSparqlConnection that this statement was created from.
+     * Returns the [class`Tracker`.SparqlConnection] that this statement was created for.
      * @returns The SPARQL connection of this statement.
      */
     get_connection(): SparqlConnection
@@ -2147,9 +2752,10 @@ interface SparqlStatement {
      */
     get_sparql(): string | null
     /**
-     * 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.
@@ -2158,11 +2764,11 @@ interface SparqlStatement {
      * 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.
      * @param flags serialization flags
      * @param format RDF format of the serialized data
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @param callback user-defined #GAsyncReadyCallback to be called when            asynchronous operation is finished.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback user-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     serialize_async(flags: SerializeFlags, format: RdfFormat, cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -2171,9 +2777,10 @@ interface SparqlStatement {
     /**
      * Promisified version of {@link serialize_async}
      * 
-     * 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.
@@ -2182,38 +2789,44 @@ interface SparqlStatement {
      * 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.
      * @param flags serialization flags
      * @param format RDF format of the serialized data
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @returns A Promise of: a #GInputStream to read RDF content.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @returns A Promise of: a [class@Gio.InputStream] to read RDF content.
      */
     serialize_async(flags: SerializeFlags, format: RdfFormat, cancellable: Gio.Cancellable | null): globalThis.Promise<Gio.InputStream>
     /**
-     * Finishes a tracker_sparql_statement_serialize_async() operation.
-     * In case of error, %NULL will be returned and `error` will be set.
-     * @param result the #GAsyncResult
-     * @returns a #GInputStream to read RDF content.
+     * Finishes the asynchronous operation started through
+     * [method`Tracker`.SparqlStatement.serialize_async].
+     * @param result a [type`Gio`.AsyncResult] with the result of the operation
+     * @returns a [class@Gio.InputStream] to read RDF content.
      */
     serialize_finish(result: Gio.AsyncResult): Gio.InputStream
     /**
-     * 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().
-     * @param cancellable a #GCancellable used to cancel the operation
+     * 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.
+     * @param cancellable Optional [type`Gio`.Cancellable]
      * @returns %TRUE if the update finished with no errors, %FALSE otherwise
      */
     update(cancellable: Gio.Cancellable | null): boolean
     /**
-     * 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().
-     * @param cancellable a #GCancellable used to cancel the operation
-     * @param callback user-defined #GAsyncReadyCallback to be called when            asynchronous operation is finished.
+     * 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.
+     * @param cancellable Optional [type`Gio`.Cancellable]
+     * @param callback user-defined [type`Gio`.AsyncReadyCallback] to be called when            the asynchronous operation is finished.
      */
     update_async(cancellable: Gio.Cancellable | null, callback: Gio.AsyncReadyCallback<this> | null): void
 
@@ -2222,19 +2835,22 @@ interface SparqlStatement {
     /**
      * Promisified version of {@link update_async}
      * 
-     * 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().
-     * @param cancellable a #GCancellable used to cancel the operation
+     * 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.
+     * @param cancellable Optional [type`Gio`.Cancellable]
      * @returns A Promise of: %TRUE if the update finished with no errors, %FALSE otherwise
      */
     update_async(cancellable: Gio.Cancellable | null): globalThis.Promise<boolean>
     /**
      * Finishes the asynchronous update started through
-     * tracker_sparql_statement_update_async().
-     * @param result The #GAsyncResult from the callback used to return the #TrackerSparqlCursor
+     * [method`Tracker`.SparqlStatement.update_async].
+     * @param result a [type`Gio`.AsyncResult] with the result of the operation
      * @returns %TRUE if the update finished with no errors, %FALSE otherwise
      */
     update_finish(result: Gio.AsyncResult): boolean
@@ -2254,8 +2870,36 @@ interface SparqlStatement {
 }
 
 /**
- * The <structname>TrackerSparqlStatement</structname> object represents
- * a prepared query statement.
+ * `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 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
+ * [method`Tracker`.SparqlStatement.execute_async] or [method`Tracker`.SparqlStatement.execute].
+ * 
+ * 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.
  * @class 
  */
 class SparqlStatement extends GObject.Object {
@@ -2335,7 +2979,7 @@ interface NotifierEvent {
      * 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
      */
     get_urn(): string | null