[tracker/wip/carlosg/doc-improvements: 3/6] libtracker-sparql: Add API docs on update_blank() return value format

[Carlos Garnacho <carlosg src gnome org>]

commit 9acffe4919ee11ba390c27a44f508807cbc40910
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.