lib: Document that absence of maildir flags can also remove/add tags

Previously the documentation of notmuch_message_maildir_flags_to_tags
suggested that the presence of a flag would cause tags to be added,
(or in the case of "unread", removed). But the case of absent maildir
flags was not explicitly described.

What we actually want, is that for supported flags, the absence of the
flag in all messages causes the corresponding tag to be removed,
(or in the case of "unread", added). So document that explicitly.

This is the case recently added to the test suite as a failing test,
(so we'll need to do bug fixing before the documentation is honest
here).

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 413b57095dd1bf78ef3dfc89cc41c4855d3a94c7..4295cbd09e0d626409869ed548b80c17fe2e000d 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -915,14 +915,17 @@ notmuch_message_remove_all_tags (notmuch_message_t *message);
  * flags, and adds or removes tags on 'message' as follows when these
  * flags are present:
  *
- *     Flag    Action
- *     ----    ------
+ *     Flag    Action if present
+ *     ----    -----------------
  *     'D'     Adds the "draft" tag to the message
  *     'F'     Adds the "flagged" tag to the message
  *     'P'     Adds the "passed" tag to the message
  *     'R'     Adds the "replied" tag to the message
  *     'S'     Removes the "unread" tag from the 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
@@ -956,11 +959,11 @@ notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);
  * its filename ends with the sequence ":2," followed by zero or more
  * of the following single-character flags (in ASCII order):
  *
- *   'D' if the message has the "draft" tag
- *   'F' if the message has the "flagged" tag
- *   'P' if the message has the "passed" tag
- *   'R' if the message has the "replied" tag
- *   'S' if the message does not have the "unread" tag
+ *   'D' iff the message has the "draft" tag
+ *   'F' iff the message has the "flagged" tag
+ *   'P' iff the message has the "passed" tag
+ *   '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.