X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=998a4ae6fa46e6e5975739db9244e31af767f44b;hp=27b43ff6dc65988363ef8504bb98e1da7926d7c6;hb=3fbb518335fe2271a31a6c4779affa4df42cf203;hpb=f0dfda5c7797f9db81ce35d270fe0ac406c7fca1

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 27b43ff6..998a4ae6 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -500,10 +500,15 @@ typedef enum {
 const char *
 notmuch_query_get_query_string (notmuch_query_t *query);
 
-/* Exclude values for notmuch_query_set_omit_excluded */
+/* Exclude values for notmuch_query_set_omit_excluded. The strange
+ * order is to maintain backward compatibility: the old FALSE/TRUE
+ * options correspond to the new
+ * NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options.
+ */
 typedef enum {
-    NOTMUCH_EXCLUDE_FALSE,
+    NOTMUCH_EXCLUDE_FLAG,
     NOTMUCH_EXCLUDE_TRUE,
+    NOTMUCH_EXCLUDE_FALSE,
     NOTMUCH_EXCLUDE_ALL
 } notmuch_exclude_t;
 
@@ -517,6 +522,15 @@ typedef enum {
  * match in at least one non-excluded message.  Otherwise, if set to ALL,
  * notmuch_query_search_threads will omit excluded messages from all threads.
  *
+ * If set to FALSE or FLAG then both notmuch_query_search_messages and
+ * notmuch_query_search_threads will return all matching
+ * messages/threads regardless of exclude status. If set to FLAG then
+ * the exclude flag will be set for any excluded message that is
+ * returned by notmuch_query_search_messages, and the thread counts
+ * for threads returned by notmuch_query_search_threads will be the
+ * number of non-excluded messages/matches. Otherwise, if set to
+ * FALSE, then the exclude status is completely ignored.
+ *
  * The performance difference when calling
  * notmuch_query_search_messages should be relatively small (and both
  * should be very fast).  However, in some cases,
@@ -753,7 +767,7 @@ notmuch_thread_get_messages (notmuch_thread_t *thread);
 int
 notmuch_thread_get_matched_messages (notmuch_thread_t *thread);
 
-/* Get the authors of 'thread'
+/* Get the authors of 'thread' as a UTF-8 string.
  *
  * The returned string is a comma-separated list of the names of the
  * authors of mail messages in the query results that belong to this
@@ -767,7 +781,7 @@ notmuch_thread_get_matched_messages (notmuch_thread_t *thread);
 const char *
 notmuch_thread_get_authors (notmuch_thread_t *thread);
 
-/* Get the subject of 'thread'
+/* Get the subject of 'thread' as a UTF-8 string.
  *
  * The subject is taken from the first message (according to the query
  * order---see notmuch_query_set_sort) in the query results that
@@ -999,10 +1013,13 @@ notmuch_message_set_flag (notmuch_message_t *message,
 time_t
 notmuch_message_get_date  (notmuch_message_t *message);
 
-/* Get the value of the specified header from 'message'.
+/* Get the value of the specified header from 'message' as a UTF-8 string.
+ *
+ * Common headers are stored in the database when the message is
+ * indexed and will be returned from the database.  Other headers will
+ * be read from the actual message file.
  *
- * The value will be read from the actual message file, not from the
- * notmuch database. The header name is case insensitive.
+ * The header name is case insensitive.
  *
  * The returned string belongs to the message so should not be
  * modified or freed by the caller (nor should it be referenced after