From 5a98880add247cca406cc99bf826398915ee6039 Mon Sep 17 00:00:00 2001 From: Carl Worth Date: Thu, 11 Nov 2010 02:45:24 -0800 Subject: [PATCH] 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). --- lib/notmuch.h | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/lib/notmuch.h b/lib/notmuch.h index 413b5709..4295cbd0 100644 --- 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. -- 2.43.0