[PATCH] lib doc: group query functions, add disclaimer

[David Bremner]

The destructiveness is somewhat surprising, so emphasize it with an
extra remark in the docs.
---
 lib/notmuch.h | 144 +++++++++++++++++++++++++++++++---------------------------
 1 file changed, 78 insertions(+), 66 deletions(-)

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 2faa146..954060d 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -686,6 +686,70 @@ notmuch_tags_t *
 notmuch_database_get_all_tags (notmuch_database_t *db);
 
 /**
+ * Is the given 'threads' iterator pointing at a valid thread.
+ *
+ * When this function returns TRUE, notmuch_threads_get will return a
+ * valid object. Whereas when this function returns FALSE,
+ * notmuch_threads_get will return NULL.
+ *
+ * If passed a NULL pointer, this function returns FALSE
+ *
+ * See the documentation of notmuch_query_search_threads for example
+ * code showing how to iterate over a notmuch_threads_t object.
+ */
+notmuch_bool_t
+notmuch_threads_valid (notmuch_threads_t *threads);
+
+/**
+ * Get the current thread from 'threads' as a notmuch_thread_t.
+ *
+ * Note: The returned thread belongs to 'threads' and has a lifetime
+ * identical to it (and the query to which it belongs).
+ *
+ * See the documentation of notmuch_query_search_threads for example
+ * code showing how to iterate over a notmuch_threads_t object.
+ *
+ * If an out-of-memory situation occurs, this function will return
+ * NULL.
+ */
+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.
+ */
+void
+notmuch_threads_move_to_next (notmuch_threads_t *threads);
+
+/**
+ * Destroy a notmuch_threads_t object.
+ *
+ * It's not strictly necessary to call this function. All memory from
+ * the notmuch_threads_t object will be reclaimed when the
+ * containing query object is destroyed.
+ */
+void
+notmuch_threads_destroy (notmuch_threads_t *threads);
+
+/**
+ * @name Queries
+ *
+ * @remark The caller should assume that any notmuch_query_* function
+ * without an appropriate const declaration is destructive in its
+ * query argument. In particular calling
+ * notmuch_query_{count,search}_* on the same query may lead to
+ * surprising results.
+ */
+/**@{*/
+/**
  * Create a new query for 'database'.
  *
  * Here, 'database' should be an open database, (see
@@ -736,6 +800,19 @@ typedef enum {
     NOTMUCH_SORT_UNSORTED
 } notmuch_sort_t;
 
+
+/**
+ * Destroy a notmuch_query_t along with any associated resources.
+ *
+ * This will in turn destroy any notmuch_threads_t and
+ * notmuch_messages_t objects generated by this query, (and in
+ * turn any notmuch_thread_t and notmuch_message_t objects generated
+ * from those results, etc.), if such objects haven't already been
+ * destroyed.
+ */
+void
+notmuch_query_destroy (notmuch_query_t *query);
+
 /**
  * Return the query_string of this query. See notmuch_query_create.
  */
@@ -927,72 +1004,6 @@ notmuch_messages_t *
 notmuch_query_search_messages (notmuch_query_t *query);
 
 /**
- * Destroy a notmuch_query_t along with any associated resources.
- *
- * This will in turn destroy any notmuch_threads_t and
- * notmuch_messages_t objects generated by this query, (and in
- * turn any notmuch_thread_t and notmuch_message_t objects generated
- * from those results, etc.), if such objects haven't already been
- * destroyed.
- */
-void
-notmuch_query_destroy (notmuch_query_t *query);
-
-/**
- * Is the given 'threads' iterator pointing at a valid thread.
- *
- * When this function returns TRUE, notmuch_threads_get will return a
- * valid object. Whereas when this function returns FALSE,
- * notmuch_threads_get will return NULL.
- *
- * If passed a NULL pointer, this function returns FALSE
- *
- * See the documentation of notmuch_query_search_threads for example
- * code showing how to iterate over a notmuch_threads_t object.
- */
-notmuch_bool_t
-notmuch_threads_valid (notmuch_threads_t *threads);
-
-/**
- * Get the current thread from 'threads' as a notmuch_thread_t.
- *
- * Note: The returned thread belongs to 'threads' and has a lifetime
- * identical to it (and the query to which it belongs).
- *
- * See the documentation of notmuch_query_search_threads for example
- * code showing how to iterate over a notmuch_threads_t object.
- *
- * If an out-of-memory situation occurs, this function will return
- * NULL.
- */
-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.
- */
-void
-notmuch_threads_move_to_next (notmuch_threads_t *threads);
-
-/**
- * Destroy a notmuch_threads_t object.
- *
- * It's not strictly necessary to call this function. All memory from
- * the notmuch_threads_t object will be reclaimed when the
- * containing query object is destroyed.
- */
-void
-notmuch_threads_destroy (notmuch_threads_t *threads);
-
-/**
  * Return the number of messages matching a search.
  *
  * This function performs a search and returns the number of matching
@@ -1059,6 +1070,7 @@ NOTMUCH_DEPRECATED(4,3)
 unsigned int
 notmuch_query_count_threads (notmuch_query_t *query);
 
+/**@}*/
 /**
  * Get the thread ID of 'thread'.
  *
-- 
2.9.3