lib: update doxygen comments to add @since for the new _st API

[notmuch] / lib / notmuch.h

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 87756838d0727f77836e419a2e7f9d5384bb1033..c5f7dcb4b9f10f28b4eab46e4844d7f06680fc05 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -838,6 +838,7 @@ notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
  * notmuch_threads_destroy function, but there's no good reason
  * to call it if the query is about to be destroyed).
  *
+ * @since libnotmuch 4.2 (notmuch 0.20)
  */
 notmuch_status_t
 notmuch_query_search_threads_st (notmuch_query_t *query,
@@ -895,6 +896,7 @@ notmuch_query_search_threads (notmuch_query_t *query);
  *
  * If a Xapian exception occurs this function will return NULL.
  *
+ * @since libnotmuch 4.2 (notmuch 0.20)
  */
 notmuch_status_t
 notmuch_query_search_messages_st (notmuch_query_t *query,
@@ -984,10 +986,28 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
  * This function performs a search and returns the number of matching
  * messages.
  *
- * If a Xapian exception occurs, this function may return 0 (after
- * printing a message).
+ * @returns
+ *
+ * NOTMUCH_STATUS_SUCCESS: query completed successfully.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. The
+ *      value of *count is not defined.
+ *
+ * @since libnotmuch 4.3 (notmuch 0.21)
+ */
+notmuch_status_t
+notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count);
+
+/**
+ * like notmuch_query_count_messages_st, but without a status return.
+ *
+ * May return 0 in the case of errors.
+ *
+ * @deprecated Deprecated since libnotmuch 4.3 (notmuch 0.21). Please
+ * use notmuch_query_count_messages_st instead.
  */
-unsigned
+NOTMUCH_DEPRECATED(4,3)
+unsigned int
 notmuch_query_count_messages (notmuch_query_t *query);
 
 /**
@@ -998,11 +1018,33 @@ notmuch_query_count_messages (notmuch_query_t *query);
  * search.
  *
  * Note that this is a significantly heavier operation than
- * notmuch_query_count_messages().
+ * notmuch_query_count_messages{_st}().
+ *
+ * @returns
  *
- * If an error occurs, this function may return 0.
+ * NOTMUCH_STATUS_OUT_OF_MEMORY: Memory allocation failed. The value
+ *      of *count is not defined
+
+ * NOTMUCH_STATUS_SUCCESS: query completed successfully.
+ *
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. The
+ *      value of *count is not defined.
+ *
+ * @since libnotmuch 4.3 (notmuch 0.21)
+ */
+notmuch_status_t
+notmuch_query_count_threads_st (notmuch_query_t *query, unsigned *count);
+
+/**
+ * like notmuch_query_count_threads, but without a status return.
+ *
+ * May return 0 in case of errors.
+ *
+ * @deprecated Deprecated as of libnotmuch 4.3 (notmuch 0.21). Please
+ * use notmuch_query_count_threads_st instead.
  */
-unsigned
+NOTMUCH_DEPRECATED(4,3)
+unsigned int
 notmuch_query_count_threads (notmuch_query_t *query);
 
 /**