From: Austin Clements <amdragon@mit.edu>
To: notmuch@notmuchmail.org
Subject: [PATCH v4 11/11] lib: Update doc of notmuch_database_{needs_upgrade,
	upgrade}
Date: Mon, 25 Aug 2014 13:26:09 -0400
Message-Id: <1408987569-14146-12-git-send-email-amdragon@mit.edu>
In-Reply-To: <1408987569-14146-1-git-send-email-amdragon@mit.edu>
References: <1408987569-14146-1-git-send-email-amdragon@mit.edu>
Precedence: list

Clients are no longer required to call these functions after opening a
database in read/write mode (which is good, because almost none of
them do!).
---
 lib/notmuch.h | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/lib/notmuch.h b/lib/notmuch.h
index cbf2ba5..21a5225 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -352,22 +352,27 @@ unsigned int
 notmuch_database_get_version (notmuch_database_t *database);
 
 /**
- * Does this database need to be upgraded before writing to it?
+ * Can the database be upgraded to a newer database version?
  *
- * If this function returns TRUE then no functions that modify the
- * database (notmuch_database_add_message, notmuch_message_add_tag,
- * notmuch_directory_set_mtime, etc.) will work unless the function
- * notmuch_database_upgrade is called successfully first.
+ * If this function returns TRUE, then the caller may call
+ * notmuch_database_upgrade to upgrade the database.  If the caller
+ * does not upgrade an out-of-date database, then some functions may
+ * fail with NOTMUCH_STATUS_UPGRADE_REQUIRED.  This always returns
+ * FALSE for a read-only database because there's no way to upgrade a
+ * read-only database.
  */
 notmuch_bool_t
 notmuch_database_needs_upgrade (notmuch_database_t *database);
 
 /**
- * Upgrade the current database.
+ * Upgrade the current database to the latest supported version.
  *
- * After opening a database in read-write mode, the client should
- * check if an upgrade is needed (notmuch_database_needs_upgrade) and
- * if so, upgrade with this function before making any modifications.
+ * This ensures that all current notmuch functionality will be
+ * available on the database.  After opening a database in read-write
+ * mode, it is recommended that clients check if an upgrade is needed
+ * (notmuch_database_needs_upgrade) and if so, upgrade with this
+ * function before making any modifications.  If
+ * notmuch_database_needs_upgrade returns FALSE, this will be a no-op.
  *
  * The optional progress_notify callback can be used by the caller to
  * provide progress indication to the user. If non-NULL it will be
-- 
2.0.0