unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
From: Austin Clements <amdragon@MIT.EDU>
To: notmuch@notmuchmail.org
Subject: [PATCH v3 13/13] lib: Update doc of notmuch_database_{needs_upgrade, upgrade}
Date: Thu, 31 Jul 2014 22:10:03 -0400	[thread overview]
Message-ID: <1406859003-11561-14-git-send-email-amdragon@mit.edu> (raw)
In-Reply-To: <1406859003-11561-1-git-send-email-amdragon@mit.edu>

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 | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/lib/notmuch.h b/lib/notmuch.h
index cbf2ba5..d771eb2 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -352,22 +352,25 @@ unsigned int
 notmuch_database_get_version (notmuch_database_t *database);
 
 /**
- * Does this database need to be upgraded before writing to it?
+ * Is the database behind the latest supported 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.
  */
 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

  parent reply	other threads:[~2014-08-01  2:11 UTC|newest]

Thread overview: 28+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2014-08-01  2:09 [PATCH v3 00/13] Implement and use database "features" Austin Clements
2014-08-01  2:09 ` [PATCH v3 01/13] test: Include generated dependencies for test sources Austin Clements
2014-08-01  2:09 ` [PATCH v3 02/13] util: Const version of strtok_len Austin Clements
2014-08-06 13:43   ` David Bremner
2014-08-01  2:09 ` [PATCH v3 03/13] new: Don't report version after upgrade Austin Clements
2014-08-23 15:39   ` Jani Nikula
2014-08-23 22:59     ` Austin Clements
2014-08-24 12:56       ` Jani Nikula
2014-08-01  2:09 ` [PATCH v3 04/13] lib: Database version 3: Introduce fine-grained "features" Austin Clements
2014-08-23 16:02   ` Jani Nikula
2014-08-24  0:57     ` Austin Clements
2014-08-23 22:21   ` David Bremner
2014-08-24  0:58     ` Austin Clements
2014-08-24  3:58       ` David Bremner
2014-08-24 22:16         ` Austin Clements
2014-08-24 23:03           ` David Bremner
2014-08-01  2:09 ` [PATCH v3 05/13] test: Tool to build DB with specific version and features Austin Clements
2014-08-23 16:03   ` Jani Nikula
2014-08-01  2:09 ` [PATCH v3 06/13] test: Tests for future version and unknown feature handling Austin Clements
2014-08-01  2:09 ` [PATCH v3 07/13] lib: Simplify upgrade code using a transaction Austin Clements
2014-08-01  2:09 ` [PATCH v3 08/13] lib: Use database features to drive upgrade Austin Clements
2014-08-01  2:09 ` [PATCH v3 09/13] lib: Reorganize upgrade around document types Austin Clements
2014-08-01  2:10 ` [PATCH v3 10/13] lib: Report progress for combined upgrade operation Austin Clements
2014-08-01  2:10 ` [PATCH v3 11/13] lib: Support empty header values in database Austin Clements
2014-08-01  2:10 ` [PATCH v3 12/13] lib: Return an error from operations that require an upgrade Austin Clements
2014-08-01  2:10 ` Austin Clements [this message]
2014-08-07 21:55 ` [PATCH v3 00/13] Implement and use database "features" Tomi Ollila
2014-08-08 18:18   ` Austin Clements

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://notmuchmail.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=1406859003-11561-14-git-send-email-amdragon@mit.edu \
    --to=amdragon@mit.edu \
    --cc=notmuch@notmuchmail.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://yhetil.org/notmuch.git/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).