The documentation was written for Doxygen, some updates for Hawkmoth. --- lib/notmuch.h | 94 +++++++++++++++++++++++++++++++---------------------------- 1 file changed, 50 insertions(+), 44 deletions(-)
diff --git a/lib/notmuch.h b/lib/notmuch.h index 02586a9126e3..ab01944cb2b0 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -18,12 +18,10 @@ * Author: Carl Worth <cwo...@cworth.org> */ -/** - * @defgroup notmuch The notmuch API +/* + * The notmuch API * * Not much of an email library, (just index and search) - * - * @{ */ #ifndef NOTMUCH_H @@ -78,22 +76,18 @@ NOTMUCH_BEGIN_DECLS * Check the version of the notmuch library being compiled against. * * Return true if the library being compiled against is of the - * specified version or above. For example: + * specified version or above. For example:: * - * @code - * #if LIBNOTMUCH_CHECK_VERSION(3, 1, 0) - * (code requiring libnotmuch 3.1.0 or above) - * #endif - * @endcode + * #if LIBNOTMUCH_CHECK_VERSION(3, 1, 0) + * (code requiring libnotmuch 3.1.0 or above) + * #endif * * LIBNOTMUCH_CHECK_VERSION has been defined since version 3.1.0; to - * check for versions prior to that, use: + * check for versions prior to that, use:: * - * @code - * #if !defined(NOTMUCH_CHECK_VERSION) - * (code requiring libnotmuch prior to 3.1.0) - * #endif - * @endcode + * #if !defined(NOTMUCH_CHECK_VERSION) + * (code requiring libnotmuch prior to 3.1.0) + * #endif */ #define LIBNOTMUCH_CHECK_VERSION(major, minor, micro) \ (LIBNOTMUCH_MAJOR_VERSION > (major) || \ @@ -112,7 +106,7 @@ typedef int notmuch_bool_t; * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function * completed without error. Any other value indicates an error. */ -typedef enum _notmuch_status { +typedef enum { /** * No error occurred. */ @@ -130,8 +124,8 @@ typedef enum _notmuch_status { * A Xapian exception occurred. * * @todo We don't really want to expose this lame XAPIAN_EXCEPTION - * value. Instead we should map to things like DATABASE_LOCKED or - * whatever. + * value. Instead we should map to things like + * DATABASE_LOCKED or whatever. */ NOTMUCH_STATUS_XAPIAN_EXCEPTION, /** @@ -209,16 +203,28 @@ notmuch_status_to_string (notmuch_status_t status); /* Various opaque data types. For each notmuch_<foo>_t see the various * notmuch_<foo> functions below. */ #ifndef __DOXYGEN__ + +/** Notmuch database. */ typedef struct _notmuch_database notmuch_database_t; +/** Notmuch query. */ typedef struct _notmuch_query notmuch_query_t; +/** Notmuch thread list. */ typedef struct _notmuch_threads notmuch_threads_t; +/** Notmuch thread. */ typedef struct _notmuch_thread notmuch_thread_t; +/** Notmuch message list. */ typedef struct _notmuch_messages notmuch_messages_t; +/** Notmuch message. */ typedef struct _notmuch_message notmuch_message_t; +/** Notmuch tag list. */ typedef struct _notmuch_tags notmuch_tags_t; +/** Notmuch directory. */ typedef struct _notmuch_directory notmuch_directory_t; +/** Notmuch filename list. */ typedef struct _notmuch_filenames notmuch_filenames_t; +/** Notmuch config list. */ typedef struct _notmuch_config_list notmuch_config_list_t; +/** Notmuch param. */ typedef struct _notmuch_param notmuch_param_t; #endif /* __DOXYGEN__ */ @@ -845,7 +851,7 @@ notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag); * object is owned by the query and as such, will only be valid until * notmuch_query_destroy. * - * Typical usage might be: + * Typical usage might be:: * * notmuch_query_t *query; * notmuch_threads_t *threads; @@ -886,7 +892,7 @@ notmuch_query_search_threads (notmuch_query_t *query, * Deprecated alias for notmuch_query_search_threads. * * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please - * use notmuch_query_search_threads instead. + * use notmuch_query_search_threads instead. * */ NOTMUCH_DEPRECATED(5,0) @@ -899,7 +905,7 @@ notmuch_query_search_threads_st (notmuch_query_t *query, notmuch_threads_t **out * messages object is owned by the query and as such, will only be * valid until notmuch_query_destroy. * - * Typical usage might be: + * Typical usage might be:: * * notmuch_query_t *query; * notmuch_messages_t *messages; @@ -941,7 +947,7 @@ notmuch_query_search_messages (notmuch_query_t *query, * Deprecated alias for notmuch_query_search_messages * * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please use - * notmuch_query_search_messages instead. + * notmuch_query_search_messages instead. * */ @@ -1039,7 +1045,7 @@ notmuch_query_count_messages (notmuch_query_t *query, unsigned int *count); * * * @deprecated Deprecated since libnotmuch 5.0 (notmuch 0.25). Please - * use notmuch_query_count_messages instead. + * use notmuch_query_count_messages instead. */ NOTMUCH_DEPRECATED(5,0) notmuch_status_t @@ -1074,7 +1080,7 @@ notmuch_query_count_threads (notmuch_query_t *query, unsigned *count); * Deprecated alias for notmuch_query_count_threads * * @deprecated Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please - * use notmuch_query_count_threads_st instead. + * use notmuch_query_count_threads_st instead. */ NOTMUCH_DEPRECATED(5,0) notmuch_status_t @@ -1206,7 +1212,7 @@ notmuch_thread_get_newest_date (notmuch_thread_t *thread); * notmuch_thread_destroy or until the query from which it derived is * destroyed). * - * Typical usage might be: + * Typical usage might be:: * * notmuch_thread_t *thread; * notmuch_tags_t *tags; @@ -1414,7 +1420,7 @@ notmuch_message_reindex (notmuch_message_t *message, /** * Message flags. */ -typedef enum _notmuch_message_flag { +typedef enum { NOTMUCH_MESSAGE_FLAG_MATCH, NOTMUCH_MESSAGE_FLAG_EXCLUDED, @@ -1477,7 +1483,7 @@ notmuch_message_get_header (notmuch_message_t *message, const char *header); * valid for as long as the message is valid, (which is until the * query from which it derived is destroyed). * - * Typical usage might be: + * Typical usage might be:: * * notmuch_message_t *message; * notmuch_tags_t *tags; @@ -1563,13 +1569,15 @@ notmuch_message_remove_all_tags (notmuch_message_t *message); * flags, and adds or removes tags on 'message' as follows when these * flags are present: * - * Flag Action if present - * ---- ----------------- - * 'D' Adds the "draft" tag to the message - * 'F' Adds the "flagged" tag to the message - * 'P' Adds the "passed" tag to the message - * 'R' Adds the "replied" tag to the message - * 'S' Removes the "unread" tag from the message + * ==== ========================================= + * Flag Action if present + * ==== ========================================= + * D Adds the "draft" tag to the message + * F Adds the "flagged" tag to the message + * P Adds the "passed" tag to the message + * R Adds the "replied" tag to the message + * S Removes the "unread" tag from the message + * ==== ========================================= * * For each flag that is not present, the opposite action (add/remove) * is performed for the corresponding tags. @@ -1642,7 +1650,7 @@ notmuch_message_tags_to_maildir_flags (notmuch_message_t *message); * * The ability to do freeze/thaw allows for safe transactions to * change tag values. For example, explicitly setting a message to - * have a given set of tags might look like this: + * have a given set of tags might look like this:: * * notmuch_message_freeze (message); * @@ -1709,7 +1717,7 @@ void notmuch_message_destroy (notmuch_message_t *message); /** - * @name Message Properties + * Message Properties * * This interface provides the ability to attach arbitrary (key,value) * string pairs to a message, to remove such pairs, and to iterate @@ -1718,7 +1726,7 @@ notmuch_message_destroy (notmuch_message_t *message); * depend on these properties. * */ -/**@{*/ + /** * Retrieve the value for a single property key * @@ -1795,7 +1803,7 @@ typedef struct _notmuch_string_map_iterator notmuch_message_properties_t; * @param[in] exact if TRUE, require exact match with key. Otherwise * treat as prefix. * - * Typical usage might be: + * Typical usage might be:: * * notmuch_message_properties_t *list; * @@ -1883,8 +1891,6 @@ notmuch_message_properties_value (notmuch_message_properties_t *properties); void notmuch_message_properties_destroy (notmuch_message_properties_t *properties); -/**@}*/ - /** * Is the given 'tags' iterator pointing at a valid tag. * @@ -1944,11 +1950,11 @@ notmuch_tags_destroy (notmuch_tags_t *tags); * identification of new messages to be added to the database. The * recommended usage is as follows: * - * o Read the mtime of a directory from the filesystem + * - Read the mtime of a directory from the filesystem * - * o Call add_message for all mail files in the directory + * - Call add_message for all mail files in the directory * - * o Call notmuch_directory_set_mtime with the mtime read from the + * - Call notmuch_directory_set_mtime with the mtime read from the * filesystem. * * Then, when wanting to check for updates to the directory in the -- 2.11.0 _______________________________________________ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch