From: david@tethera.net
To: notmuch@notmuchmail.org
Subject: [PATCH] lib: update documentation of callback functions for
	database_compact and database_upgrade.
Date: Fri,  1 Nov 2013 20:15:16 -0300
Message-Id: <1383347716-5375-1-git-send-email-david@tethera.net>
In-Reply-To:
 <2a58adbdc1257f16579692544b4bcbadca3d3045.1383315568.git.jani@nikula.org>
References:
 <2a58adbdc1257f16579692544b4bcbadca3d3045.1383315568.git.jani@nikula.org>
Cc: David Bremner <bremner@debian.org>
Precedence: list

From: David Bremner <bremner@debian.org>

Compact was missing callback documentation entirely, and upgrade did not discuss the
closure parameter.
---
This patch depends on 
     
     id:2a58adbdc1257f16579692544b4bcbadca3d3045.1383315568.git.jani@nikula.org

BTW, I didn't completely understand the remark about SONAME bumps;
since we're providing new symbols, it doesn't really matter what the
signature is?

 lib/notmuch.h | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/lib/notmuch.h b/lib/notmuch.h
index cd301a4..82fd599 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -227,6 +227,9 @@ typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure);
  * The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE
  * during the compaction process to ensure no writes are made.
  *
+ * If the optional callback function 'status_cb' is non-NULL, it will
+ * be called with diagnostic and informational messages. The argument
+ * 'closure' is passed verbatim to any callback invoked.
  */
 notmuch_status_t
 notmuch_database_compact (const char* path,
@@ -270,7 +273,8 @@ notmuch_database_needs_upgrade (notmuch_database_t *database);
  * provide progress indication to the user. If non-NULL it will be
  * called periodically with 'progress' as a floating-point value in
  * the range of [0.0 .. 1.0] indicating the progress made so far in
- * the upgrade process.
+ * the upgrade process.  The argument 'closure' is passed verbatim to
+ * any callback invoked.
  */
 notmuch_status_t
 notmuch_database_upgrade (notmuch_database_t *database,
-- 
1.8.4.rc3