[RFC PATCH 3/4] lib: fix the biggest hawkmoth offenders in notmuch.h
Jani Nikula
jani at nikula.org
Sun Aug 20 12:30:38 PDT 2017
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 <cworth at 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
More information about the notmuch
mailing list