From a6b3f341dcfbf1160a02d02879a36777bcf459f1 Mon Sep 17 00:00:00 2001 From: Carl Worth Date: Wed, 21 Oct 2009 15:46:46 -0700 Subject: [PATCH] notmuch_query_search: Clarify the documentation. This is where we wanted to put the note to recommend the user call notmuch_message_destroy if the lifetime of the message is much shorter than the lifetime of the query. (Somehow this had ended up in the documentation of notmuch_message_get_tags before.) --- notmuch.h | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/notmuch.h b/notmuch.h index 3b4f980d..5dfc8ce2 100644 --- a/notmuch.h +++ b/notmuch.h @@ -231,17 +231,22 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort); * { * message = notmuch_results_get (results); * .... + * notmuch_message_destroy (message); * } * * notmuch_query_destroy (query); * - * Note that there's no explicit destructor needed for the - * notmuch_results_t object. + * Note: If you are finished with a message before its containing + * query, you can call notmuch_message_destroy to clean up some memory + * sooner (as in the above example). Otherwise, if your message + * objects are long-lived, then you don't need to call + * notmuch_message_destroy and all the memory will still be reclaimed + * when the query is destroyed. * - * (For consistency, we do provide a notmuch_results_destroy function, - * but there's no point in calling it if you're about to destroy the - * query object as well too---either call will free all the memory of - * the results). + * Note that there's no explicit destructor needed for the + * notmuch_results_t object. (For consistency, we do provide a + * notmuch_results_destroy function, but there's no good reason to + * call it if the query is about to be destroyed). */ notmuch_results_t * notmuch_query_search (notmuch_query_t *query);