From: Carl Worth <cworth@cworth.org>
Date: Thu, 11 Nov 2010 12:51:55 +0000 (-0800)
Subject: lib: Be honest in the documentation of the maildir functions
X-Git-Tag: 0.5~19
X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=1ea0b8bfe164a0f7a3e750236b8aef9b5ab8917e;p=notmuch.git

lib: Be honest in the documentation of the maildir functions

I had originally hoped for better semantics, such as doing nothing in
non-maildir directories, and preserving unknown maildir flags that
happen to be present.

We could still do those things, of course, but for now, remove them
from the documentation since the implementation does not do these
things yet.
---

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 4295cbd0..ea12fe76 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -926,11 +926,8 @@ notmuch_message_remove_all_tags (notmuch_message_t *message);
  * For each flag that is not present, the opposite action (add/remove)
  * is performed for the corresponding tags.
  *
- * The only filenames examined for flags are filenames which appear to
- * be within a maildir directory, (the file must be in a directory
- * named "new" or "cur" and there must be a neighboring directory
- * named respectively "cur" or "new"). The flags are identified as
- * trailing components of the filename after a sequence of ":2,".
+ * Flags are identified as trailing components of the filename after a
+ * sequence of ":2,".
  *
  * If there are multiple filenames associated with this message, the
  * flag is considered present if it appears in one or more
@@ -950,14 +947,9 @@ notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);
  *
  * Specifically, for each filename corresponding to this message:
  *
- * If the filename is not in a maildir directory, do nothing.
- * (A maildir directory is determined as a directory named "new" or
- * "cur" with a neighboring directory named respectively "cur" or
- * "new".)
- *
- * If the filename is in a maildir directory, rename the file so that
- * its filename ends with the sequence ":2," followed by zero or more
- * of the following single-character flags (in ASCII order):
+ * Rename the file so that its filename ends with the sequence ":2,"
+ * followed by zero or more of the following single-character flags
+ * (in ASCII order):
  *
  *   'D' iff the message has the "draft" tag
  *   'F' iff the message has the "flagged" tag
@@ -965,8 +957,8 @@ notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);
  *   'R' iff the message has the "replied" tag
  *   'S' iff the message does not have the "unread" tag
  *
- * Any existing flags unmentioned in the list above are left
- * unaffected by the rename.
+ * Warning: any existing flags unmentioned in the list above will be
+ * removed by this renaming.
  *
  * Also, if this filename is in a directory named "new", rename it to
  * be within the neighboring directory named "cur".