lib: Document what move_to_next does at the end of the list.

Explicitly mention that there's an invalid position after the last
item in the list.

1 files changed, 20 insertions, 0 deletions

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 479a1dcd..c67de644 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -467,6 +467,11 @@ 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.
  */
@@ -641,6 +646,11 @@ 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.
  */
@@ -957,6 +967,11 @@ 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.
  */
@@ -1065,6 +1080,11 @@ 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.
  */