[RFC PATCH 3/4] lib: fix the biggest hawkmoth offenders in notmuch.h

Subject:[RFC PATCH 3/4] lib: fix the biggest hawkmoth offenders in notmuch.h

Date:Sun, 20 Aug 2017 22:30:38 +0300

To:notmuch@notmuchmail.org

Cc:

From:Jani Nikula


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@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

Thread: