lib: Fix internal documentation of _notmuch_database_link_message

[notmuch] / lib / database.cc

diff --git a/lib/database.cc b/lib/database.cc
index 9cd46d4fcb7ca3c85b6d7be8340cc6b60a1a2c56..2511caec7a8623e36c20ba92d32613f28f662ae7 100644 (file)
--- a/lib/database.cc
+++ b/lib/database.cc
@@ -1152,36 +1152,41 @@ _resolve_message_id_to_thread_id (notmuch_database_t *notmuch,
                                  const char *message_id)
 {
     notmuch_message_t *message;
-    const char *ret = NULL;
+    string thread_id_string;
+    const char *thread_id;
+    char *metadata_key;
+    Xapian::WritableDatabase *db;
 
     message = notmuch_database_find_message (notmuch, message_id);
-    /* If we haven't seen that message yet then check if we have already
-     * generated a dummy id for it and stored it in the metadata.
-     * If not then we generate a new thread id.
-     * This ensures that we can thread messages even when we haven't received
-     * the root (yet?)
-     */
-    if (message == NULL) {
-        Xapian::WritableDatabase *db = static_cast <Xapian::WritableDatabase *> (notmuch->xapian_db);
-        char * metadata_key = _get_metadata_thread_id_key (ctx, message_id);
-        string thread_id = notmuch->xapian_db->get_metadata(metadata_key);
-        if (thread_id.empty()) {
-            ret = _notmuch_database_generate_thread_id(notmuch);
-            db->set_metadata(metadata_key, ret);
-        } else {
-            ret = thread_id.c_str();
-        }
-        talloc_free (metadata_key);
-        goto DONE;
-    }
 
-    ret = talloc_steal (ctx, notmuch_message_get_thread_id (message));
+    if (message) {
+       thread_id = talloc_steal (ctx, notmuch_message_get_thread_id (message));
 
-  DONE:
-    if (message)
        notmuch_message_destroy (message);
 
-    return ret;
+       return thread_id;
+    }
+
+    /* Message has not been seen yet.
+     *
+     * We may have seen a reference to it already, in which case, we
+     * can return the thread ID stored in the metadata. Otherwise, we
+     * generate a new thread ID and store it there.
+     */
+    db = static_cast <Xapian::WritableDatabase *> (notmuch->xapian_db);
+    metadata_key = _get_metadata_thread_id_key (ctx, message_id);
+    thread_id_string = notmuch->xapian_db->get_metadata (metadata_key);
+
+    if (thread_id_string.empty()) {
+       thread_id = _notmuch_database_generate_thread_id (notmuch);
+       db->set_metadata (metadata_key, thread_id);
+    } else {
+       thread_id = thread_id_string.c_str();
+    }
+
+    talloc_free (metadata_key);
+
+    return thread_id;
 }
 
 static notmuch_status_t
@@ -1343,18 +1348,27 @@ _notmuch_database_link_message_to_children (notmuch_database_t *notmuch,
 /* Given a (mostly empty) 'message' and its corresponding
  * 'message_file' link it to existing threads in the database.
  *
- * We first look at 'message_file' and its link-relevant headers
- * (References and In-Reply-To) for message IDs. We also look in the
- * database for existing message that reference 'message'. In either
- * case, we will assign to the current message the first thread_id
+ * The first check is in the metadata of the database to see if we
+ * have pre-allocated a thread_id in advance for this message, (which
+ * would have happened if a message was previously added that
+ * referenced this one).
+ *
+ * Second, we look at 'message_file' and its link-relevant headers
+ * (References and In-Reply-To) for message IDs.
+ *
+ * Finally, we look in the database for existing message that
+ * reference 'message'.
+ *
+ * In all cases, we assign to the current message the first thread_id
  * found (through either parent or child). We will also merge any
  * existing, distinct threads where this message belongs to both,
  * (which is not uncommon when mesages are processed out of order).
  *
- * Finally, if not thread ID has been found through parent or child,
- * we call _notmuch_message_generate_thread_id to generate a new
- * generates a new thread ID if the message doesn't connect to any
- * existing threads.
+ * Finally, if no thread ID has been found through parent or child, we
+ * call _notmuch_message_generate_thread_id to generate a new thread
+ * ID. This should only happen for new, top-level messages, (no
+ * References or In-Reply-To header in this message, and no previously
+ * added message refers to this message).
  */
 static notmuch_status_t
 _notmuch_database_link_message (notmuch_database_t *notmuch,