diff options
| author |  Austin Clements <amdragon@mit.edu> | 2014-08-25 13:26:09 -0400 |
|---|---|---|
| committer |  David Bremner <david@tethera.net> | 2014-08-30 11:42:07 -0700 |
| commit | 658a00e7c809cc4e3076aab28e105d3761086451 (patch) | |
| tree | e2a2cb9aeff08bc0de085cff62b460be0d75de94 | |
| parent | ec573cd54fb3ea98f37a3c3612b00fb16e34578b (diff) | |
lib: Update doc of notmuch_database_{needs_upgrade,upgrade}
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!).
| -rw-r--r-- | lib/notmuch.h | 23 |
1 files changed, 14 insertions, 9 deletions
diff --git a/lib/notmuch.h b/lib/notmuch.h index cbf2ba5c..21a52252 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 |