MIME-Version: 1.0
In-Reply-To: <1383347716-5375-1-git-send-email-david@tethera.net>
References:
 <2a58adbdc1257f16579692544b4bcbadca3d3045.1383315568.git.jani@nikula.org>
	<1383347716-5375-1-git-send-email-david@tethera.net>
Date: Sat, 2 Nov 2013 01:19:58 +0200
Message-ID:
 <CAB+hUn8+PB+Y3C1bZediJCL4DvPx+shyCyCndaFEnxOSHHi9sA@mail.gmail.com>
Subject: Re: [PATCH] lib: update documentation of callback functions for
	database_compact and database_upgrade.
From: Jani Nikula <jani@nikula.org>
To: David Bremner <david@tethera.net>
Content-Type: multipart/alternative; boundary=047d7bacba9a0f6fd804ea25ce96
Cc: Notmuch Mail <notmuch@notmuchmail.org>, David Bremner <bremner@debian.org>
Precedence: list

--047d7bacba9a0f6fd804ea25ce96
Content-Type: text/plain; charset=UTF-8

The point was, we can do this *now* without soname bumps, because we
haven't released this yet.
 On Nov 2, 2013 1:16 AM, <david@tethera.net> wrote:

> 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
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch
>

--047d7bacba9a0f6fd804ea25ce96
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<p dir=3D"ltr">The point was, we can do this *now* without soname bumps, be=
cause we haven&#39;t released this yet.<br>
</p>
<div class=3D"gmail_quote">On Nov 2, 2013 1:16 AM,  &lt;<a href=3D"mailto:d=
avid@tethera.net">david@tethera.net</a>&gt; wrote:<br type=3D"attribution">=
<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p=
x #ccc solid;padding-left:1ex">
From: David Bremner &lt;<a href=3D"mailto:bremner@debian.org">bremner@debia=
n.org</a>&gt;<br>
<br>
Compact was missing callback documentation entirely, and upgrade did not di=
scuss the<br>
closure parameter.<br>
---<br>
This patch depends on<br>
<br>
=C2=A0 =C2=A0 =C2=A0<a href=3D"mailto:id%3A2a58adbdc1257f16579692544b4bcbad=
ca3d3045.1383315568.git.jani@nikula.org">id:2a58adbdc1257f16579692544b4bcba=
dca3d3045.1383315568.git.jani@nikula.org</a><br>
<br>
BTW, I didn&#39;t completely understand the remark about SONAME bumps;<br>
since we&#39;re providing new symbols, it doesn&#39;t really matter what th=
e<br>
signature is?<br>
<br>
=C2=A0lib/notmuch.h | 6 +++++-<br>
=C2=A01 file changed, 5 insertions(+), 1 deletion(-)<br>
<br>
diff --git a/lib/notmuch.h b/lib/notmuch.h<br>
index cd301a4..82fd599 100644<br>
--- a/lib/notmuch.h<br>
+++ b/lib/notmuch.h<br>
@@ -227,6 +227,9 @@ typedef void (*notmuch_compact_status_cb_t)(const char =
*message, void *closure);<br>
=C2=A0 * The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE<=
br>
=C2=A0 * during the compaction process to ensure no writes are made.<br>
=C2=A0 *<br>
+ * If the optional callback function &#39;status_cb&#39; is non-NULL, it w=
ill<br>
+ * be called with diagnostic and informational messages. The argument<br>
+ * &#39;closure&#39; is passed verbatim to any callback invoked.<br>
=C2=A0 */<br>
=C2=A0notmuch_status_t<br>
=C2=A0notmuch_database_compact (const char* path,<br>
@@ -270,7 +273,8 @@ notmuch_database_needs_upgrade (notmuch_database_t *dat=
abase);<br>
=C2=A0 * provide progress indication to the user. If non-NULL it will be<br=
>
=C2=A0 * called periodically with &#39;progress&#39; as a floating-point va=
lue in<br>
=C2=A0 * the range of [0.0 .. 1.0] indicating the progress made so far in<b=
r>
- * the upgrade process.<br>
+ * the upgrade process. =C2=A0The argument &#39;closure&#39; is passed ver=
batim to<br>
+ * any callback invoked.<br>
=C2=A0 */<br>
=C2=A0notmuch_status_t<br>
=C2=A0notmuch_database_upgrade (notmuch_database_t *database,<br>
--<br>
1.8.4.rc3<br>
<br>
_______________________________________________<br>
notmuch mailing list<br>
<a href=3D"mailto:notmuch@notmuchmail.org">notmuch@notmuchmail.org</a><br>
<a href=3D"http://notmuchmail.org/mailman/listinfo/notmuch" target=3D"_blan=
k">http://notmuchmail.org/mailman/listinfo/notmuch</a><br>
</blockquote></div>

--047d7bacba9a0f6fd804ea25ce96--