lib: Improve documentation of _notmuch_message_create_for_message_id

[notmuch] / lib / message.cc

diff --git a/lib/message.cc b/lib/message.cc
index d0b7351e71796ad2e288a018cbc5ef00ff4fcb67..3f934265a73727feceb0f5dfa26bc70f55669dbe 100644 (file)
--- a/lib/message.cc
+++ b/lib/message.cc
@@ -193,14 +193,16 @@ _notmuch_message_create (const void *talloc_owner,
  *     There is already a document with message ID 'message_id' in the
  *     database. The returned message can be used to query/modify the
  *     document.
+ *
  *   NOTMUCH_PRIVATE_STATUS_NO_DOCUMENT_FOUND:
  *
  *     No document with 'message_id' exists in the database. The
  *     returned message contains a newly created document (not yet
  *     added to the database) and a document ID that is known not to
- *     exist in the database. The caller can modify the message, and a
- *     call to _notmuch_message_sync will add * the document to the
- *     database.
+ *     exist in the database.  This message is "blank"; that is, it
+ *     contains only a message ID and no other metadata. The caller
+ *     can modify the message, and a call to _notmuch_message_sync
+ *     will add the document to the database.
  *
  * If an error occurs, this function will return NULL and *status
  * will be set as appropriate. (The status pointer argument must
@@ -439,7 +441,7 @@ notmuch_message_get_header (notmuch_message_t *message, const char *header)
     if (message->message_file == NULL)
        return NULL;
 
-    return notmuch_message_file_get_header (message->message_file, header);
+    return _notmuch_message_file_get_header (message->message_file, header);
 }
 
 /* Return the message ID from the In-Reply-To header of 'message'.
@@ -898,13 +900,13 @@ notmuch_message_get_tags (notmuch_message_t *message)
 }
 
 const char *
-notmuch_message_get_author (notmuch_message_t *message)
+_notmuch_message_get_author (notmuch_message_t *message)
 {
     return message->author;
 }
 
 void
-notmuch_message_set_author (notmuch_message_t *message,
+_notmuch_message_set_author (notmuch_message_t *message,
                            const char *author)
 {
     if (message->author)
@@ -971,7 +973,7 @@ void
 _notmuch_message_close (notmuch_message_t *message)
 {
     if (message->message_file) {
-       notmuch_message_file_close (message->message_file);
+       _notmuch_message_file_close (message->message_file);
        message->message_file = NULL;
     }
 }
@@ -1032,6 +1034,8 @@ _notmuch_message_gen_terms (notmuch_message_t *message,
        /* Create a gap between this an the next terms so they don't
         * appear to be a phrase. */
        message->termpos = term_gen->get_termpos () + 100;
+
+       _notmuch_message_invalidate_metadata (message, prefix_name);
     }
 
     term_gen->set_termpos (message->termpos);