X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=9a19699956dc0a9178d6f0fc39110e0ee7acf92d;hp=bae48a6589f62868331a3c7d7d70715d12ea706c;hb=f6cb896bc4c0bafca1acd5ac3fb45169cd893e29;hpb=8cbb5114a20c1217f23977fd5edca99a0b7a2955

diff --git a/lib/notmuch.h b/lib/notmuch.h
index bae48a65..9a196999 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -219,6 +219,8 @@ notmuch_database_upgrade (notmuch_database_t *database,
  * Here, 'path' should be a path relative to the path of 'database'
  * (see notmuch_database_get_path), or else should be an absolute path
  * with initial components that match the path of 'database'.
+ *
+ * Can return NULL if a Xapian exception occurs.
  */
 notmuch_directory_t *
 notmuch_database_get_directory (notmuch_database_t *database,
@@ -246,6 +248,9 @@ notmuch_database_get_directory (notmuch_database_t *database,
  *
  * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.
  *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
+ *	message not added.
+ *
  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message
  *	ID as another message already in the database. The new
  *	filename was successfully added to the message in the database
@@ -280,6 +285,9 @@ notmuch_database_add_message (notmuch_database_t *database,
  * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the
  *	message was removed from the database.
  *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
+ *	message not removed.
+ *
  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but
  *	the message persists in the database with at least one other
  *	filename.
@@ -297,8 +305,11 @@ notmuch_database_remove_message (notmuch_database_t *database,
  * a new notmuch_message_t object is returned. The caller should call
  * notmuch_message_destroy when done with the message.
  *
- * If no message is found with the given message_id or if an
- * out-of-memory situation occurs, this function returns NULL.
+ * This function returns NULL in the following situations:
+ *
+ *	* No message is found with the given message_id
+ *	* An out-of-memory situation occurs
+ *	* A Xapian exception occurs
  */
 notmuch_message_t *
 notmuch_database_find_message (notmuch_database_t *database,
@@ -389,6 +400,8 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
  * notmuch_threads_t object. (For consistency, we do provide a
  * notmuch_threads_destroy function, but there's no good reason
  * to call it if the query is about to be destroyed).
+ *
+ * If a Xapian exception occurs this function will return NULL.
  */
 notmuch_threads_t *
 notmuch_query_search_threads (notmuch_query_t *query);
@@ -428,6 +441,8 @@ notmuch_query_search_threads (notmuch_query_t *query);
  * notmuch_messages_t object. (For consistency, we do provide a
  * notmuch_messages_destroy function, but there's no good
  * reason to call it if the query is about to be destroyed).
+ *
+ * If a Xapian exception occurs this function will return NULL.
  */
 notmuch_messages_t *
 notmuch_query_search_messages (notmuch_query_t *query);
@@ -495,6 +510,9 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
  *
  * This function performs a search and returns Xapian's best
  * guess as to number of matching messages.
+ *
+ * If a Xapian exception occurs, this function may return 0 (after
+ * printing a message).
  */
 unsigned
 notmuch_query_count_messages (notmuch_query_t *query);