lib: Improve documentation of _notmuch_message_create_for_message_id

Clarify the state of the returned message when
_notmuch_message_create_for_message_id returns
NOTMUCH_PRIVATE_STATUS_NO_DOCUMENT_FOUND.

diff --git a/lib/message.cc b/lib/message.cc
index 90a01eb8839b27ebc25d59b32cb02e7e282244b9..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