mu-store: cosmetics

2 files changed, 12 insertions, 5 deletions

diff --git a/lib/mu-store.cc b/lib/mu-store.cc
index 1e50f2b..81a3433 100644
--- a/lib/mu-store.cc
+++ b/lib/mu-store.cc
@@ -485,6 +485,12 @@ Store::remove_messages_by_term(std::span<const std::string> terms,
 	}
 
 	// Sort the IDs to remove to make Xapian tree traversal easier
+	//
+	// Note: Xapian contractually iterates over terms in ascending
+	// byte-lexicographic order, so it's only natural to suppose that its
+	// storage engines in general will get the best locality accessing terms
+	// in this order. We're allowed to delete in any order we want, so if we
+	// have to choose an order, this one seems reasonable.
 	std::ranges::sort(ids_to_remove);
 	for (Id id : ids_to_remove) {
 		nr_removed += priv_->remove_message_by_id_unlocked(id);
diff --git a/lib/mu-store.hh b/lib/mu-store.hh
index da0ec56..f2c82cf 100644
--- a/lib/mu-store.hh
+++ b/lib/mu-store.hh
@@ -266,14 +266,15 @@ public:
 	 * Remove a number if messages from the store. It will _not_ remove the
 	 * message from the file system.
 	 *
-	 * It's more efficient to use this function than to translate the terms to docids and then
-	 * call remove_messages() with the ids: this way, we can fuse the ID lookup and the
-	 * deletion, skip post-translation existence steps, and do far fewer Xapian
-	 * B-tree traversals.
+	 * It's more efficient to use this function than to translate the terms
+	 * to docids and then call remove_messages() with the ids: this way, we
+	 * can fuse the ID lookup and the deletion, skip post-translation
+	 * existence steps, and do far fewer Xapian B-tree traversals.
 	 *
-	 * @param ids vector with terms for the message
+	 * @param terms the terms for the message
 	 * @param progress_fn called occasionally to update number of removed messages;
 	 * called occasionally with cumulative number of messages removed so far
+	 *
 	 * @return number of messages removed overall
 	 */
 	size_t remove_messages_by_term(std::span<const std::string> terms,