lib: Treat NULL as a valid (and empty) notmuch_filenames_t iterator.

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 13efd5db90b77e1cb1b49473665715423842cde8..f3e1d28661414abaca44088dba4931c853027daa 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -57,6 +57,9 @@ typedef int notmuch_bool_t;
  * value. Instead we should map to things like DATABASE_LOCKED or
  * whatever.
  *
+ * NOTMUCH_STATUS_READONLY_DATABASE: An attempt was made to write to a
+ *     database opened in read-only mode.
+ *
  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
  *
  * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to read or
@@ -217,8 +220,8 @@ notmuch_database_get_directory (notmuch_database_t *database,
  * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.
  *
  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message
- *     ID as another message already in the database. Nothing added
- *     to the database.
+ *     ID as another message already in the database. The new filename
+ *     was successfully added to the message in the database.
  *
  * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the
  *     file, (such as permission denied, or file not found,
@@ -234,12 +237,21 @@ notmuch_database_add_message (notmuch_database_t *database,
 
 /* Remove a message from the given notmuch database.
  *
- * Note that the only this particular filename association is removed
- * from the database. If the same message (as determined by the
- * message ID) is still available via other filenames, then the
- * message will persist in the database for those filenames. When the
- * last filename is removed for a particular message, the database
- * content for that message will be entirely removed.
+ * Note that only this particular filename association is removed from
+ * the database. If the same message (as determined by the message ID)
+ * is still available via other filenames, then the message will
+ * persist in the database for those filenames. When the last filename
+ * is removed for a particular message, the database content for that
+ * message will be entirely removed.
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the
+ *     message was removed from the database.
+ *
+ * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but
+ *     the message persists in the database with at least one other
+ *     filename.
  */
 notmuch_status_t
 notmuch_database_remove_message (notmuch_database_t *database,
@@ -984,6 +996,9 @@ notmuch_directory_destroy (notmuch_directory_t *directory);
  * When this function returns TRUE, notmuch_filenames_get will return
  * a valid string. Whereas when this function returns FALSE,
  * notmuch_filenames_get will return NULL.
+ *
+ * It is acceptable to pass NULL for 'filenames', in which case this
+ * function will always return FALSE.
  */
 notmuch_bool_t
 notmuch_filenames_has_more (notmuch_filenames_t *filenames);
@@ -992,11 +1007,17 @@ notmuch_filenames_has_more (notmuch_filenames_t *filenames);
  *
  * Note: The returned string belongs to 'filenames' and has a lifetime
  * identical to it (and the directory to which it ultimately belongs).
+ *
+ * It is acceptable to pass NULL for 'filenames', in which case this
+ * function will always return NULL.
  */
 const char *
 notmuch_filenames_get (notmuch_filenames_t *filenames);
 
 /* Advance the 'filenames' iterator to the next filename.
+ *
+ * It is acceptable to pass NULL for 'filenames', in which case this
+ * function will do nothing.
  */
 void
 notmuch_filenames_advance (notmuch_filenames_t *filenames);
@@ -1006,6 +1027,9 @@ notmuch_filenames_advance (notmuch_filenames_t *filenames);
  * It's not strictly necessary to call this function. All memory from
  * the notmuch_filenames_t object will be reclaimed when the
  * containing directory object is destroyed.
+ *
+ * It is acceptable to pass NULL for 'filenames', in which case this
+ * function will do nothing.
  */
 void
 notmuch_filenames_destroy (notmuch_filenames_t *filenames);