[tracker/wip/carlosg/tracker-3.0-api-breaks: 63/79] Further updates to docs and introspection annotations.

[Carlos Garnacho <carlosg src gnome org>]

commit 0753f7a383b34f974ff7ba7669a2dba7d2aaa0a9
Author: Sam Thursfield <sam afuera me uk>
Date:   Tue Jan 21 00:26:01 2020 +0100

    Further updates to docs and introspection annotations.

 .../libtracker-sparql-sections.txt                 |  6 +----
 src/libtracker-sparql/tracker-connection.c         | 30 ++++++++++++----------
 src/libtracker-sparql/tracker-endpoint-dbus.c      | 13 ++++++++++
 src/libtracker-sparql/tracker-notifier.h           |  2 --
 4 files changed, 31 insertions(+), 20 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt 
b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
index 996b6316c..cdde7b3cb 100644
--- a/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
+++ b/docs/reference/libtracker-sparql/libtracker-sparql-sections.txt
@@ -121,6 +121,7 @@ tracker_sparql_connection_update_blank
 tracker_sparql_connection_update_blank_async
 tracker_sparql_connection_update_blank_finish
 tracker_sparql_connection_get_namespace_manager
+tracker_sparql_connection_create_notifier
 tracker_sparql_connection_close
 <SUBSECTION Standard>
 TrackerSparqlConnectionClass
@@ -153,9 +154,7 @@ tracker_sparql_statement_bind_string
 tracker_sparql_statement_bind_boolean
 tracker_sparql_statement_clear_bindings
 tracker_sparql_statement_get_connection
-tracker_sparql_statement_set_connection
 tracker_sparql_statement_get_sparql
-tracker_sparql_statement_set_sparql
 <SUBSECTION Standard>
 TrackerSparqlStatementClass
 TRACKER_SPARQL_STATEMENT
@@ -214,12 +213,9 @@ TrackerNotifier
 TrackerNotifierClass
 TrackerNotifierEventType
 TrackerNotifierEvent
-tracker_notifier_new
 tracker_notifier_event_get_event_type
 tracker_notifier_event_get_id
-tracker_notifier_event_get_type
 tracker_notifier_event_get_urn
-tracker_notifier_event_get_location
 <SUBSECTION Standard>
 TRACKER_IS_NOTIFIER
 TRACKER_IS_NOTIFIER_CLASS
diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c
index efc3135e4..043e691e8 100644
--- a/src/libtracker-sparql/tracker-connection.c
+++ b/src/libtracker-sparql/tracker-connection.c
@@ -43,16 +43,18 @@ tracker_sparql_connection_class_init (TrackerSparqlConnectionClass *klass)
  * tracker_sparql_connection_new:
  * @flags: values from #TrackerSparqlConnectionFlags
  * @store: the directory that contains the database, as a #GFile
- * @ontology: the directory that contains the database schemas, as a #GFile
- * @cancellable: a #GCancellable, or %NULL
+ * @ontology: (nullable): the directory that contains the database schemas as
+ *                        a #GFile, or %NULL to use the default schemas.
+ * @cancellable: (nullable): a #GCancellable, or %NULL
+ * @error: pointer to a #GError
  *
  * Opens a database. Use this for data managed by the current process.
  *
  * To connect to databases managed by other processes, use
  * tracker_sparql_connection_bus_new().
  *
- * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
- * object when no longer used.
+ * Returns: (transfer full): a new #TrackerSparqlConnection. Call
+ * g_object_unref() on the object when no longer used.
  *
  * Since: 3.0
  */
@@ -61,8 +63,9 @@ tracker_sparql_connection_class_init (TrackerSparqlConnectionClass *klass)
  * tracker_sparql_connection_new_async:
  * @flags: values from #TrackerSparqlConnectionFlags
  * @store: the directory that contains the database, as a #GFile
- * @ontology: the directory that contains the database schemas, as a #GFile
- * @cancellable: a #GCancellable, or %NULL
+ * @ontology: (nullable): the directory that contains the database schemas as
+ *                        a #GFile, or %NULL to use the default schemas.
+ * @cancellable: (nullable): a #GCancellable, or %NULL
  * @callback: the #GAsyncReadyCallback called when the operation completes
  * @user_data: data passed to @callback
  *
