From 0c1292051eef2a6f6a9a07630eadffe53186489e Mon Sep 17 00:00:00 2001 From: Austin Clements Date: Mon, 4 Aug 2014 21:29:16 -0400 Subject: 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. --- lib/message.cc | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'lib') diff --git a/lib/message.cc b/lib/message.cc index 90a01eb8..3f934265 100644 --- 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 -- cgit v1.2.3