lib: Return an error from operations that require an upgrade

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 02604c5645c3c881ec490c6ed82a9a02601873d7..cbf2ba5cd46d192b046b3c651f63df4d16d61fa8 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -159,6 +159,10 @@ typedef enum _notmuch_status {
      * The operation is not supported.
      */
     NOTMUCH_STATUS_UNSUPPORTED_OPERATION,
+    /**
+     * The operation requires a database upgrade.
+     */
+    NOTMUCH_STATUS_UPGRADE_REQUIRED,
     /**
      * Not an actual status value. Just a way to find out how many
      * valid status values there are.
@@ -287,8 +291,16 @@ notmuch_database_open (const char *path,
  *
  * notmuch_database_close can be called multiple times.  Later calls
  * have no effect.
+ *
+ * Return value:
+ *
+ * NOTMUCH_STATUS_SUCCESS: Successfully closed the database.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; the
+ *     database has been closed but there are no guarantees the
+ *     changes to the database, if any, have been flushed to disk.
  */
-void
+notmuch_status_t
 notmuch_database_close (notmuch_database_t *database);
 
 /**
@@ -317,8 +329,11 @@ notmuch_database_compact (const char* path,
 /**
  * Destroy the notmuch database, closing it if necessary and freeing
  * all associated resources.
+ *
+ * Return value as in notmuch_database_close if the database was open;
+ * notmuch_database_destroy itself has no failure modes.
  */
-void
+notmuch_status_t
 notmuch_database_destroy (notmuch_database_t *database);
 
 /**
@@ -415,6 +430,10 @@ notmuch_database_end_atomic (notmuch_database_t *notmuch);
  * If this directory object does not exist in the database, this
  * returns NOTMUCH_STATUS_SUCCESS and sets *directory to NULL.
  *
+ * Otherwise the returned directory object is owned by the database
+ * and as such, will only be valid until notmuch_database_destroy is
+ * called.
+ *
  * Return value:
  *
  * NOTMUCH_STATUS_SUCCESS: Successfully retrieved directory.
@@ -423,6 +442,9 @@ notmuch_database_end_atomic (notmuch_database_t *notmuch);
  *
  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
  *     directory not retrieved.
+ *
+ * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
+ *     database to use this function.
  */
 notmuch_status_t
 notmuch_database_get_directory (notmuch_database_t *database,
@@ -475,6 +497,9 @@ notmuch_database_get_directory (notmuch_database_t *database,
  *
  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
  *     mode so no message can be added.
+ *
+ * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
+ *     database to use this function.
  */
 notmuch_status_t
 notmuch_database_add_message (notmuch_database_t *database,
@@ -505,6 +530,9 @@ notmuch_database_add_message (notmuch_database_t *database,
  *
  * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
  *     mode so no message can be removed.
+ *
+ * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
+ *     database to use this function.
  */
 notmuch_status_t
 notmuch_database_remove_message (notmuch_database_t *database,
@@ -560,6 +588,9 @@ notmuch_database_find_message (notmuch_database_t *database,
  * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating the message object
  *
  * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
+ *
+ * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
+ *     database to use this function.
  */
 notmuch_status_t
 notmuch_database_find_message_by_filename (notmuch_database_t *notmuch,
@@ -802,6 +833,8 @@ notmuch_query_destroy (notmuch_query_t *query);
  * valid object. Whereas when this function returns FALSE,
  * notmuch_threads_get will return NULL.
  *
+ * If passed a NULL pointer, this function returns FALSE
+ *
  * See the documentation of notmuch_query_search_threads for example
  * code showing how to iterate over a notmuch_threads_t object.
  */
@@ -994,7 +1027,7 @@ notmuch_thread_get_newest_date (notmuch_thread_t *thread);
  *
  *     for (tags = notmuch_thread_get_tags (thread);
  *          notmuch_tags_valid (tags);
- *          notmuch_result_move_to_next (tags))
+ *          notmuch_tags_move_to_next (tags))
  *     {
  *         tag = notmuch_tags_get (tags);
  *         ....
@@ -1236,7 +1269,7 @@ notmuch_message_get_header (notmuch_message_t *message, const char *header);
  *
  *     for (tags = notmuch_message_get_tags (message);
  *          notmuch_tags_valid (tags);
- *          notmuch_result_move_to_next (tags))
+ *          notmuch_tags_move_to_next (tags))
  *     {
  *         tag = notmuch_tags_get (tags);
  *         ....