[nautilus/wip/antoniof/update-starred-uris] fixup! Documenting the code

[António Fernandes <antoniof src gnome org>]

commit 09cda77cff05cbd85cd12afe5a55f0c69abb8582
Author: António Fernandes <antoniojpfernandes gmail com>
Date:   Thu Sep 10 16:26:18 2020 +0000

    fixup! Documenting the code

 src/nautilus-tag-manager.c | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)
---
diff --git a/src/nautilus-tag-manager.c b/src/nautilus-tag-manager.c
index 58e2c5535..c9e0fccf7 100644
--- a/src/nautilus-tag-manager.c
+++ b/src/nautilus-tag-manager.c
@@ -706,7 +706,8 @@ update_moved_uris_callback (GObject      *object,
                             gpointer      user_data)
 {
     g_autoptr (GError) error = NULL;
-    GList *new_uris = user_data;
+    /* Taking ownership of new_uris and its elements */
+    GList/*<owned gchar*>*/ *new_uris = user_data;
 
     tracker_sparql_connection_update_finish (TRACKER_SPARQL_CONNECTION (object),
                                              result,
@@ -729,6 +730,15 @@ update_moved_uris_callback (GObject      *object,
     g_list_free_full (new_uris, (GDestroyNotify) g_free);
 }
 
+/**
+ * nautilus_tag_manager_update_moved_uris:
+ * @self: The tag manager singleton
+ * @src: The original location as a #GFile
+ * @dest: The new location as a #GFile
+ *  
+ * Checks whether the rename/move operation (@src to @dest) has modified 
+ * the URIs of any starred files, and updates the database accordingly.
+ */
 void
 nautilus_tag_manager_update_moved_uris (NautilusTagManager *self,
                                         GFile              *src,
@@ -737,8 +747,8 @@ nautilus_tag_manager_update_moved_uris (NautilusTagManager *self,
     GHashTableIter starred_iter;
     gchar *starred_uri;
     g_autoptr (GString) query = NULL;
-    g_autoptr (GList) old_uris = NULL;
-    g_autoptr (GList) new_uris = NULL;
+    g_autoptr (GList/*<unowned gchar*>*/) old_uris = NULL;
+    g_autoptr (GList/*<owned gchar*>*/) new_uris = NULL;
 
     if (!self->database_ok)
     {
@@ -756,6 +766,7 @@ nautilus_tag_manager_update_moved_uris (NautilusTagManager *self,
 
         if (g_file_equal (starred_location, src))
         {
+            /* The moved file/folder is starred */
             old_uris = g_list_prepend (old_uris, starred_uri);
             new_uris = g_list_prepend (new_uris, g_file_get_uri (dest));
             continue;
@@ -764,6 +775,7 @@ nautilus_tag_manager_update_moved_uris (NautilusTagManager *self,
         relative_path = g_file_get_relative_path (src, starred_location);
         if (relative_path != NULL)
         {
+            /* The starred file/folder is descendant of the moved/renamed directory */
             g_autoptr (GFile) new_location = NULL;
 
             new_location = g_file_resolve_relative_path (dest, relative_path);
@@ -775,6 +787,7 @@ nautilus_tag_manager_update_moved_uris (NautilusTagManager *self,
 
     if (new_uris == NULL)
     {
+        /* No starred files are affected by this move/rename */
         return;
     }