Document that indexing does not sync flags

This quirk is somewhat unexpected, since flags won't be updated as
expected, but subsequence calls to notmuch-new(1) won't update the
index, giving an impression of it being stale.

diff --git a/lib/notmuch.h b/lib/notmuch.h
index ee11400a417306fe5701b978e21e5955c2d3051c..dc40c88640568ffd5e73bd3b2c14dae20fee9c1e 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -807,6 +807,12 @@ notmuch_database_get_directory (notmuch_database_t *database,
  * notmuch_message_destroy when done with the message. On any failure
  * '*message' will be set to NULL.
  *
+ * Note that this does not synchronise Maildir flags to notmuch flags,
+ * regardless of the value of maildir.synchronize_flags. Future calls to
+ * notmuch-new(1) will also not synchronise flags, since the file's current
+ * mtime shall be recorded as indexed. If flags ought to be synchronised,
+ * explicitly call notmuch_message_maildir_flags_to_tags.
+ *
  * Return value:
  *
  * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.