[tracker/wip/carlosg/doc-improvements: 3/6] libtracker-sparql: Add API docs on update_blank() return value format
- From: Carlos Garnacho <carlosg src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [tracker/wip/carlosg/doc-improvements: 3/6] libtracker-sparql: Add API docs on update_blank() return value format
- Date: Thu, 16 Sep 2021 22:05:59 +0000 (UTC)
commit 708e98e2c0400fef2efabf34b4b230f3e2afede0
Author: Carlos Garnacho <carlosg gnome org>
Date: Wed Sep 15 21:30:30 2021 +0200
libtracker-sparql: Add API docs on update_blank() return value format
We explain this (somewhat) in the examples page, which feels oddly out
of place. Borrow some of these docs to document the functions themselves.
src/libtracker-sparql/tracker-connection.c | 15 +++++++++++++--
1 file changed, 13 insertions(+), 2 deletions(-)
---
diff --git a/src/libtracker-sparql/tracker-connection.c b/src/libtracker-sparql/tracker-connection.c
index adc9b3d92..fc583a3f2 100644
--- a/src/libtracker-sparql/tracker-connection.c
+++ b/src/libtracker-sparql/tracker-connection.c
@@ -471,6 +471,13 @@ tracker_sparql_connection_update_array_finish (TrackerSparqlConnection *connect
* its parts correctly escaped using tracker_sparql_escape_string(),
* otherwise SPARQL injection is possible.
*
+ * The format string of the `GVariant` is `aaa{ss}` (an array of an array
+ * of dictionaries). The first array represents each INSERT that may exist in
+ * the SPARQL string. The second array represents each new node for a given
+ * 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.
+ *
* Returns: a #GVariant with the generated URNs, which should be freed with
* g_variant_unref() when no longer used.
*/
@@ -500,7 +507,9 @@ tracker_sparql_connection_update_blank (TrackerSparqlConnection *connection,
* asynchronous operation is finished.
* @user_data: user-defined data to be passed to @callback
*
- * Executes asynchronously a SPARQL update.
+ * 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().
*/
void
tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connection,
@@ -527,7 +536,9 @@ tracker_sparql_connection_update_blank_async (TrackerSparqlConnection *connectio
* @error: #GError for error reporting.
*
* Finishes the asynchronous SPARQL update operation, and returns
- * the URNs of the generated nodes, if any.
+ * the URNs of the generated nodes, if any. See the
+ * tracker_sparql_connection_update_blank() documentation for the interpretation
+ * of the returned #GVariant.
*
* Returns: a #GVariant with the generated URNs, which should be freed with
* g_variant_unref() when no longer used.
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]