@@ -83,14 +86,15 @@ tracker_sparql_connection_class_init (TrackerSparqlConnectionClass *klass)
 
 /**
  * tracker_sparql_connection_bus_new:
- * @service: The name of the D-Bus service to connect to.
- * @object_path: The path to the object, or %NULL to use the default.
- * @conn: The #GDBusConnection to use, or %NULL to use the session bus.
+ * @service_name: The name of the D-Bus service to connect to.
+ * @object_path: (nullable): The path to the object, or %NULL to use the default.
+ * @dbus_connection: (nullable): The #GDBusConnection to use, or %NULL to use the session bus.
+ * @error: pointer to a #GError
  *
  * Connects to a database owned by another process on the
  * local machine.
  *
- * Returns: a new #TrackerSparqlConnection. Call g_object_unref() on the
+ * Returns: (transfer full): a new #TrackerSparqlConnection. Call g_object_unref() on the
  * object when no longer used.
  *
  * Since: 3.0
@@ -103,8 +107,8 @@ tracker_sparql_connection_class_init (TrackerSparqlConnectionClass *klass)
  * 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.
  *
- * Returns: a new remote #TrackerSparqlConnection. Call g_object_unref() on the
- * object when no longer used.
+ * Returns: (transfer full): a new remote #TrackerSparqlConnection. Call
+ * g_object_unref() on the object when no longer used.
  *
  * Since: 1.12
  */
@@ -544,7 +548,7 @@ tracker_sparql_connection_create_notifier (TrackerSparqlConnection *connection,
 
 /**
  * tracker_sparql_connection_close:
- * @self: a #TrackerSparqlConnection
+ * @connection: a #TrackerSparqlConnection
  *
  * Closes a SPARQL connection. No other API calls than g_object_unref()
  * should happen after this call.
diff --git a/src/libtracker-sparql/tracker-endpoint-dbus.c b/src/libtracker-sparql/tracker-endpoint-dbus.c
index 7da17fa67..c9ef380b0 100644
--- a/src/libtracker-sparql/tracker-endpoint-dbus.c
+++ b/src/libtracker-sparql/tracker-endpoint-dbus.c
@@ -637,6 +637,19 @@ tracker_endpoint_dbus_init (TrackerEndpointDBus *endpoint)
 {
 }
 
+/**
+ * tracker_endpoint_dbus_new:
+ * @sparql_connection: a #TrackerSparqlConnection
+ * @dbus_connection: a #GDBusConnection
+ * @object_path: (nullable): the object path to use, or %NULL for the default
+ * @cancellable: (nullable): a #GCancellable, or %NULL
+ * @error: pointer to a #GError
+ *
+ * Registers a Tracker endpoint object at @object_path on @dbus_connection.
+ * The default object path is "/org/freedesktop/Tracker1/Endpoint".
+ *
+ * Returns: (transfer full): a #TrackerEndpointDBus object.
+ */
 TrackerEndpointDBus *
 tracker_endpoint_dbus_new (TrackerSparqlConnection  *sparql_connection,
                            GDBusConnection          *dbus_connection,
diff --git a/src/libtracker-sparql/tracker-notifier.h b/src/libtracker-sparql/tracker-notifier.h
index dbcd09fba..93acb8d03 100644
--- a/src/libtracker-sparql/tracker-notifier.h
+++ b/src/libtracker-sparql/tracker-notifier.h
@@ -75,8 +75,6 @@ TrackerNotifierEventType
 TRACKER_AVAILABLE_IN_ALL
 gint64        tracker_notifier_event_get_id         (TrackerNotifierEvent *event);
 TRACKER_AVAILABLE_IN_ALL
-const gchar * tracker_notifier_event_get_type       (TrackerNotifierEvent *event);
-TRACKER_AVAILABLE_IN_ALL
 const gchar * tracker_notifier_event_get_urn        (TrackerNotifierEvent *event);
 
 #endif /* __TRACKER_NOTIFIER_H__ */