[PATCH 1/3] lib: clarify description of notmuch_database_add_message
Daniel Kahn Gillmor
dkg at fifthhorseman.net
Tue Aug 8 22:47:29 PDT 2017
Since we're accumulating the index when we add a new file to the
message, the semantics have slightly changed. This tries to align the
documentation with the actual functionality.
---
lib/notmuch.h | 11 +++++++----
1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/lib/notmuch.h b/lib/notmuch.h
index f78b3473..02586a91 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -542,8 +542,10 @@ notmuch_database_get_directory (notmuch_database_t *database,
notmuch_directory_t **directory);
/**
- * Add a new message to the given notmuch database or associate an
- * additional filename with an existing message.
+ * Add a message file to a database, indexing it for retrieval by
+ * future searches. If a message already exists with the same message
+ * ID as the specified file, their indexes will be merged, and this
+ * new filename will also be associated with the existing message.
*
* Here, 'filename' should be a path relative to the path of
* 'database' (see notmuch_database_get_path), or else should be an
@@ -556,8 +558,9 @@ notmuch_database_get_directory (notmuch_database_t *database,
* entire contents of the file.
*
* If another message with the same message ID already exists in the
- * database, rather than creating a new message, this adds 'filename'
- * to the list of the filenames for the existing message.
+ * database, rather than creating a new message, this adds the search
+ * terms from the identified file to the existing message's index, and
+ * adds 'filename' to the list of filenames known for the message.
*
* If 'message' is not NULL, then, on successful return
* (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message'
--
2.13.2
More information about the notmuch
mailing list