From: David Bremner <david@tethera.net>
To: David Bremner <david@tethera.net>,
Franz Fellner <alpine.art.de@gmail.com>,
Lucas Hoffmann <luc.lists@gmail.com>,
notmuch@notmuchmail.org
Subject: [PATCH] lib doc: group query functions, add disclaimer
Date: Sat, 3 Sep 2016 09:50:08 -0300 [thread overview]
Message-ID: <20160903125008.4704-1-david@tethera.net> (raw)
In-Reply-To: <87a8fsl8qs.fsf@zancas.localnet>
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
next prev parent reply other threads:[~2016-09-03 12:50 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-08-31 8:23 Bug: counting messages twice after excluding tags yields different results Lucas
2016-08-31 9:21 ` Franz Fellner
2016-08-31 11:16 ` Lucas Hoffmann
2016-08-31 12:20 ` David Bremner
2016-08-31 12:56 ` Franz Fellner
2016-09-01 1:16 ` David Bremner
2016-09-03 12:50 ` David Bremner [this message]
2016-09-05 10:57 ` David Bremner
2017-03-05 11:41 ` David Bremner
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://notmuchmail.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20160903125008.4704-1-david@tethera.net \
--to=david@tethera.net \
--cc=alpine.art.de@gmail.com \
--cc=luc.lists@gmail.com \
--cc=notmuch@notmuchmail.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://yhetil.org/notmuch.git/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).