X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=lib%2Fnotmuch.h;h=88da07898eb20958154d80e5cfb72e054b6a2981;hp=479a1dcd3195a886aece90e555f869811f1374b5;hb=bf159bd829efb6aa73c68542949eb11d9a44d93c;hpb=4e5d2f22db290a830c0267f34b519c6138af00ed

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 479a1dcd..88da0789 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -247,8 +247,9 @@ notmuch_database_get_directory (notmuch_database_t *database,
  * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.
  *
  * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message
- *	ID as another message already in the database. The new filename
- *	was successfully added to the message in the database.
+ *	ID as another message already in the database. The new
+ *	filename was successfully added to the message in the database
+ *	(if not already present).
  *
  * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the
  *	file, (such as permission denied, or file not found,
@@ -327,8 +328,9 @@ notmuch_database_get_all_tags (notmuch_database_t *db);
  * As a special case, passing a length-zero string, (that is ""), will
  * result in a query that returns all messages in the database.
  *
- * See notmuch_query_set_sort for controlling the order of results and
- * notmuch_query_search to actually execute the query.
+ * See notmuch_query_set_sort for controlling the order of results.
+ * See notmuch_query_search_messages and notmuch_query_search_threads
+ * to actually execute the query.
  *
  * User should call notmuch_query_destroy when finished with this
  * query.
@@ -432,7 +434,7 @@ notmuch_query_search_messages (notmuch_query_t *query);
  *
  * This will in turn destroy any notmuch_threads_t and
  * notmuch_messages_t objects generated by this query, (and in
- * turn any notmuch_thrad_t and notmuch_message_t objects generated
+ * turn any notmuch_thread_t and notmuch_message_t objects generated
  * from those results, etc.), if such objects haven't already been
  * destroyed.
  */
@@ -466,6 +468,11 @@ notmuch_thread_t *
 notmuch_threads_get (notmuch_threads_t *threads);
 
 /* Move the 'threads' iterator to the next thread.
+ *
+ * If 'threads' is already pointing at the last thread then the
+ * iterator will be moved to a point just beyond that last thread,
+ * (where notmuch_threads_valid will return FALSE and
+ * notmuch_threads_get will return NULL).
  *
  * See the documentation of notmuch_query_search_threads for example
  * code showing how to iterate over a notmuch_threads_t object.
@@ -565,7 +572,7 @@ notmuch_thread_get_subject (notmuch_thread_t *thread);
 time_t
 notmuch_thread_get_oldest_date (notmuch_thread_t *thread);
 
-/* Get the date of the oldest message in 'thread' as a time_t value.
+/* Get the date of the newest message in 'thread' as a time_t value.
  */
 time_t
 notmuch_thread_get_newest_date (notmuch_thread_t *thread);
@@ -640,6 +647,11 @@ notmuch_message_t *
 notmuch_messages_get (notmuch_messages_t *messages);
 
 /* Move the 'messages' iterator to the next message.
+ *
+ * If 'messages' is already pointing at the last message then the
+ * iterator will be moved to a point just beyond that last message,
+ * (where notmuch_messages_valid will return FALSE and
+ * notmuch_messages_get will return NULL).
  *
  * See the documentation of notmuch_query_search_messages for example
  * code showing how to iterate over a notmuch_messages_t object.
@@ -913,7 +925,7 @@ notmuch_message_freeze (notmuch_message_t *message);
  * NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least
  *	its frozen count has successfully been reduced by 1).
  *
- * NOTMUCH_STATUS_UNBALANCE_FREEZE_THAW: An attempt was made to thaw
+ * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw
  *	an unfrozen message. That is, there have been an unbalanced
  *	number of calls to notmuch_message_freeze and
  *	notmuch_message_thaw.
@@ -956,6 +968,11 @@ const char *
 notmuch_tags_get (notmuch_tags_t *tags);
 
 /* Move the 'tags' iterator to the next tag.
+ *
+ * If 'tags' is already pointing at the last tag then the iterator
+ * will be moved to a point just beyond that last tag, (where
+ * notmuch_tags_valid will return FALSE and notmuch_tags_get will
+ * return NULL).
  *
  * See the documentation of notmuch_message_get_tags for example code
  * showing how to iterate over a notmuch_tags_t object.
@@ -1064,6 +1081,11 @@ const char *
 notmuch_filenames_get (notmuch_filenames_t *filenames);
 
 /* Move the 'filenames' iterator to the next filename.
+ *
+ * If 'filenames' is already pointing at the last filename then the
+ * iterator will be moved to a point just beyond that last filename,
+ * (where notmuch_filenames_valid will return FALSE and
+ * notmuch_filenames_get will return NULL).
  *
  * It is acceptable to pass NULL for 'filenames', in which case this
  * function will do nothing.