From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 38F7F6DE12E5 for ; Sun, 20 Aug 2017 12:30:55 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References" X-Spam-Flag: NO X-Spam-Score: 0.034 X-Spam-Level: X-Spam-Status: No, score=0.034 tagged_above=-999 required=5 tests=[AWL=0.054, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01] autolearn=disabled Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 58nrf0KWi4zo for ; Sun, 20 Aug 2017 12:30:54 -0700 (PDT) Received: from mail-lf0-f51.google.com (mail-lf0-f51.google.com [209.85.215.51]) by arlo.cworth.org (Postfix) with ESMTPS id 1A2186DE12C2 for ; Sun, 20 Aug 2017 12:30:49 -0700 (PDT) Received: by mail-lf0-f51.google.com with SMTP id f123so9905239lfe.3 for ; Sun, 20 Aug 2017 12:30:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nikula-org.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id:in-reply-to:references :in-reply-to:references; bh=+9v+8xHoaskbvWsjYnGcztFcj0LGYTAa75WKKqNeXmk=; b=ChMNhrCDjpPiHMy6Hay71AsgE6pN0gCYoWbuk6GVE3lZkJmg4nJOGGNLaVc3oaVCeG Z8pvmQr4Jae6ntA3SVoMdcSl0o8ClUiwDQ68SaKQhMQzdPkrYro5Sh8awgskqDA+XCI1 EAHvtsKVC3MQLKPsXi1oQTAm2kWHNVDzXKAGz8rWTxlbsQ80wz8c8uTCwTsX2QMqlclN 4f7j5fVBZMd6RbRqC0d8e0U5dB+XZ7zJ8AqR2XZoAwUH7fXAA+TBGBqfrKGOrK3GLqIo kgz8J15257MdcGbUV87uVbuwRjS6WiP+fHfkO7KN57xXjurIVn+/6eByMyNXi2RB54/9 5x3A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:in-reply-to:references; bh=+9v+8xHoaskbvWsjYnGcztFcj0LGYTAa75WKKqNeXmk=; b=ujlv4zleMLR4ggshuoGeB4kw4nb6KsO0Qy0W8S8lStNEF0Hydh8+qHBuMnFDGKOHI8 ipKyjEFX/tsB2+CYeajiLNYGQW0hR6icR0mRCv78b4hRyNIOy9T+Fwia2K0E+X12/hgQ QnlvFYsS7GVIlHj0832BkKPfzYazxIb1VtN+nP8x8CFz8X6ZTyBuU+y6H2v6DQ+UDJ+q 26e4T9KzOYXeUVwqhShO0anE/n0/uxx9HlxMwSRc3kZYcg4EEsOp+56FMgsCp/XJ3+hb GuJL+66xSH6mQ9SEJZEP747pYpPyn2EcGkfVGBnqLQVyaBE/P+wdf9lSUZFykhqpKQ8p KgIA== X-Gm-Message-State: AHYfb5ht1wR0krTdnfJqg9dZM6hOal2K6dN2quO4ej6X8mCkESEJxMj/ JgvpFU4hKqVQDAKSTTfpPw== X-Received: by 10.46.14.18 with SMTP id 18mr5409081ljo.13.1503257447131; Sun, 20 Aug 2017 12:30:47 -0700 (PDT) Received: from localhost (mobile-access-5d6aa6-119.dhcp.inet.fi. [93.106.166.119]) by smtp.gmail.com with ESMTPSA id a63sm589585lfb.94.2017.08.20.12.30.45 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sun, 20 Aug 2017 12:30:46 -0700 (PDT) From: Jani Nikula To: notmuch@notmuchmail.org Subject: [RFC PATCH 3/4] lib: fix the biggest hawkmoth offenders in notmuch.h Date: Sun, 20 Aug 2017 22:30:38 +0300 Message-Id: <149680eb23fc45476ec3f1038d4b74f5a1f2158d.1503256651.git.jani@nikula.org> X-Mailer: git-send-email 2.11.0 In-Reply-To: References: In-Reply-To: References: X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 20 Aug 2017 19:30:55 -0000 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 */ -/** - * @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__t see the various * notmuch_ 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