From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id wCjhFxbiZWHnqAAAgWs5BA (envelope-from ) for ; Tue, 12 Oct 2021 21:29:26 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id SL6QExbiZWEcLwAAB5/wlQ (envelope-from ) for ; Tue, 12 Oct 2021 19:29:26 +0000 Received: from mail.notmuchmail.org (nmbug.tethera.net [144.217.243.247]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 8AD553B3D9 for ; Tue, 12 Oct 2021 21:29:25 +0200 (CEST) Received: from nmbug.tethera.net (localhost [127.0.0.1]) by mail.notmuchmail.org (Postfix) with ESMTP id 56BA62902F; Tue, 12 Oct 2021 15:29:21 -0400 (EDT) Received: from mail-lf1-x12a.google.com (mail-lf1-x12a.google.com [IPv6:2a00:1450:4864:20::12a]) by mail.notmuchmail.org (Postfix) with ESMTPS id 3D2802C176 for ; Tue, 12 Oct 2021 14:51:47 -0400 (EDT) Received: by mail-lf1-x12a.google.com with SMTP id x27so974842lfa.9 for ; Tue, 12 Oct 2021 11:51:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nikula-org.20210112.gappssmtp.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=o8sfk4PT8s06ntIRrBxETk9NQ5DIbvBwBYnzqw8ss/Q=; b=A+7apkN9yvLpF9agrChBBTu4GgI9FM3eeIvkCd5PLl8ZJsEng+wnRhPdfi1s1Q+7sC DvHVisKsnKOpqLHifGlnl8LFgCr4W8k/iJ52nDhReVVMXqwQqATkO+uCrzmXuxBRaAgC Itjuz+4KiT+029e5sYJLg+lERkN14JiquEJsd4n0ctfkTa8I6QBiGu6GqFVLNRqgMLy1 mnmNemTa/YG9xmkcrCT8TWmiQF0DNQrj9R8jiNCmX8c4NS3cADg4WNT+HXpQJTQqhFg5 DvBlka5BeBdpiYcxrVsUk6JpBVIPcodXLbPT5LhrwWDxyB9z9km3oFxSIWSAH6Bd48KV kjPw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=o8sfk4PT8s06ntIRrBxETk9NQ5DIbvBwBYnzqw8ss/Q=; b=AD83d9/fMBLllfc9m1ieWVBM5vja24gTnrFC9x5r0R7/wgMSgfB+npXPuKwzDpUgA2 0kIYUgkZ/jCvRuPb8EvaSEmSgqpm+tAGyeYjzB5FvCUg0+NXH4y9ymGouo0L1/aiNW3h rq4kicN6dejzicltbQik2bJXEKVG6RgwYYdvqBWfQN7vSLhbz6CemsuUt/fOsMfk1py5 qNI8rOcwstxjhWoDDuKMUBkzoI1NGg6dtTN22wswr7ieCGtb02vP2PajtuKphvUW/l8E gv6vnYHYFFymnbxFEVPcDgaO0LHn542Iw8AY3OPTri/ApZ1yHI+/o+OLGJ158oIAx8nx Z6AA== X-Gm-Message-State: AOAM531Akz7L6Tw/Kod42S6NoumA1UUSU2wOTFEp7PjoPJ7aodAFblcX NeFdAk2TpGpMV/sHDADcZSyYvpcWhbmk83E14CY= X-Google-Smtp-Source: ABdhPJwrJnY/BB22kLsv0TCKyE3rNw6NxUL7DX1qYiTGRl4IFAKPU5nbgo5L/XRzJLE5ZD6TeTT0mw== X-Received: by 2002:a2e:bd02:: with SMTP id n2mr30371710ljq.40.1634064701715; Tue, 12 Oct 2021 11:51:41 -0700 (PDT) Received: from localhost (87-95-50-104.bb.dnainternet.fi. [87.95.50.104]) by smtp.gmail.com with ESMTPSA id a11sm1100240lfk.165.2021.10.12.11.51.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 12 Oct 2021 11:51:41 -0700 (PDT) From: Jani Nikula To: notmuch@notmuchmail.org Cc: jani@nikula.org Subject: [RFC 5/5] lib: documentation comment overhaul for hawkmoth Date: Tue, 12 Oct 2021 21:51:27 +0300 Message-Id: <20211012185127.198348-6-jani@nikula.org> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20211012185127.198348-1-jani@nikula.org> References: <20211012185127.198348-1-jani@nikula.org> MIME-Version: 1.0 X-MailFrom: jani@nikula.org X-Mailman-Rule-Hits: max-size X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-notmuch.notmuchmail.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; news-moderation; no-subject; suspicious-header Message-ID-Hash: F7SFYLS7LR5EH2V5QX6OV7YTQUPBIFBL X-Message-ID-Hash: F7SFYLS7LR5EH2V5QX6OV7YTQUPBIFBL X-Mailman-Approved-At: Tue, 12 Oct 2021 19:29:20 -0400 X-Mailman-Version: 3.2.1 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Help: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1634066965; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=s79kuymp0EU5TyEoVBwFjJ5moq07zD5s6RgbKLbx9Fg=; b=aSQfiDoRsN9x2Ky69VeKQiSUQOG18pSKZkJ0YHz8sT19BVuFGVb+Zo0W4H+Y5AG+81fOy+ X2kat7jSREr/w9GKtTKra+ephbkuwLD7iW+Z8tgbPHyZR1u2PwCTOfxuM083VkJDCVBhYH hvrrZNqC2w6l+DhKdj03b5B/miMQMsyc7Cw1gsJdg9Xt6BWs55WDY8QdVSXX2Hk6Ahvm6l 8aQefbRckg64uOj8qFoqUZuD7XjTOzjAZAeMnuQ3/KodLvghUKc69dDCoGyi2KCDrFvdbl cfS2zRYABOwr7gEsDrYGGYynRRrgYx/x9M/JoNchtRzNGFBjeGBfaFSd8cDqhA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1634066965; a=rsa-sha256; cv=none; b=B7l1b0uW8l3KqYxjTtSf+ocRyj40PTOGpRCxvhMsP9RNWwl0blcX4dGxm5hrpnDJUFBv+K 9TKMNOMKJW/ev3zYviRyVHGcKBaythY6TOpkWlJSVqfcfAEZ3KUBvONmgqCoOfFLveQwbT 9woTKhXRlCIVI1ezjdxLYAD4Lp4NxuLQQ9maXbdjL29ugEBncrZlTjaOliYn3nrDDn+GtY y4LM3KOe1+aCQkESSSk/9ukRJrbx9OLNa0oSCFCkqyQSQ8yzrM/vTn5pt6NnSYs/5rpv/P vXKyHIE5mFP2cHhfgdkRlkklkVUdIMC8jITCZJjeqrbr+T3aIRfBbiI/ui5Lzg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("body hash did not verify") header.d=nikula-org.20210112.gappssmtp.com header.s=20210112 header.b=A+7apkN9; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 144.217.243.247 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Spam-Score: -0.18 Authentication-Results: aspmx1.migadu.com; dkim=fail ("body hash did not verify") header.d=nikula-org.20210112.gappssmtp.com header.s=20210112 header.b=A+7apkN9; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 144.217.243.247 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Queue-Id: 8AD553B3D9 X-Spam-Score: -0.18 X-Migadu-Scanner: scn1.migadu.com X-TUID: vyZdrXwRwN/h Convert from Doxygen to Hawkmoth, and improve while at it. - Use rst :param: field lists for parameters. - Use :deprecated: and :since:. - Cross-reference all constructs. - Use preformatted text for TRUE, FALSE, NULL, parameter references, etc. Comment changes only. --- lib/notmuch.h | 1971 +++++++++++++++++++++++++++---------------------- 1 file changed, 1075 insertions(+), 896 deletions(-) diff --git a/lib/notmuch.h b/lib/notmuch.h index 700e9b7b25c1..9d78ff64d7c7 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -19,13 +19,12 @@ */ /** - * @defgroup notmuch The notmuch API + * The notmuch API * * Not much of an email library, (just index and search) - * - * @{ */ +/**/ #ifndef NOTMUCH_H #define NOTMUCH_H @@ -72,23 +71,25 @@ 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: + * :param major: major version + * :param minor: minor version + * :param micro: micro version + * + * :return: true if the library being compiled against is of the + * 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) || \ @@ -104,8 +105,9 @@ typedef int notmuch_bool_t; /** * Status codes used for the return values of most functions. * - * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function - * completed without error. Any other value indicates an error. + * A zero value (:c:enumerator:`NOTMUCH_STATUS_SUCCESS`) indicates + * that the function completed without error. Any other value + * indicates an error. */ typedef enum { /** @@ -124,9 +126,13 @@ typedef enum { /** * 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. + * .. note:: + * + * We don't really want to expose this lame + * :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION` + * value. Instead we should map to things like + * :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE` or + * whatever. */ NOTMUCH_STATUS_XAPIAN_EXCEPTION, /** @@ -145,22 +151,22 @@ typedef enum { */ NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID, /** - * The user erroneously passed a NULL pointer to a notmuch + * The user erroneously passed a ``NULL`` pointer to a notmuch * function. */ NOTMUCH_STATUS_NULL_POINTER, /** - * A tag value is too long (exceeds NOTMUCH_TAG_MAX). + * A tag value is too long (exceeds :c:macro:`NOTMUCH_TAG_MAX`). */ NOTMUCH_STATUS_TAG_TOO_LONG, /** - * The notmuch_message_thaw function has been called more times - * than notmuch_message_freeze. + * The :c:func:`notmuch_message_thaw` function has been called + * more times than :c:func:`notmuch_message_freeze`. */ NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW, /** - * notmuch_database_end_atomic has been called more times than - * notmuch_database_begin_atomic. + * :c:func:`notmuch_database_end_atomic` has been called more + * times than :c:func:`notmuch_database_begin_atomic`. */ NOTMUCH_STATUS_UNBALANCED_ATOMIC, /** @@ -227,7 +233,7 @@ typedef enum { } notmuch_status_t; /** - * Get a string representation of a notmuch_status_t value. + * Get a string representation of a :c:type:`notmuch_status_t` value. * * The result is read-only. */ @@ -236,61 +242,78 @@ notmuch_status_to_string (notmuch_status_t status); /* Various opaque data types. For each notmuch__t see the various * notmuch_ functions below. */ +/** Notmuch opaque database type. */ typedef struct _notmuch_database notmuch_database_t; +/** Notmuch opaque query type. */ typedef struct _notmuch_query notmuch_query_t; +/** Notmuch opaque threads type. */ typedef struct _notmuch_threads notmuch_threads_t; +/** Notmuch opaque thread type. */ typedef struct _notmuch_thread notmuch_thread_t; +/** Notmuch opaque messages type. */ typedef struct _notmuch_messages notmuch_messages_t; +/** Notmuch opaque message type. */ typedef struct _notmuch_message notmuch_message_t; +/** Notmuch opaque tags type. */ typedef struct _notmuch_tags notmuch_tags_t; +/** Notmuch opaque directory type. */ typedef struct _notmuch_directory notmuch_directory_t; +/** Notmuch opaque filenames type. */ typedef struct _notmuch_filenames notmuch_filenames_t; +/** Notmuch opaque config list type. */ typedef struct _notmuch_config_list notmuch_config_list_t; +/** Notmuch opaque type. */ typedef struct _notmuch_config_values notmuch_config_values_t; +/** Notmuch opaque config values type. */ typedef struct _notmuch_config_pairs notmuch_config_pairs_t; +/** Notmuch opaque indexing options type. */ typedef struct _notmuch_indexopts notmuch_indexopts_t; /** - * Create a new, empty notmuch database located at 'path'. + * Create a new, empty notmuch database located at ``path``. * * The path should be a top-level directory to a collection of * plain-text email messages (one message per file). This call will - * create a new ".notmuch" directory within 'path' where notmuch will - * store its data. + * create a new ".notmuch" directory within ``path`` where notmuch + * will store its data. * - * After a successful call to notmuch_database_create, the returned - * database will be open so the caller should call - * notmuch_database_destroy when finished with it. + * After a successful call to :c:func:`notmuch_database_create`, the + * returned database will be open so the caller should call + * :c:func:`notmuch_database_destroy` when finished with it. * * The database will not yet have any data in it - * (notmuch_database_create itself is a very cheap function). Messages - * contained within 'path' can be added to the database by calling - * notmuch_database_index_file. + * (:c:func:`notmuch_database_create` itself is a very cheap + * function). Messages contained within ``path`` can be added to the + * database by calling :c:func:`notmuch_database_index_file`. * * In case of any failure, this function returns an error status and - * sets *database to NULL (after printing an error message on stderr). + * sets ``*database`` to ``NULL`` (after printing an error message on + * ``stderr``). * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Successfully created the database. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully created + * the database. * - * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL. + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The given ``path`` + * argument is ``NULL``. * - * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. + * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of memory. * - * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to create the - * database file (such as permission denied, or file not found, - * etc.), or the database already exists. + * - :c:enumerator:`NOTMUCH_STATUS_FILE_ERROR`: An error occurred + * trying to create the database file (such as permission denied, + * or file not found, etc.), or the database already exists. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred. */ notmuch_status_t notmuch_database_create (const char *path, notmuch_database_t **database); /** - * Like notmuch_database_create, except optionally return an error - * message. This message is allocated by malloc and should be freed by - * the caller. + * Like :c:func:`notmuch_database_create`, except optionally return an + * error message. This message is allocated by malloc and should be + * freed by the caller. */ notmuch_status_t notmuch_database_create_verbose (const char *path, @@ -298,7 +321,7 @@ notmuch_database_create_verbose (const char *path, char **error_message); /** - * Database open mode for notmuch_database_open. + * Database open mode for :c:func:`notmuch_database_open`. */ typedef enum { /** @@ -312,20 +335,20 @@ typedef enum { } notmuch_database_mode_t; /** - * Deprecated alias for notmuch_database_open_with_config with - * config_path="" and error_message=NULL - * @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32) + * Deprecated alias for :c:func:`notmuch_database_open_with_config` + * with config_path="" and error_message=NULL + * + * :deprecated: Deprecated as of libnotmuch 5.4 (notmuch 0.32) */ notmuch_status_t notmuch_database_open (const char *path, notmuch_database_mode_t mode, notmuch_database_t **database); /** - * Deprecated alias for notmuch_database_open_with_config with + * Deprecated alias for :c:func:`notmuch_database_open_with_config` with * config_path="" * - * @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32) - * + * :deprecated: Deprecated as of libnotmuch 5.4 (notmuch 0.32) */ notmuch_status_t notmuch_database_open_verbose (const char *path, @@ -337,102 +360,100 @@ notmuch_database_open_verbose (const char *path, * Open an existing notmuch database located at 'database_path', using * configuration in 'config_path'. * - * @param[in] database_path - * @parblock - * Path to existing database. + * :param database_path: + * Path to existing database. * - * A notmuch database is a Xapian database containing appropriate - * metadata. + * A notmuch database is a Xapian database containing appropriate + * metadata. * - * The database should have been created at some time in the past, - * (not necessarily by this process), by calling - * notmuch_database_create. + * The database should have been created at some time in the past, + * (not necessarily by this process), by calling + * notmuch_database_create. * - * If 'database_path' is NULL, use the location specified + * If 'database_path' is ``NULL``, use the location specified * - * - in the environment variable NOTMUCH_DATABASE, if non-empty + * - in the environment variable ``NOTMUCH_DATABASE``, if non-empty * - * - in a configuration file, located as described under 'config_path' + * - in a configuration file, located as described under ``config_path`` * - * - by $XDG_DATA_HOME/notmuch/$PROFILE where XDG_DATA_HOME defaults - * to "$HOME/.local/share" and PROFILE as as discussed in - * 'profile' + * - by ``$XDG_DATA_HOME/notmuch/$PROFILE`` where + * ``XDG_DATA_HOME`` defaults to ``$HOME/.local/share`` and + * ``PROFILE`` as as discussed in 'profile' * - * If 'database_path' is non-NULL, but does not appear to be a Xapian - * database, check for a directory '.notmuch/xapian' below - * 'database_path' (this is the behavior of - * notmuch_database_open_verbose pre-0.32). + * If ``database_path`` is non-``NULL``, but does not appear to be a + * Xapian database, check for a directory ``.notmuch/xapian`` below + * ``database_path`` (this is the behavior of + * :c:func:`notmuch_database_open_verbose` pre-0.32). * - * @endparblock - * @param[in] mode - * @parblock - * Mode to open database. Use one of #NOTMUCH_DATABASE_MODE_READ_WRITE - * or #NOTMUCH_DATABASE_MODE_READ_ONLY + * :param mode: Mode to open database. Use one of + * :c:enumerator:`NOTMUCH_DATABASE_MODE_READ_WRITE` or + * :c:enumerator:`NOTMUCH_DATABASE_MODE_READ_ONLY` * - * @endparblock - * @param[in] config_path - * @parblock - * Path to config file. + * :param config_path: + * Path to config file. * - * Config file is key-value, with mandatory sections. See - * notmuch-config(5) for more information. The key-value pair - * overrides the corresponding configuration data stored in the - * database (see notmuch_database_get_config) + * Config file is key-value, with mandatory sections. See + * :any:`notmuch-config(1)` for more information. The key-value pair + * overrides the corresponding configuration data stored in the + * database (see :c:func:`notmuch_database_get_config`). * - * If config_path is NULL use the path specified + * If ``config_path`` is ``NULL`` use the path specified * - * - in environment variable NOTMUCH_CONFIG, if non-empty + * - in environment variable ``NOTMUCH_CONFIG``, if non-empty. * - * - by XDG_CONFIG_HOME/notmuch/ where - * XDG_CONFIG_HOME defaults to "$HOME/.config". + * - by ``XDG_CONFIG_HOME/notmuch/`` where ``XDG_CONFIG_HOME`` + * defaults to ``$HOME/.config``. * - * - by $HOME/.notmuch-config + * - by ``$HOME/.notmuch-config``. * - * If config_path is "" (empty string) then do not - * open any configuration file. - * @endparblock - * @param[in] profile: - * @parblock - * Name of profile (configuration/database variant). + * If ``config_path`` is "" (empty string) then do not open any + * configuration file. * - * If non-NULL, append to the directory / file path determined for - * config_path and database_path. + * :param profile: + * Name of profile (configuration/database variant). * - * If NULL then use - * - environment variable NOTMUCH_PROFILE if defined, - * - otherwise "default" for directories and "" (empty string) for paths. + * If non-``NULL``, append to the directory / file path determined + * for ``config_path`` and ``database_path``. * - * @endparblock - * @param[out] database - * @parblock - * Pointer to database object. May not be NULL. + * If ``NULL`` then use * - * The caller should call notmuch_database_destroy when finished with - * this database. + * - environment variable ``NOTMUCH_PROFILE`` if defined, * - * In case of any failure, this function returns an error status and - * sets *database to NULL. + * - otherwise "default" for directories and "" (empty string) for paths. + * + * :param database: + * Pointer to database object. May not be ``NULL``. + * + * The caller should call :c:func:`notmuch_database_destroy` when + * finished with this database. + * + * In case of any failure, this function returns an error status and + * sets ``*database`` to ``NULL``. + * + * :param error_message: + * If non-``NULL``, store error message from opening the database. + * Any such message is allocated by **malloc(3)** and should be freed + * by the caller. * - * @endparblock - * @param[out] error_message - * If non-NULL, store error message from opening the database. - * Any such message is allocated by \a malloc(3) and should be freed - * by the caller. + * :return: * - * @retval NOTMUCH_STATUS_SUCCESS: Successfully opened the database. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully opened the + * database. * - * @retval NOTMUCH_STATUS_NULL_POINTER: The given \a database - * argument is NULL. + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The given database + * argument is ``NULL``. * - * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. + * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of memory. * - * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the - * database or config file (such as permission denied, or file not found, - * etc.), or the database version is unknown. + * - :c:enumerator:`NOTMUCH_STATUS_FILE_ERROR`: An error occurred + * trying to open the database or config file (such as permission + * denied, or file not found, etc.), or the database version is + * unknown. * - * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred. * - * @since libnotmuch 5.4 (notmuch 0.32) + * :since: libnotmuch 5.4 (notmuch 0.32) */ notmuch_status_t @@ -447,26 +468,31 @@ notmuch_database_open_with_config (const char *database_path, /** * Loads configuration from config file, database, and/or defaults * - * For description of arguments, @see notmuch_database_open_with_config + * For description of arguments, see + * :c:func:`notmuch_database_open_with_config` * - * @retval NOTMUCH_STATUS_SUCCESS: Successfully loaded configuration. + * :return: * - * @retval NOTMUCH_STATUS_NO_CONFIG: No config file was loaded. Not fatal. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully loaded + * configuration. * - * @retval NOTMUCH_STATUS_NO_DATABASE: No config information was - * loaded from a database. Not fatal. + * - :c:enumerator:`NOTMUCH_STATUS_NO_CONFIG`: No config file was + * loaded. Not fatal. * - * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. + * - :c:enumerator:`NOTMUCH_STATUS_NO_DATABASE`: No config + * information was loaded from a database. Not fatal. * - * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the - * database or config file (such as permission denied, or file not found, - * etc.) + * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of memory. * - * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. + * - :c:enumerator:`NOTMUCH_STATUS_FILE_ERROR`: An error occurred + * trying to open the database or config file (such as permission + * denied, or file not found, etc.) * - * @since libnotmuch 5.4 (notmuch 0.32) + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred. + * + * :since: libnotmuch 5.4 (notmuch 0.32) */ - notmuch_status_t notmuch_database_load_config (const char *database_path, const char *config_path, @@ -478,21 +504,27 @@ notmuch_database_load_config (const char *database_path, * Create a new notmuch database located at 'database_path', using * configuration in 'config_path'. * - * For description of arguments, @see notmuch_database_open_with_config + * For description of arguments, see :c:func:`notmuch_database_open_with_config` + * + * :return: * - * @retval NOTMUCH_STATUS_SUCCESS: Successfully created the database. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully + * created the database. * - * @retval NOTMUCH_STATUS_DATABASE_EXISTS: Database already exists, not created + * - :c:enumerator:`NOTMUCH_STATUS_DATABASE_EXISTS`: Database + * already exists, not created * - * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. + * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of + * memory. * - * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the - * database or config file (such as permission denied, or file not found, - * etc.) + * - :c:enumerator:`NOTMUCH_STATUS_FILE_ERROR`: An error + * occurred trying to open the database or config file (such as + * permission denied, or file not found, etc.) * - * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred. * - * @since libnotmuch 5.4 (notmuch 0.32) + * :since: libnotmuch 5.4 (notmuch 0.32) */ notmuch_status_t @@ -504,7 +536,6 @@ notmuch_database_create_with_config (const char *database_path, /** * Retrieve last status string for given database. - * */ const char * notmuch_database_status_string (const notmuch_database_t *notmuch); @@ -512,37 +543,39 @@ notmuch_database_status_string (const notmuch_database_t *notmuch); /** * Commit changes and close the given notmuch database. * - * After notmuch_database_close has been called, calls to other + * After :c:func:`notmuch_database_close` has been called, calls to other * functions on objects derived from this database may either behave * as if the database had not been closed (e.g., if the required data * has been cached) or may fail with a - * NOTMUCH_STATUS_XAPIAN_EXCEPTION. The only further operation + * :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`. The only further operation * permitted on the database itself is to call - * notmuch_database_destroy. + * :c:func:`notmuch_database_destroy`. * - * notmuch_database_close can be called multiple times. Later calls - * have no effect. + * :c:func:`notmuch_database_close` can be called multiple times. + * Later calls have no effect. * - * For writable databases, notmuch_database_close commits all changes + * For writable databases, :c:func:`notmuch_database_close` commits all changes * to disk before closing the database, unless the caller is currently - * in an atomic section (there was a notmuch_database_begin_atomic - * without a matching notmuch_database_end_atomic). In this case - * changes since the last commit are discarded. @see - * notmuch_database_end_atomic for more information. + * in an atomic section (there was a :c:func:`notmuch_database_begin_atomic` + * without a matching :c:func:`notmuch_database_end_atomic`). In this case + * changes since the last commit are discarded. See + * :c:func:`notmuch_database_end_atomic` for more information. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Successfully closed the database. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully closed the + * database. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; the - * database has been closed but there are no guarantees the - * changes to the database, if any, have been flushed to disk. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred; the database has been closed but there are + * no guarantees the changes to the database, if any, have been + * flushed to disk. */ notmuch_status_t notmuch_database_close (notmuch_database_t *database); /** - * A callback invoked by notmuch_database_compact to notify the user + * A callback invoked by :c:func:`notmuch_database_compact` to notify the user * of the progress of the compaction process. */ typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure); @@ -551,12 +584,13 @@ typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure); * Compact a notmuch database, backing up the original database to the * given path. * - * The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE - * during the compaction process to ensure no writes are made. + * The database will be opened with + * :c:enumerator:`NOTMUCH_DATABASE_MODE_READ_WRITE` during the + * compaction process to ensure no writes are made. * - * If the optional callback function 'status_cb' is non-NULL, it will - * be called with diagnostic and informational messages. The argument - * 'closure' is passed verbatim to any callback invoked. + * If the optional callback function ``status_cb`` is non-``NULL``, it + * will be called with diagnostic and informational messages. The + * argument ``closure`` is passed verbatim to any callback invoked. */ notmuch_status_t notmuch_database_compact (const char *path, @@ -568,7 +602,7 @@ notmuch_database_compact (const char *path, * Like notmuch_database_compact, but take an open database as a * parameter. * - * @since libnnotmuch 5.4 (notmuch 0.32) + * :since: libnnotmuch 5.4 (notmuch 0.32) */ notmuch_status_t notmuch_database_compact_db (notmuch_database_t *database, @@ -580,8 +614,9 @@ notmuch_database_compact_db (notmuch_database_t *database, * Destroy the notmuch database, closing it if necessary and freeing * all associated resources. * - * Return value as in notmuch_database_close if the database was open; - * notmuch_database_destroy itself has no failure modes. + * Return value as in :c:func:`notmuch_database_close` if the database + * was open; :c:func:`notmuch_database_destroy` itself has no failure + * modes. */ notmuch_status_t notmuch_database_destroy (notmuch_database_t *database); @@ -598,7 +633,7 @@ notmuch_database_get_path (notmuch_database_t *database); /** * Return the database format version of the given database. * - * @retval 0 on error + * :return: Database format version, or 0 on error. */ unsigned int notmuch_database_get_version (notmuch_database_t *database); @@ -606,15 +641,15 @@ notmuch_database_get_version (notmuch_database_t *database); /** * Can the database be upgraded to a newer database version? * - * If this function returns TRUE, then the caller may call - * notmuch_database_upgrade to upgrade the database. If the caller - * does not upgrade an out-of-date database, then some functions may - * fail with NOTMUCH_STATUS_UPGRADE_REQUIRED. This always returns - * FALSE for a read-only database because there's no way to upgrade a - * read-only database. - * - * Also returns FALSE if an error occurs accessing the database. + * If this function returns ``TRUE``, then the caller may call + * :c:func:`notmuch_database_upgrade` to upgrade the database. If the + * caller does not upgrade an out-of-date database, then some + * functions may fail with + * :c:enumerator:`NOTMUCH_STATUS_UPGRADE_REQUIRED`. This always + * returns ``FALSE`` for a read-only database because there's no way + * to upgrade a read-only database. * + * Also returns ``FALSE`` if an error occurs accessing the database. */ notmuch_bool_t notmuch_database_needs_upgrade (notmuch_database_t *database); @@ -625,16 +660,17 @@ notmuch_database_needs_upgrade (notmuch_database_t *database); * This ensures that all current notmuch functionality will be * available on the database. After opening a database in read-write * mode, it is recommended that clients check if an upgrade is needed - * (notmuch_database_needs_upgrade) and if so, upgrade with this - * function before making any modifications. If - * notmuch_database_needs_upgrade returns FALSE, this will be a no-op. + * (:c:func:`notmuch_database_needs_upgrade`) and if so, upgrade with + * this function before making any modifications. If + * :c:func:`notmuch_database_needs_upgrade` returns ``FALSE``, this + * will be a no-op. * * The optional progress_notify callback can be used by the caller to - * provide progress indication to the user. If non-NULL it will be - * called periodically with 'progress' as a floating-point value in + * provide progress indication to the user. If non-``NULL`` it will be + * called periodically with ``progress`` as a floating-point value in * the range of [0.0 .. 1.0] indicating the progress made so far in - * the upgrade process. The argument 'closure' is passed verbatim to - * any callback invoked. + * the upgrade process. The argument ``closure`` is passed verbatim + * to any callback invoked. */ notmuch_status_t notmuch_database_upgrade (notmuch_database_t *database, @@ -646,20 +682,21 @@ notmuch_database_upgrade (notmuch_database_t *database, * Begin an atomic database operation. * * Any modifications performed between a successful begin and a - * notmuch_database_end_atomic will be applied to the database - * atomically. Note that, unlike a typical database transaction, this - * only ensures atomicity, not durability; neither begin nor end - * necessarily flush modifications to disk. + * :c:func:`notmuch_database_end_atomic` will be applied to the + * database atomically. Note that, unlike a typical database + * transaction, this only ensures atomicity, not durability; neither + * begin nor end necessarily flush modifications to disk. * * Atomic sections may be nested. begin_atomic and end_atomic must * always be called in pairs. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Successfully entered atomic section. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully + * entered atomic section. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; - * atomic section not entered. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred; atomic section not entered. */ notmuch_status_t notmuch_database_begin_atomic (notmuch_database_t *notmuch); @@ -670,15 +707,16 @@ notmuch_database_begin_atomic (notmuch_database_t *notmuch); * times, commit the the transaction and all previous (non-cancelled) * transactions to the database. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Successfully completed atomic section. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully + * completed atomic section. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; - * atomic section not ended. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred; atomic section not ended. * - * NOTMUCH_STATUS_UNBALANCED_ATOMIC: The database is not currently in - * an atomic section. + * - :c:enumerator:`NOTMUCH_STATUS_UNBALANCED_ATOMIC`: The + * database is not currently in an atomic section. */ notmuch_status_t notmuch_database_end_atomic (notmuch_database_t *notmuch); @@ -693,39 +731,43 @@ notmuch_database_end_atomic (notmuch_database_t *notmuch); * messages committed in the future will be assigned a modification * revision > the committed database revision. * - * The UUID is a NUL-terminated opaque string that uniquely identifies - * this database. Two revision numbers are only comparable if they - * have the same database UUID. + * The UUID is a ``NUL``-terminated opaque string that uniquely + * identifies this database. Two revision numbers are only comparable + * if they have the same database UUID. */ unsigned long notmuch_database_get_revision (notmuch_database_t *notmuch, const char **uuid); /** - * Retrieve a directory object from the database for 'path'. + * Retrieve a directory object from the database for ``path``. * - * Here, 'path' should be a path relative to the path of 'database' - * (see notmuch_database_get_path), or else should be an absolute path - * with initial components that match the path of 'database'. + * Here, ``path`` should be a path relative to the path of + * ``database`` (see :c:func:`notmuch_database_get_path`), or else + * should be an absolute path with initial components that match the + * path of ``database``. * * If this directory object does not exist in the database, this - * returns NOTMUCH_STATUS_SUCCESS and sets *directory to NULL. + * returns :c:enumerator:`NOTMUCH_STATUS_SUCCESS` and sets + * ``*directory`` to ``NULL``. * * Otherwise the returned directory object is owned by the database - * and as such, will only be valid until notmuch_database_destroy is - * called. + * and as such, will only be valid until + * :c:func:`notmuch_database_destroy` is called. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Successfully retrieved directory. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully retrieved + * directory. * - * NOTMUCH_STATUS_NULL_POINTER: The given 'directory' argument is NULL. + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The given + * ``directory`` argument is ``NULL``. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; - * directory not retrieved. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred; directory not retrieved. * - * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the - * database to use this function. + * - :c:enumerator:`NOTMUCH_STATUS_UPGRADE_REQUIRED`: The caller + * must upgrade the database to use this function. */ notmuch_status_t notmuch_database_get_directory (notmuch_database_t *database, @@ -738,10 +780,10 @@ notmuch_database_get_directory (notmuch_database_t *database, * ID as the specified file, their indexes will be merged, and this * new filename will also be associated with the existing message. * - * Here, 'filename' should be a path relative to the path of - * 'database' (see notmuch_database_get_path), or else should be an - * absolute filename with initial components that match the path of - * 'database'. + * Here, ``filename`` should be a path relative to the path of + * ``database`` (see :c:func:`notmuch_database_get_path`), or else + * should be an absolute filename with initial components that match + * the path of ``database``. * * The file should be a single mail message (not a multi-message mbox) * that is expected to remain at its current location, (since the @@ -751,46 +793,50 @@ notmuch_database_get_directory (notmuch_database_t *database, * If another message with the same message ID already exists in the * database, rather than creating a new message, this adds the search * terms from the identified file to the existing message's index, and - * adds 'filename' to the list of filenames known for the message. + * adds ``filename`` to the list of filenames known for the message. * - * The 'indexopts' parameter can be NULL (meaning, use the indexing + * The ``indexopts`` parameter can be ``NULL`` (meaning, use the indexing * defaults from the database), or can be an explicit choice of * indexing options that should govern the indexing of this specific - * 'filename'. + * ``filename``. * - * If 'message' is not NULL, then, on successful return - * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message' + * If ``message`` is not ``NULL``, then, on successful return + * (:c:enumerator:`NOTMUCH_STATUS_SUCCESS` or + * :c:enumerator:`NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID`) ``*message`` * will be initialized to a message object that can be used for things * such as adding tags to the just-added message. The user should call - * notmuch_message_destroy when done with the message. On any failure - * '*message' will be set to NULL. + * :c:func:`notmuch_message_destroy` when done with the message. On + * any failure ``*message`` will be set to ``NULL``. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Message successfully added to database. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Message successfully + * added to database. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, - * message not added. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred, message not added. * - * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message - * ID as another message already in the database. The new - * filename was successfully added to the message in the database - * (if not already present) and the existing message is returned. + * - :c:enumerator:`NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID`: Message + * has the same message ID as another message already in the + * database. The new filename was successfully added to the + * message in the database (if not already present) and the + * existing message is returned. * - * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the - * file, (such as permission denied, or file not found, - * etc.). Nothing added to the database. + * - :c:enumerator:`NOTMUCH_STATUS_FILE_ERROR`: an error occurred + * trying to open the file, (such as permission denied, or file + * not found, etc.). Nothing added to the database. * - * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look - * like an email message. Nothing added to the database. + * - :c:enumerator:`NOTMUCH_STATUS_FILE_NOT_EMAIL`: the contents of + * filename don't look like an email message. Nothing added to the + * database. * - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only - * mode so no message can be added. + * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: Database was + * opened in read-only mode so no message can be added. * - * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the - * database to use this function. + * - :c:enumerator:`NOTMUCH_STATUS_UPGRADE_REQUIRED`: The caller + * must upgrade the database to use this function. * - * @since libnotmuch 5.1 (notmuch 0.26) + * :since: libnotmuch 5.1 (notmuch 0.26) */ notmuch_status_t notmuch_database_index_file (notmuch_database_t *database, @@ -799,11 +845,11 @@ notmuch_database_index_file (notmuch_database_t *database, notmuch_message_t **message); /** - * Deprecated alias for notmuch_database_index_file called with - * NULL indexopts. + * Deprecated alias for :c:func:`notmuch_database_index_file` called + * with ``NULL`` indexopts. * - * @deprecated Deprecated as of libnotmuch 5.1 (notmuch 0.26). Please - * use notmuch_database_index_file instead. + * :deprecated: Deprecated as of libnotmuch 5.1 (notmuch 0.26). Please + * use :c:func:`notmuch_database_index_file` instead. * */ NOTMUCH_DEPRECATED (5, 1) @@ -822,23 +868,24 @@ notmuch_database_add_message (notmuch_database_t *database, * a particular message, the database content for that message will be * entirely removed. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the - * message was removed from the database. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: The last filename + * was removed and the message was removed from the database. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred, - * message not removed. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred, message not removed. * - * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but - * the message persists in the database with at least one other - * filename. + * - :c:enumerator:`NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID`: This + * filename was removed but the message persists in the database + * with at least one other filename. * - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only - * mode so no message can be removed. + * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: + * Database was opened in read-only mode so no message can be + * removed. * - * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the - * database to use this function. + * - :c:enumerator:`NOTMUCH_STATUS_UPGRADE_REQUIRED`: The caller + * must upgrade the database to use this function. */ notmuch_status_t notmuch_database_remove_message (notmuch_database_t *database, @@ -847,25 +894,30 @@ notmuch_database_remove_message (notmuch_database_t *database, /** * Find a message with the given message_id. * - * If a message with the given message_id is found then, on successful return - * (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to a message - * object. The caller should call notmuch_message_destroy when done with the - * message. + * If a message with the given message_id is found then, on successful + * return (:c:enumerator:`NOTMUCH_STATUS_SUCCESS`) ``*message`` will + * be initialized to a message object. The caller should call + * :c:func:`notmuch_message_destroy` when done with the message. * - * On any failure or when the message is not found, this function initializes - * '*message' to NULL. This means, when NOTMUCH_STATUS_SUCCESS is returned, the - * caller is supposed to check '*message' for NULL to find out whether the + * On any failure or when the message is not found, this function + * initializes ``*message`` to ``NULL``. This means, when + * :c:enumerator:`NOTMUCH_STATUS_SUCCESS` is returned, the caller is + * supposed to check ``*message`` for ``NULL`` to find out whether the * message with the given message_id was found. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Successful return, check '*message'. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successful return, + * check ``*message``. * - * NOTMUCH_STATUS_NULL_POINTER: The given 'message' argument is NULL + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The given + * ``message`` argument is ``NULL`` * - * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating message object + * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of + * memory, creating message object * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred */ notmuch_status_t notmuch_database_find_message (notmuch_database_t *database, @@ -876,27 +928,33 @@ notmuch_database_find_message (notmuch_database_t *database, * Find a message with the given filename. * * If the database contains a message with the given filename then, on - * successful return (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to - * a message object. The caller should call notmuch_message_destroy when done - * with the message. + * successful return (:c:enumerator:`NOTMUCH_STATUS_SUCCESS`) + * ``*message`` will be initialized to a message object. The caller + * should call :c:func:`notmuch_message_destroy` when done with the + * message. * - * On any failure or when the message is not found, this function initializes - * '*message' to NULL. This means, when NOTMUCH_STATUS_SUCCESS is returned, the - * caller is supposed to check '*message' for NULL to find out whether the + * On any failure or when the message is not found, this function + * initializes ``*message`` to ``NULL``. This means, when + * :c:enumerator:`NOTMUCH_STATUS_SUCCESS` is returned, the caller is + * supposed to check ``*message`` for ``NULL`` to find out whether the * message with the given filename is found. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Successful return, check '*message' + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successful return, + * check ``*message`` * - * NOTMUCH_STATUS_NULL_POINTER: The given 'message' argument is NULL + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The given + * ``message`` argument is ``NULL`` * - * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating the message object + * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of + * memory, creating the message object * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred * - * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the - * database to use this function. + * - :c:enumerator:`NOTMUCH_STATUS_UPGRADE_REQUIRED`: The + * caller must upgrade the database to use this function. */ notmuch_status_t notmuch_database_find_message_by_filename (notmuch_database_t *notmuch, @@ -907,9 +965,10 @@ notmuch_database_find_message_by_filename (notmuch_database_t *notmuch, * Return a list of all tags found in the database. * * This function creates a list of all tags found in the database. The - * resulting list contains all tags from all messages found in the database. + * resulting list contains all tags from all messages found in the + * database. * - * On error this function returns NULL. + * On error this function returns ``NULL``. */ notmuch_tags_t * notmuch_database_get_all_tags (notmuch_database_t *db); @@ -917,12 +976,18 @@ notmuch_database_get_all_tags (notmuch_database_t *db); /** * Reopen an open notmuch database. * - * @param [in] db open notmuch database - * @param [in] mode mode (read only or read-write) for reopened database. + * :param db: open notmuch database + * :param mode: mode (read only or read-write) for reopened database. + * + * :return: + * + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS` * - * @retval #NOTMUCH_STATUS_SUCCESS - * @retval #NOTMUCH_STATUS_ILLEGAL_ARGUMENT The passed database was not open. - * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION A Xapian exception occured + * - :c:enumerator:`NOTMUCH_STATUS_ILLEGAL_ARGUMENT`: The passed + * database was not open. + * + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occured. */ notmuch_status_t notmuch_database_reopen (notmuch_database_t *db, notmuch_database_mode_t mode); @@ -930,8 +995,9 @@ notmuch_database_reopen (notmuch_database_t *db, notmuch_database_mode_t mode); /** * Create a new query for 'database'. * - * Here, 'database' should be an open database, (see - * notmuch_database_open and notmuch_database_create). + * Here, ``database`` should be an open database, (see + * :c:func:`notmuch_database_open` and + * :c:func:`notmuch_database_create`). * * For the query string, we'll document the syntax here more * completely in the future, but it's likely to be a specialized @@ -939,18 +1005,19 @@ notmuch_database_reopen (notmuch_database_t *db, notmuch_database_mode_t mode); * * https://xapian.org/docs/queryparser.html * - * As a special case, passing either a length-zero string, (that is ""), - * or a string consisting of a single asterisk (that is "*"), will - * result in a query that returns all messages in the database. - * - * See notmuch_query_set_sort for controlling the order of results. - * See notmuch_query_search_messages and notmuch_query_search_threads - * to actually execute the query. + * As a special case, passing either a length-zero string, (that is + * ""), or a string consisting of a single asterisk (that is "*"), + * will result in a query that returns all messages in the database. * - * User should call notmuch_query_destroy when finished with this + * See :c:func:`notmuch_query_set_sort` for controlling the order of + * results. See :c:func:`notmuch_query_search_messages` and + * :c:func:`notmuch_query_search_threads` to actually execute the * query. * - * Will return NULL if insufficient memory is available. + * User should call :c:func:`notmuch_query_destroy` when finished with + * this query. + * + * Will return ``NULL`` if insufficient memory is available. */ notmuch_query_t * notmuch_query_create (notmuch_database_t *database, @@ -967,7 +1034,7 @@ notmuch_query_create_with_syntax (notmuch_database_t *database, notmuch_query_syntax_t syntax, notmuch_query_t **output); /** - * Sort values for notmuch_query_set_sort. + * Sort values for :c:func:`notmuch_query_set_sort`. */ typedef enum { /** @@ -989,7 +1056,8 @@ typedef enum { } notmuch_sort_t; /** - * Return the query_string of this query. See notmuch_query_create. + * Return the query_string of this query. See + * :c:func:`notmuch_query_create`. */ const char * notmuch_query_get_query_string (const notmuch_query_t *query); @@ -1001,44 +1069,58 @@ notmuch_database_t * notmuch_query_get_database (const notmuch_query_t *query); /** - * Exclude values for notmuch_query_set_omit_excluded. The strange - * order is to maintain backward compatibility: the old FALSE/TRUE - * options correspond to the new - * NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options. + * Exclude values for :c:func:`notmuch_query_set_omit_excluded`. The + * strange order is to maintain backward compatibility: the old + * ``FALSE``/``TRUE`` options correspond to the new + * :c:enumerator:`NOTMUCH_EXCLUDE_FLAG`/:c:enumerator:`NOTMUCH_EXCLUDE_TRUE` + * options. */ typedef enum { + /** See :c:func:`notmuch_query_set_omit_excluded`. */ NOTMUCH_EXCLUDE_FLAG, + /** See :c:func:`notmuch_query_set_omit_excluded`. */ NOTMUCH_EXCLUDE_TRUE, + /** See :c:func:`notmuch_query_set_omit_excluded`. */ NOTMUCH_EXCLUDE_FALSE, + /** See :c:func:`notmuch_query_set_omit_excluded`. */ NOTMUCH_EXCLUDE_ALL } notmuch_exclude_t; /** * Specify whether to omit excluded results or simply flag them. By - * default, this is set to TRUE. - * - * If set to TRUE or ALL, notmuch_query_search_messages will omit excluded - * messages from the results, and notmuch_query_search_threads will omit - * threads that match only in excluded messages. If set to TRUE, - * notmuch_query_search_threads will include all messages in threads that - * match in at least one non-excluded message. Otherwise, if set to ALL, - * notmuch_query_search_threads will omit excluded messages from all threads. - * - * If set to FALSE or FLAG then both notmuch_query_search_messages and - * notmuch_query_search_threads will return all matching - * messages/threads regardless of exclude status. If set to FLAG then - * the exclude flag will be set for any excluded message that is - * returned by notmuch_query_search_messages, and the thread counts - * for threads returned by notmuch_query_search_threads will be the - * number of non-excluded messages/matches. Otherwise, if set to - * FALSE, then the exclude status is completely ignored. + * default, this is set to :c:enumerator:`NOTMUCH_EXCLUDE_TRUE`. + * + * If set to :c:enumerator:`NOTMUCH_EXCLUDE_TRUE` or + * :c:enumerator:`NOTMUCH_EXCLUDE_ALL`, + * :c:func:`notmuch_query_search_messages` will omit excluded messages + * from the results, and :c:func:`notmuch_query_search_threads` will + * omit threads that match only in excluded messages. If set to + * :c:enumerator:`NOTMUCH_EXCLUDE_TRUE`, + * :c:func:`notmuch_query_search_threads` will include all messages in + * threads that match in at least one non-excluded message. + * Otherwise, if set to :c:enumerator:`NOTMUCH_EXCLUDE_ALL`, + * :c:func:`notmuch_query_search_threads` will omit excluded messages + * from all threads. + * + * If set to :c:enumerator:`NOTMUCH_EXCLUDE_FALSE` or + * :c:enumerator:`NOTMUCH_EXCLUDE_FLAG` then both + * :c:func:`notmuch_query_search_messages` and + * :c:func:`notmuch_query_search_threads` will return all matching + * messages/threads regardless of exclude status. If set to + * :c:enumerator:`NOTMUCH_EXCLUDE_FLAG` then the exclude flag will be + * set for any excluded message that is returned by + * :c:func:`notmuch_query_search_messages`, and the thread counts for + * threads returned by :c:func:`notmuch_query_search_threads` will be + * the number of non-excluded messages/matches. Otherwise, if set to + * :c:enumerator:`NOTMUCH_EXCLUDE_FALSE`, then the exclude status is + * completely ignored. * * The performance difference when calling - * notmuch_query_search_messages should be relatively small (and both - * should be very fast). However, in some cases, - * notmuch_query_search_threads is very much faster when omitting - * excluded messages as it does not need to construct the threads that - * only match in excluded messages. + * :c:func:`notmuch_query_search_messages` should be relatively small + * (and both should be very fast). However, in some cases, + * :c:func:`notmuch_query_search_threads` is very much faster when + * omitting excluded messages as it does not need to construct the + * threads that only match in excluded messages. */ void notmuch_query_set_omit_excluded (notmuch_query_t *query, @@ -1052,7 +1134,7 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort); /** * Return the sort specified for this query. See - * notmuch_query_set_sort. + * :c:func:`notmuch_query_set_sort`. */ notmuch_sort_t notmuch_query_get_sort (const notmuch_query_t *query); @@ -1062,26 +1144,29 @@ notmuch_query_get_sort (const notmuch_query_t *query); * This exclusion will be ignored if this tag appears explicitly in * the query. * - * @returns + * :return: * - * NOTMUCH_STATUS_SUCCESS: excluded was added successfully. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: excluded was added + * successfully. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. - * Most likely a problem lazily parsing the query string. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: a Xapian + * exception occurred. Most likely a problem lazily parsing the + * query string. * - * NOTMUCH_STATUS_IGNORED: tag is explicitly present in the query, so - * not excluded. + * - :c:enumerator:`NOTMUCH_STATUS_IGNORED`: tag is explicitly + * present in the query, so not excluded. */ notmuch_status_t notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag); /** - * Execute a query for threads, returning a notmuch_threads_t object - * which can be used to iterate over the results. The returned threads - * object is owned by the query and as such, will only be valid until - * notmuch_query_destroy. + * Execute a query for threads, returning a + * :c:type:`notmuch_threads_t` object which can be used to iterate + * over the results. The returned threads object is owned by the query + * and as such, will only be valid until + * :c:func:`notmuch_query_destroy`. * - * Typical usage might be: + * Typical usage might be:: * * notmuch_query_t *query; * notmuch_threads_t *threads; @@ -1103,28 +1188,28 @@ notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag); * notmuch_query_destroy (query); * * Note: If you are finished with a thread before its containing - * query, you can call notmuch_thread_destroy to clean up some memory - * sooner (as in the above example). Otherwise, if your thread objects - * are long-lived, then you don't need to call notmuch_thread_destroy - * and all the memory will still be reclaimed when the query is - * destroyed. + * query, you can call :c:func:`notmuch_thread_destroy` to clean up + * some memory sooner (as in the above example). Otherwise, if your + * thread objects are long-lived, then you don't need to call + * :c:func:`notmuch_thread_destroy` and all the memory will still be + * reclaimed when the query is destroyed. * * Note that there's no explicit destructor needed for the - * notmuch_threads_t object. (For consistency, we do provide a - * notmuch_threads_destroy function, but there's no good reason - * to call it if the query is about to be destroyed). + * :c:type:`notmuch_threads_t` object. (For consistency, we do provide + * a :c:func:`notmuch_threads_destroy` function, but there's no good + * reason to call it if the query is about to be destroyed). * - * @since libnotmuch 5.0 (notmuch 0.25) + * :since: libnotmuch 5.0 (notmuch 0.25) */ notmuch_status_t notmuch_query_search_threads (notmuch_query_t *query, notmuch_threads_t **out); /** - * Deprecated alias for notmuch_query_search_threads. + * Deprecated alias for :c:func:`notmuch_query_search_threads`. * - * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please - * use notmuch_query_search_threads instead. + * :deprecated: Deprecated as of libnotmuch 5 (notmuch 0.25). Please + * use :c:func:`notmuch_query_search_threads` instead. * */ NOTMUCH_DEPRECATED (5, 0) @@ -1132,12 +1217,13 @@ notmuch_status_t notmuch_query_search_threads_st (notmuch_query_t *query, notmuch_threads_t **out); /** - * Execute a query for messages, returning a notmuch_messages_t object - * which can be used to iterate over the results. The returned - * messages object is owned by the query and as such, will only be - * valid until notmuch_query_destroy. + * Execute a query for messages, returning a + * :c:type:`notmuch_messages_t` object which can be used to iterate + * over the results. The returned messages object is owned by the + * query and as such, will only be valid until + * :c:func:`notmuch_query_destroy`. * - * Typical usage might be: + * Typical usage might be:: * * notmuch_query_t *query; * notmuch_messages_t *messages; @@ -1157,29 +1243,29 @@ notmuch_query_search_threads_st (notmuch_query_t *query, notmuch_threads_t **out * notmuch_query_destroy (query); * * Note: If you are finished with a message before its containing - * query, you can call notmuch_message_destroy to clean up some memory - * sooner (as in the above example). Otherwise, if your message - * objects are long-lived, then you don't need to call - * notmuch_message_destroy and all the memory will still be reclaimed - * when the query is destroyed. + * query, you can call :c:func:`notmuch_message_destroy` to clean up + * some memory sooner (as in the above example). Otherwise, if your + * message objects are long-lived, then you don't need to call + * :c:func:`notmuch_message_destroy` and all the memory will still be + * reclaimed when the query is destroyed. * * Note that there's no explicit destructor needed for the - * notmuch_messages_t object. (For consistency, we do provide a - * notmuch_messages_destroy function, but there's no good - * reason to call it if the query is about to be destroyed). + * :c:type:`notmuch_messages_t` object. (For consistency, we do + * provide a :c:func:`notmuch_messages_destroy` function, but there's + * no good reason to call it if the query is about to be destroyed). * - * If a Xapian exception occurs this function will return NULL. + * If a Xapian exception occurs this function will return ``NULL``. * - * @since libnotmuch 5 (notmuch 0.25) + * :since: libnotmuch 5 (notmuch 0.25) */ notmuch_status_t notmuch_query_search_messages (notmuch_query_t *query, notmuch_messages_t **out); /** - * Deprecated alias for notmuch_query_search_messages + * Deprecated alias for :c:func:`notmuch_query_search_messages` * - * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please use - * notmuch_query_search_messages instead. + * :deprecated: Deprecated as of libnotmuch 5 (notmuch 0.25). Please + * use :c:func:`notmuch_query_search_messages` instead. * */ @@ -1189,66 +1275,71 @@ notmuch_query_search_messages_st (notmuch_query_t *query, notmuch_messages_t **out); /** - * Destroy a notmuch_query_t along with any associated resources. + * Destroy a :c:type:`notmuch_query_t` along with any associated + * resources. * - * This will in turn destroy any notmuch_threads_t and - * notmuch_messages_t objects generated by this query, (and in - * turn any notmuch_thread_t and notmuch_message_t objects generated - * from those results, etc.), if such objects haven't already been - * destroyed. + * This will in turn destroy any :c:type:`notmuch_threads_t` and + * :c:type:`notmuch_messages_t` objects generated by this query, (and + * in turn any :c:type:`notmuch_thread_t` and + * :c:type:`notmuch_message_t` objects generated from those results, + * etc.), if such objects haven't already been destroyed. */ void notmuch_query_destroy (notmuch_query_t *query); /** - * Is the given 'threads' iterator pointing at a valid thread. + * Is the given ``threads`` iterator pointing at a valid thread. * - * When this function returns TRUE, notmuch_threads_get will return a - * valid object. Whereas when this function returns FALSE, - * notmuch_threads_get will return NULL. + * When this function returns ``TRUE``, :c:func:`notmuch_threads_get` + * will return a valid object. Whereas when this function returns + * ``FALSE``, :c:func:`notmuch_threads_get` will return ``NULL``. * - * If passed a NULL pointer, this function returns FALSE + * If passed a ``NULL`` pointer, this function returns ``FALSE`` * - * See the documentation of notmuch_query_search_threads for example - * code showing how to iterate over a notmuch_threads_t object. + * See the documentation of :c:func:`notmuch_query_search_threads` for + * example code showing how to iterate over a + * :c:type:`notmuch_threads_t` object. */ notmuch_bool_t notmuch_threads_valid (notmuch_threads_t *threads); /** - * Get the current thread from 'threads' as a notmuch_thread_t. + * Get the current thread from ``threads`` as a + * :c:type:`notmuch_thread_t`. * - * Note: The returned thread belongs to 'threads' and has a lifetime + * Note: The returned thread belongs to ``threads`` and has a lifetime * identical to it (and the query to which it belongs). * - * See the documentation of notmuch_query_search_threads for example - * code showing how to iterate over a notmuch_threads_t object. + * See the documentation of :c:func:`notmuch_query_search_threads` for + * example code showing how to iterate over a + * :c:type:`notmuch_threads_t` object. * * If an out-of-memory situation occurs, this function will return - * NULL. + * ``NULL``. */ notmuch_thread_t * notmuch_threads_get (notmuch_threads_t *threads); /** - * Move the 'threads' iterator to the next thread. + * Move the ``threads`` iterator to the next thread. * - * If 'threads' is already pointing at the last thread then the + * If ``threads`` is already pointing at the last thread then the * iterator will be moved to a point just beyond that last thread, - * (where notmuch_threads_valid will return FALSE and - * notmuch_threads_get will return NULL). + * (where :c:func:`notmuch_threads_valid` will return ``FALSE`` and + * :c:func:`notmuch_threads_get` will return ``NULL``). * - * See the documentation of notmuch_query_search_threads for example - * code showing how to iterate over a notmuch_threads_t object. + * See the documentation of :c:func:`notmuch_query_search_threads` for + * example code showing how to iterate over a + * :c:type:`notmuch_threads_t` object. */ void notmuch_threads_move_to_next (notmuch_threads_t *threads); /** - * Destroy a notmuch_threads_t object. + * Destroy a :c:type:`notmuch_threads_t` object. * * It's not strictly necessary to call this function. All memory from - * the notmuch_threads_t object will be reclaimed when the + * the :c:type:`notmuch_threads_t` object will be reclaimed when the * containing query object is destroyed. */ void @@ -1260,24 +1351,22 @@ notmuch_threads_destroy (notmuch_threads_t *threads); * This function performs a search and returns the number of matching * messages. * - * @returns - * - * NOTMUCH_STATUS_SUCCESS: query completed successfully. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: query completed + * successfully. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The - * value of *count is not defined. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: a Xapian + * exception occurred. The value of ``*count`` is not defined. * - * @since libnotmuch 5 (notmuch 0.25) + * :since: libnotmuch 5 (notmuch 0.25) */ notmuch_status_t notmuch_query_count_messages (notmuch_query_t *query, unsigned int *count); /** - * Deprecated alias for notmuch_query_count_messages - * + * Deprecated alias for :c:func:`notmuch_query_count_messages` * - * @deprecated Deprecated since libnotmuch 5.0 (notmuch 0.25). Please - * use notmuch_query_count_messages instead. + * :deprecated: Deprecated since libnotmuch 5.0 (notmuch 0.25). Please + * use :c:func:`notmuch_query_count_messages` instead. */ NOTMUCH_DEPRECATED (5, 0) notmuch_status_t @@ -1286,73 +1375,78 @@ notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count); /** * Return the number of threads matching a search. * - * This function performs a search and returns the number of unique thread IDs - * in the matching messages. This is the same as number of threads matching a - * search. + * This function performs a search and returns the number of unique + * thread IDs in the matching messages. This is the same as number of + * threads matching a search. * * Note that this is a significantly heavier operation than - * notmuch_query_count_messages{_st}(). + * :c:func:`notmuch_query_count_messages` or + * :c:func:`notmuch_query_count_messages_st`. * - * @returns + * :return: * - * NOTMUCH_STATUS_OUT_OF_MEMORY: Memory allocation failed. The value - * of *count is not defined + * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Memory allocation + * failed. The value of ``*count`` is not defined * - * NOTMUCH_STATUS_SUCCESS: query completed successfully. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Query completed + * successfully. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The - * value of *count is not defined. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred. The value of ``*count`` is not defined. * - * @since libnotmuch 5 (notmuch 0.25) + * :since: libnotmuch 5 (notmuch 0.25) */ notmuch_status_t notmuch_query_count_threads (notmuch_query_t *query, unsigned *count); /** - * Deprecated alias for notmuch_query_count_threads + * Deprecated alias for :c:func:`notmuch_query_count_threads` * - * @deprecated Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please - * use notmuch_query_count_threads_st instead. + * :deprecated: Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please + * use :c:func:`notmuch_query_count_threads_st` instead. */ NOTMUCH_DEPRECATED (5, 0) notmuch_status_t notmuch_query_count_threads_st (notmuch_query_t *query, unsigned *count); /** - * Get the thread ID of 'thread'. + * Get the thread ID of ``thread``. * - * The returned string belongs to 'thread' and as such, should not be - * modified by the caller and will only be valid for as long as the - * thread is valid, (which is until notmuch_thread_destroy or until - * the query from which it derived is destroyed). + * The returned string belongs to ``thread`` and as such, should not + * be modified by the caller and will only be valid for as long as the + * thread is valid, (which is until :c:func:`notmuch_thread_destroy` + * or until the query from which it derived is destroyed). */ const char * notmuch_thread_get_thread_id (notmuch_thread_t *thread); /** - * Get the total number of messages in 'thread'. + * Get the total number of messages in ``thread``. * * This count consists of all messages in the database belonging to - * this thread. Contrast with notmuch_thread_get_matched_messages() . + * this thread. Contrast with + * :c:func:`notmuch_thread_get_matched_messages`. */ int notmuch_thread_get_total_messages (notmuch_thread_t *thread); /** - * Get the total number of files in 'thread'. + * Get the total number of files in ``thread``. * - * This sums notmuch_message_count_files over all messages in the - * thread - * @returns Non-negative integer - * @since libnotmuch 5.0 (notmuch 0.25) + * This sums :c:func:`notmuch_message_count_files` over all messages + * in the thread + * + * :return: Non-negative integer + * + * :since: libnotmuch 5.0 (notmuch 0.25) */ int notmuch_thread_get_total_files (notmuch_thread_t *thread); /** - * Get a notmuch_messages_t iterator for the top-level messages in - * 'thread' in oldest-first order. + * Get a :c:type:`notmuch_messages_t` iterator for the top-level + * messages in ``thread`` in oldest-first order. * * This iterator will not necessarily iterate over all of the messages * in the thread. It will only iterate over the messages in the thread @@ -1364,8 +1458,8 @@ notmuch_messages_t * notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread); /** - * Get a notmuch_thread_t iterator for all messages in 'thread' in - * oldest-first order. + * Get a :c:type:`notmuch_thread_t` iterator for all messages in + * ``thread`` in oldest-first order. * * The returned list will be destroyed when the thread is destroyed. */ @@ -1373,66 +1467,66 @@ notmuch_messages_t * notmuch_thread_get_messages (notmuch_thread_t *thread); /** - * Get the number of messages in 'thread' that matched the search. + * Get the number of messages in ``thread`` that matched the search. * * This count includes only the messages in this thread that were * matched by the search from which the thread was created and were * not excluded by any exclude tags passed in with the query (see - * notmuch_query_add_tag_exclude). Contrast with - * notmuch_thread_get_total_messages() . + * :c:func:`notmuch_query_add_tag_exclude`). Contrast with + * :c:func:`notmuch_thread_get_total_messages`. */ int notmuch_thread_get_matched_messages (notmuch_thread_t *thread); /** - * Get the authors of 'thread' as a UTF-8 string. + * Get the authors of ``thread`` as a UTF-8 string. * * The returned string is a comma-separated list of the names of the * authors of mail messages in the query results that belong to this * thread. * - * The string contains authors of messages matching the query first, then - * non-matched authors (with the two groups separated by '|'). Within - * each group, authors are ordered by date. + * The string contains authors of messages matching the query first, + * then non-matched authors (with the two groups separated by + * '|'). Within each group, authors are ordered by date. * - * The returned string belongs to 'thread' and as such, should not be - * modified by the caller and will only be valid for as long as the - * thread is valid, (which is until notmuch_thread_destroy or until - * the query from which it derived is destroyed). + * The returned string belongs to ``thread`` and as such, should not + * be modified by the caller and will only be valid for as long as the + * thread is valid, (which is until :c:func:`notmuch_thread_destroy` + * or until the query from which it derived is destroyed). */ const char * notmuch_thread_get_authors (notmuch_thread_t *thread); /** - * Get the subject of 'thread' as a UTF-8 string. + * Get the subject of ``thread`` as a UTF-8 string. * * The subject is taken from the first message (according to the query - * order---see notmuch_query_set_sort) in the query results that - * belongs to this thread. + * order---see :c:func:`notmuch_query_set_sort`) in the query results + * that belongs to this thread. * - * The returned string belongs to 'thread' and as such, should not be - * modified by the caller and will only be valid for as long as the - * thread is valid, (which is until notmuch_thread_destroy or until - * the query from which it derived is destroyed). + * The returned string belongs to ``thread`` and as such, should not + * be modified by the caller and will only be valid for as long as the + * thread is valid, (which is until :c:func:`notmuch_thread_destroy` + * or until the query from which it derived is destroyed). */ const char * notmuch_thread_get_subject (notmuch_thread_t *thread); /** - * Get the date of the oldest message in 'thread' as a time_t value. + * Get the date of the oldest message in ``thread`` as a time_t value. */ time_t notmuch_thread_get_oldest_date (notmuch_thread_t *thread); /** - * Get the date of the newest message in 'thread' as a time_t value. + * Get the date of the newest message in ``thread`` as a time_t value. */ time_t notmuch_thread_get_newest_date (notmuch_thread_t *thread); /** - * Get the tags for 'thread', returning a notmuch_tags_t object which - * can be used to iterate over all tags. + * Get the tags for ``thread``, returning a :c:type:`notmuch_tags_t` + * object which can be used to iterate over all tags. * * Note: In the Notmuch database, tags are stored on individual * messages, not on threads. So the tags returned here will be all @@ -1441,10 +1535,10 @@ notmuch_thread_get_newest_date (notmuch_thread_t *thread); * * The tags object is owned by the thread and as such, will only be * valid for as long as the thread is valid, (for example, until - * notmuch_thread_destroy or until the query from which it derived is - * destroyed). + * :c:func:`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; @@ -1463,67 +1557,71 @@ notmuch_thread_get_newest_date (notmuch_thread_t *thread); * notmuch_thread_destroy (thread); * * Note that there's no explicit destructor needed for the - * notmuch_tags_t object. (For consistency, we do provide a - * notmuch_tags_destroy function, but there's no good reason to call - * it if the message is about to be destroyed). + * :c:type:`notmuch_tags_t` object. (For consistency, we do provide a + * :c:func:`notmuch_tags_destroy` function, but there's no good reason + * to call it if the message is about to be destroyed). */ notmuch_tags_t * notmuch_thread_get_tags (notmuch_thread_t *thread); /** - * Destroy a notmuch_thread_t object. + * Destroy a :c:type:`notmuch_thread_t` object. */ void notmuch_thread_destroy (notmuch_thread_t *thread); /** - * Is the given 'messages' iterator pointing at a valid message. + * Is the given ``messages`` iterator pointing at a valid message. * - * When this function returns TRUE, notmuch_messages_get will return a - * valid object. Whereas when this function returns FALSE, - * notmuch_messages_get will return NULL. + * When this function returns ``TRUE``, :c:func:`notmuch_messages_get` + * will return a valid object. Whereas when this function returns + * ``FALSE``, :c:func:`notmuch_messages_get` will return ``NULL``. * - * See the documentation of notmuch_query_search_messages for example - * code showing how to iterate over a notmuch_messages_t object. + * See the documentation of :c:func:`notmuch_query_search_messages` + * for example code showing how to iterate over a + * :c:type:`notmuch_messages_t` object. */ notmuch_bool_t notmuch_messages_valid (notmuch_messages_t *messages); /** - * Get the current message from 'messages' as a notmuch_message_t. + * Get the current message from ``messages`` as a + * :c:type:`notmuch_message_t`. * - * Note: The returned message belongs to 'messages' and has a lifetime - * identical to it (and the query to which it belongs). + * Note: The returned message belongs to ``messages`` and has a + * lifetime identical to it (and the query to which it belongs). * - * See the documentation of notmuch_query_search_messages for example - * code showing how to iterate over a notmuch_messages_t object. + * See the documentation of :c:func:`notmuch_query_search_messages` + * for example code showing how to iterate over a + * :c:type:`notmuch_messages_t` object. * * If an out-of-memory situation occurs, this function will return - * NULL. + * ``NULL``. */ notmuch_message_t * notmuch_messages_get (notmuch_messages_t *messages); /** - * Move the 'messages' iterator to the next message. + * Move the ``messages`` iterator to the next message. * - * If 'messages' is already pointing at the last message then the + * If ``messages`` is already pointing at the last message then the * iterator will be moved to a point just beyond that last message, - * (where notmuch_messages_valid will return FALSE and - * notmuch_messages_get will return NULL). + * (where :c:func:`notmuch_messages_valid` will return ``FALSE`` and + * :c:func:`notmuch_messages_get` will return ``NULL``). * - * See the documentation of notmuch_query_search_messages for example - * code showing how to iterate over a notmuch_messages_t object. + * See the documentation of :c:func:`notmuch_query_search_messages` + * for example code showing how to iterate over a + * :c:type:`notmuch_messages_t` object. */ void notmuch_messages_move_to_next (notmuch_messages_t *messages); /** - * Destroy a notmuch_messages_t object. + * Destroy a :c:type:`notmuch_messages_t` object. * * It's not strictly necessary to call this function. All memory from - * the notmuch_messages_t object will be reclaimed when the containing - * query object is destroyed. + * the :c:type:`notmuch_messages_t` object will be reclaimed when the + * containing query object is destroyed. */ void notmuch_messages_destroy (notmuch_messages_t *messages); @@ -1533,13 +1631,15 @@ notmuch_messages_destroy (notmuch_messages_t *messages); * * The resulting list is guaranteed not to contain duplicated tags. * - * WARNING: You can no longer iterate over messages after calling this - * function, because the iterator will point at the end of the list. - * We do not have a function to reset the iterator yet and the only - * way how you can iterate over the list again is to recreate the - * message list. + * .. warning:: + * + * You can no longer iterate over messages after calling this + * function, because the iterator will point at the end of the list. + * We do not have a function to reset the iterator yet and the only + * way how you can iterate over the list again is to recreate the + * message list. * - * The function returns NULL on error. + * The function returns ``NULL`` on error. */ notmuch_tags_t * notmuch_messages_collect_tags (notmuch_messages_t *messages); @@ -1547,80 +1647,83 @@ notmuch_messages_collect_tags (notmuch_messages_t *messages); /** * Get the database associated with this message. * - * @since libnotmuch 5.2 (notmuch 0.27) + * :since: libnotmuch 5.2 (notmuch 0.27) */ notmuch_database_t * notmuch_message_get_database (const notmuch_message_t *message); /** - * Get the message ID of 'message'. + * Get the message ID of ``message``. * - * The returned string belongs to 'message' and as such, should not be - * modified by the caller and will only be valid for as long as the + * The returned string belongs to ``message`` and as such, should not + * be modified by the caller and will only be valid for as long as the * message is valid, (which is until the query from which it derived * is destroyed). * - * This function will return NULL if triggers an unhandled Xapian + * This function will return ``NULL`` if triggers an unhandled Xapian * exception. */ const char * notmuch_message_get_message_id (notmuch_message_t *message); /** - * Get the thread ID of 'message'. + * Get the thread ID of ``message``. * - * The returned string belongs to 'message' and as such, should not be - * modified by the caller and will only be valid for as long as the + * The returned string belongs to ``message`` and as such, should not + * be modified by the caller and will only be valid for as long as the * message is valid, (for example, until the user calls - * notmuch_message_destroy on 'message' or until a query from which it - * derived is destroyed). + * :c:func:`notmuch_message_destroy` on ``message`` or until a query + * from which it derived is destroyed). * - * This function will return NULL if triggers an unhandled Xapian + * This function will return ``NULL`` if triggers an unhandled Xapian * exception. */ const char * notmuch_message_get_thread_id (notmuch_message_t *message); /** - * Get a notmuch_messages_t iterator for all of the replies to - * 'message'. + * Get a :c:type:`notmuch_messages_t` iterator for all of the replies to + * ``message``. * - * Note: This call only makes sense if 'message' was ultimately - * obtained from a notmuch_thread_t object, (such as by coming - * directly from the result of calling notmuch_thread_get_ - * toplevel_messages or by any number of subsequent - * calls to notmuch_message_get_replies). + * Note: This call only makes sense if ``message`` was ultimately + * obtained from a :c:type:`notmuch_thread_t` object, (such as by + * coming directly from the result of calling + * :c:func:`notmuch_thread_get_toplevel_messages` or by any number of + * subsequent calls to :c:func:`notmuch_message_get_replies`). * - * If 'message' was obtained through some non-thread means, (such as - * by a call to notmuch_query_search_messages), then this function - * will return NULL. + * If ``message`` was obtained through some non-thread means, (such as + * by a call to :c:func:`notmuch_query_search_messages`), then this + * function will return ``NULL``. * - * If there are no replies to 'message', this function will return - * NULL. (Note that notmuch_messages_valid will accept that NULL - * value as legitimate, and simply return FALSE for it.) + * If there are no replies to ``message``, this function will return + * ``NULL``. (Note that :c:func:`notmuch_messages_valid` will accept + * that ``NULL`` value as legitimate, and simply return ``FALSE`` for + * it.) * - * This function also returns NULL if it triggers a Xapian exception. + * This function also returns ``NULL`` if it triggers a Xapian + * exception. * - * The returned list will be destroyed when the thread is - * destroyed. + * The returned list will be destroyed when the thread is destroyed. */ notmuch_messages_t * notmuch_message_get_replies (notmuch_message_t *message); /** * Get the total number of files associated with a message. - * @returns Non-negative integer for file count. - * @returns Negative integer for error. - * @since libnotmuch 5.0 (notmuch 0.25) + * + * :return: Non-negative integer for file count, negative integer for + * error. + * + * :since: libnotmuch 5.0 (notmuch 0.25) */ int notmuch_message_count_files (notmuch_message_t *message); /** - * Get a filename for the email corresponding to 'message'. + * Get a filename for the email corresponding to ``message``. * * The returned filename is an absolute filename, (the initial - * component will match notmuch_database_get_path() ). + * component will match :c:func:`notmuch_database_get_path`). * * The returned string belongs to the message so should not be * modified or freed by the caller (nor should it be referenced after @@ -1629,38 +1732,39 @@ notmuch_message_count_files (notmuch_message_t *message); * Note: If this message corresponds to multiple files in the mail * store, (that is, multiple files contain identical message IDs), * this function will arbitrarily return a single one of those - * filenames. See notmuch_message_get_filenames for returning the - * complete list of filenames. + * filenames. See :c:func:`notmuch_message_get_filenames` for + * returning the complete list of filenames. * - * This function returns NULL if it triggers a Xapian exception. + * This function returns ``NULL`` if it triggers a Xapian exception. */ const char * notmuch_message_get_filename (notmuch_message_t *message); /** - * Get all filenames for the email corresponding to 'message'. + * Get all filenames for the email corresponding to ``message``. * - * Returns a notmuch_filenames_t iterator listing all the filenames - * associated with 'message'. These files may not have identical - * content, but each will have the identical Message-ID. + * Returns a :c:type:`notmuch_filenames_t` iterator listing all the + * filenames associated with ``message``. These files may not have + * identical content, but each will have the identical Message-ID. * * Each filename in the iterator is an absolute filename, (the initial - * component will match notmuch_database_get_path() ). + * component will match :c:func:`notmuch_database_get_path`). * - * This function returns NULL if it triggers a Xapian exception. + * This function returns ``NULL`` if it triggers a Xapian exception. */ notmuch_filenames_t * notmuch_message_get_filenames (notmuch_message_t *message); /** - * Re-index the e-mail corresponding to 'message' using the supplied index options + * Re-index the e-mail corresponding to ``message`` using the supplied + * index options * * Returns the status of the re-index operation. (see the return - * codes documented in notmuch_database_index_file) + * codes documented in :c:func:`notmuch_database_index_file`) * * After reindexing, the user should discard the message object passed - * in here by calling notmuch_message_destroy, since it refers to the - * original message, not to the reindexed message. + * in here by calling :c:func:`notmuch_message_destroy`, since it + * refers to the original message, not to the reindexed message. */ notmuch_status_t notmuch_message_reindex (notmuch_message_t *message, @@ -1682,12 +1786,12 @@ typedef enum { } notmuch_message_flag_t; /** - * Get a value of a flag for the email corresponding to 'message'. + * Get a value of a flag for the email corresponding to ``message``. * - * returns FALSE in case of errors. + * returns ``FALSE`` in case of errors. * - * @deprecated Deprecated as of libnotmuch 5.3 (notmuch 0.31). Please - * use notmuch_message_get_flag_st instead. + * :deprecated: Deprecated as of libnotmuch 5.3 (notmuch 0.31). Please + * use :c:func:`notmuch_message_get_flag_st` instead. */ NOTMUCH_DEPRECATED (5, 3) notmuch_bool_t @@ -1695,18 +1799,23 @@ notmuch_message_get_flag (notmuch_message_t *message, notmuch_message_flag_t flag); /** - * Get a value of a flag for the email corresponding to 'message'. + * Get a value of a flag for the email corresponding to ``message``. + * + * :param message: a message object + * :param flag: flag to check + * :param is_set: pointer to boolean to store flag value. * - * @param message a message object - * @param flag flag to check - * @param is_set pointer to boolean to store flag value. + * :return: * - * @retval #NOTMUCH_STATUS_SUCCESS - * @retval #NOTMUCH_STATUS_NULL_POINTER is_set is NULL - * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION Accessing the database - * triggered an exception. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS` + + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: is_set is + * ``NULL`` * - * @since libnotmuch 5.3 (notmuch 0.31) + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: Accessing + * the database triggered an exception. + * + * :since: libnotmuch 5.3 (notmuch 0.31) */ notmuch_status_t notmuch_message_get_flag_st (notmuch_message_t *message, @@ -1714,18 +1823,18 @@ notmuch_message_get_flag_st (notmuch_message_t *message, notmuch_bool_t *is_set); /** - * Set a value of a flag for the email corresponding to 'message'. + * Set a value of a flag for the email corresponding to ``message``. */ void notmuch_message_set_flag (notmuch_message_t *message, notmuch_message_flag_t flag, notmuch_bool_t value); /** - * Get the date of 'message' as a time_t value. + * Get the date of ``message`` as a time_t value. * * For the original textual representation of the Date header from the - * message call notmuch_message_get_header() with a header value of - * "date". + * message call :c:func:`notmuch_message_get_header` with a header + * value of "date". * * Returns 0 in case of error. */ @@ -1733,7 +1842,8 @@ time_t notmuch_message_get_date (notmuch_message_t *message); /** - * Get the value of the specified header from 'message' as a UTF-8 string. + * Get the value of the specified header from ``message`` as a UTF-8 + * string. * * Common headers are stored in the database when the message is * indexed and will be returned from the database. Other headers will @@ -1746,20 +1856,21 @@ notmuch_message_get_date (notmuch_message_t *message); * the message is destroyed). * * Returns an empty string ("") if the message does not contain a - * header line matching 'header'. Returns NULL if any error occurs. + * header line matching ``header``. Returns ``NULL`` if any error + * occurs. */ const char * notmuch_message_get_header (notmuch_message_t *message, const char *header); /** - * Get the tags for 'message', returning a notmuch_tags_t object which - * can be used to iterate over all tags. + * Get the tags for ``message``, returning a :c:type:`notmuch_tags_t` + * object which can be used to iterate over all tags. * * The tags object is owned by the message and as such, will only be * 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; @@ -1778,9 +1889,9 @@ notmuch_message_get_header (notmuch_message_t *message, const char *header); * notmuch_message_destroy (message); * * Note that there's no explicit destructor needed for the - * notmuch_tags_t object. (For consistency, we do provide a - * notmuch_tags_destroy function, but there's no good reason to call - * it if the message is about to be destroyed). + * :c:type:`notmuch_tags_t` object. (For consistency, we do provide a + * :c:func:`notmuch_tags_destroy` function, but there's no good reason + * to call it if the message is about to be destroyed). */ notmuch_tags_t * notmuch_message_get_tags (notmuch_message_t *message); @@ -1793,17 +1904,20 @@ notmuch_message_get_tags (notmuch_message_t *message); /** * Add a tag to the given message. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Tag successfully added to message + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Tag successfully + * added to message * - * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The ``tag`` + * argument is ``NULL`` * - * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long - * (exceeds NOTMUCH_TAG_MAX) + * - :c:enumerator:`NOTMUCH_STATUS_TAG_TOO_LONG`: The length of + * ``tag`` is too long (exceeds :c:macro:`NOTMUCH_TAG_MAX`) * - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only - * mode so message cannot be modified. + * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: + * Database was opened in read-only mode so message cannot be + * modified. */ notmuch_status_t notmuch_message_add_tag (notmuch_message_t *message, const char *tag); @@ -1811,17 +1925,20 @@ notmuch_message_add_tag (notmuch_message_t *message, const char *tag); /** * Remove a tag from the given message. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Tag successfully removed from message + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Tag successfully + * removed from message * - * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The ``tag`` + * argument is ``NULL`` * - * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long - * (exceeds NOTMUCH_TAG_MAX) + * - :c:enumerator:`NOTMUCH_STATUS_TAG_TOO_LONG`: The length of + * ``tag`` is too long (exceeds :c:macro:`NOTMUCH_TAG_MAX`) * - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only - * mode so message cannot be modified. + * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: + * Database was opened in read-only mode so message cannot be + * modified. */ notmuch_status_t notmuch_message_remove_tag (notmuch_message_t *message, const char *tag); @@ -1829,13 +1946,17 @@ notmuch_message_remove_tag (notmuch_message_t *message, const char *tag); /** * Remove all tags from the given message. * - * See notmuch_message_freeze for an example showing how to safely - * replace tag values. + * See :c:func:`notmuch_message_freeze` for an example showing how to + * safely replace tag values. + * + * :return: * - * @retval #NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in - * read-only mode so message cannot be modified. - * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION: an exception was thrown - * accessing the database. + * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: + * Database was opened in read-only mode so message cannot be + * modified. + * + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: An + * exception was thrown accessing the database. */ notmuch_status_t notmuch_message_remove_all_tags (notmuch_message_t *message); @@ -1843,23 +1964,25 @@ notmuch_message_remove_all_tags (notmuch_message_t *message); /** * Add/remove tags according to maildir flags in the message filename(s). * - * This function examines the filenames of 'message' for maildir - * flags, and adds or removes tags on 'message' as follows when these - * flags are present: + * This function examines the filenames of ``message`` for maildir + * 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. * * Flags are identified as trailing components of the filename after a - * sequence of ":2,". + * sequence of ``:2,``. * * If there are multiple filenames associated with this message, the * flag is considered present if it appears in one or more @@ -1868,21 +1991,23 @@ notmuch_message_remove_all_tags (notmuch_message_t *message); * * A client can ensure that notmuch database tags remain synchronized * with maildir flags by calling this function after each call to - * notmuch_database_index_file. See also - * notmuch_message_tags_to_maildir_flags for synchronizing tag changes - * back to maildir flags. + * :c:func:`notmuch_database_index_file`. See also + * :c:func:`notmuch_message_tags_to_maildir_flags` for synchronizing + * tag changes back to maildir flags. */ notmuch_status_t notmuch_message_maildir_flags_to_tags (notmuch_message_t *message); /** - * return TRUE if any filename of 'message' has maildir flag 'flag', - * FALSE otherwise. + * return ``TRUE`` if any filename of ``message`` has maildir flag + * ``flag``, ``FALSE`` otherwise. + * + * Deprecated wrapper for + * :c:func:`notmuch_message_has_maildir_flag_st` * - * Deprecated wrapper for notmuch_message_has_maildir_flag_st + * :return: ``FALSE`` in case of error * - * @returns FALSE in case of error - * @deprecated libnotmuch 5.3 (notmuch 0.31) + * :deprecated: libnotmuch 5.3 (notmuch 0.31) */ NOTMUCH_DEPRECATED (5, 3) notmuch_bool_t @@ -1891,14 +2016,19 @@ notmuch_message_has_maildir_flag (notmuch_message_t *message, char flag); /** * check message for maildir flag * - * @param [in,out] message message to check - * @param [in] flag flag to check for - * @param [out] is_set pointer to boolean + * :param message: message message to check + * :param flag: flag to check for + * :param is_set: pointer to boolean + * + * :return: * - * @retval #NOTMUCH_STATUS_SUCCESS - * @retval #NOTMUCH_STATUS_NULL_POINTER is_set is NULL - * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION Accessing the database - * triggered an exception. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`. + * + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: ``is_set`` is + * ``NULL``. + * + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: Accessing the + * database triggered an exception. */ notmuch_status_t notmuch_message_has_maildir_flag_st (notmuch_message_t *message, @@ -1911,44 +2041,48 @@ notmuch_message_has_maildir_flag_st (notmuch_message_t *message, * Specifically, for each filename corresponding to this message: * * If the filename is not in a maildir directory, do nothing. (A - * maildir directory is determined as a directory named "new" or - * "cur".) Similarly, if the filename has invalid maildir info, - * (repeated or outof-ASCII-order flag characters after ":2,"), then + * maildir directory is determined as a directory named ``new`` or + * ``cur``.) Similarly, if the filename has invalid maildir info, + * (repeated or outof-ASCII-order flag characters after ``:2,``), then * do nothing. * * If the filename is in a maildir directory, rename the file so that - * its filename ends with the sequence ":2," followed by zero or more - * of the following single-character flags (in ASCII order): + * its filename ends with the sequence ``:2,`` followed by zero or + * more of the following single-character flags (in ASCII order): * - * * flag 'D' iff the message has the "draft" tag - * * flag 'F' iff the message has the "flagged" tag - * * flag 'P' iff the message has the "passed" tag - * * flag 'R' iff the message has the "replied" tag - * * flag 'S' iff the message does not have the "unread" tag + * * flag ``D`` iff the message has the "draft" tag + * * flag ``F`` iff the message has the "flagged" tag + * * flag ``P`` iff the message has the "passed" tag + * * flag ``R`` iff the message has the "replied" tag + * * flag ``S`` iff the message does not have the "unread" tag * * Any existing flags unmentioned in the list above will be preserved * in the renaming. * - * Also, if this filename is in a directory named "new", rename it to - * be within the neighboring directory named "cur". + * Also, if this filename is in a directory named ``new``, rename it + * to be within the neighboring directory named ``cur``. * * A client can ensure that maildir filename flags remain synchronized * with notmuch database tags by calling this function after changing - * tags, (after calls to notmuch_message_add_tag, - * notmuch_message_remove_tag, or notmuch_message_freeze/ - * notmuch_message_thaw). See also notmuch_message_maildir_flags_to_tags - * for synchronizing maildir flag changes back to tags. + * tags, (after calls to :c:func:`notmuch_message_add_tag`, + * :c:func:`notmuch_message_remove_tag`, or + * :c:func:`notmuch_message_freeze`/ + * :c:func:`notmuch_message_thaw`). See also + * :c:func:`notmuch_message_maildir_flags_to_tags` for synchronizing + * maildir flag changes back to tags. */ notmuch_status_t notmuch_message_tags_to_maildir_flags (notmuch_message_t *message); /** - * Freeze the current state of 'message' within the database. + * Freeze the current state of ``message`` within the database. * * This means that changes to the message state, (via - * notmuch_message_add_tag, notmuch_message_remove_tag, and - * notmuch_message_remove_all_tags), will not be committed to the - * database until the message is thawed with notmuch_message_thaw. + * :c:func:`notmuch_message_add_tag`, + * :c:func:`notmuch_message_remove_tag`, and + * :c:func:`notmuch_message_remove_all_tags`), will not be committed + * to the database until the message is thawed with + * :c:func:`notmuch_message_thaw`. * * Multiple calls to freeze/thaw are valid and these calls will * "stack". That is there must be as many calls to thaw as to freeze @@ -1956,7 +2090,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); * @@ -1974,44 +2108,48 @@ notmuch_message_tags_to_maildir_flags (notmuch_message_t *message); * Imagine the example above without freeze/thaw and the operation * somehow getting interrupted. This could result in the message being * left with no tags if the interruption happened after - * notmuch_message_remove_all_tags but before notmuch_message_add_tag. + * :c:func:`notmuch_message_remove_all_tags` but before + * :c:func:`notmuch_message_add_tag`. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Message successfully frozen. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Message successfully + * frozen. * - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only - * mode so message cannot be modified. + * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: Database was + * opened in read-only mode so message cannot be modified. */ notmuch_status_t notmuch_message_freeze (notmuch_message_t *message); /** - * Thaw the current 'message', synchronizing any changes that may have - * occurred while 'message' was frozen into the notmuch database. + * Thaw the current ``message``, synchronizing any changes that may have + * occurred while ``message`` was frozen into the notmuch database. * - * See notmuch_message_freeze for an example of how to use this - * function to safely provide tag changes. + * See :c:func:`notmuch_message_freeze` for an example of how to use + * this function to safely provide tag changes. * * Multiple calls to freeze/thaw are valid and these calls with * "stack". That is there must be as many calls to thaw as to freeze * before a message is actually thawed. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least - * its frozen count has successfully been reduced by 1). + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Message + * successfully thawed, (or at least its frozen count has + * successfully been reduced by 1). * - * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw - * an unfrozen message. That is, there have been an unbalanced - * number of calls to notmuch_message_freeze and - * notmuch_message_thaw. + * - :c:enumerator:`NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW`: An + * attempt was made to thaw an unfrozen message. That is, there have + * been an unbalanced number of calls to + * :c:func:`notmuch_message_freeze` and + * :c:func:`notmuch_message_thaw`. */ notmuch_status_t notmuch_message_thaw (notmuch_message_t *message); /** - * Destroy a notmuch_message_t object. + * Destroy a :c:type:`notmuch_message_t` object. * * It can be useful to call this function in the case of a single * query object with many messages in the result, (such as iterating @@ -2023,7 +2161,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 @@ -2031,22 +2169,26 @@ notmuch_message_destroy (notmuch_message_t *message); * add or delete values for, as other subsystems or extensions may * depend on these properties. * - * Please see notmuch-properties(7) for more details about specific + * Please see :any:`notmuch-properties(7)` for more details about specific * properties and conventions around their use. * */ -/**@{*/ + /** * Retrieve the value for a single property key * - * *value* is set to a string owned by the message or NULL if there is + * ``value`` is set to a string owned by the message or ``NULL`` if there is * no such key. In the case of multiple values for the given key, the * first one is retrieved. * - * @returns - * - NOTMUCH_STATUS_NULL_POINTER: *value* may not be NULL. - * - NOTMUCH_STATUS_SUCCESS: No error occurred. - * @since libnotmuch 4.4 (notmuch 0.23) + * :return: + * + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: ``value`` may + * not be ``NULL``. + * + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: No error occurred. + * + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t notmuch_message_get_property (notmuch_message_t *message, const char *key, const char **value); @@ -2054,11 +2196,17 @@ notmuch_message_get_property (notmuch_message_t *message, const char *key, const /** * Add a (key,value) pair to a message * - * @returns - * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character. - * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL. - * - NOTMUCH_STATUS_SUCCESS: No error occurred. - * @since libnotmuch 4.4 (notmuch 0.23) + * :return: + * + * - :c:enumerator:`NOTMUCH_STATUS_ILLEGAL_ARGUMENT`: ``key`` may + * not contain an '=' character. + * + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: Neither + * ``key`` nor ``value`` may be ``NULL``. + * + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: No error occurred. + * + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t notmuch_message_add_property (notmuch_message_t *message, const char *key, const char *value); @@ -2068,11 +2216,17 @@ notmuch_message_add_property (notmuch_message_t *message, const char *key, const * * It is not an error to remove a non-existent (key,value) pair * - * @returns - * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character. - * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL. - * - NOTMUCH_STATUS_SUCCESS: No error occurred. - * @since libnotmuch 4.4 (notmuch 0.23) + * :return: + * + * - :c:enumerator:`NOTMUCH_STATUS_ILLEGAL_ARGUMENT`: ``key`` + * may not contain an '=' character. + * + * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: Neither + * ``key`` nor ``value`` may be ``NULL``. + * + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: No error occurred. + * + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t notmuch_message_remove_property (notmuch_message_t *message, const char *key, const char *value); @@ -2080,15 +2234,19 @@ notmuch_message_remove_property (notmuch_message_t *message, const char *key, co /** * Remove all (key,value) pairs from the given message. * - * @param[in,out] message message to operate on. - * @param[in] key key to delete properties for. If NULL, delete - * properties for all keys - * @returns - * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in - * read-only mode so message cannot be modified. - * - NOTMUCH_STATUS_SUCCESS: No error occurred. + * :param message: message to operate on. + * :param key: key to delete properties for. If ``NULL``, delete + * properties for all keys * - * @since libnotmuch 4.4 (notmuch 0.23) + * :return: + * + * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: + * Database was opened in read-only mode so message cannot be + * modified. + * + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: No error occurred. + * + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t notmuch_message_remove_all_properties (notmuch_message_t *message, const char *key); @@ -2096,15 +2254,18 @@ notmuch_message_remove_all_properties (notmuch_message_t *message, const char *k /** * Remove all (prefix*,value) pairs from the given message * - * @param[in,out] message message to operate on. - * @param[in] prefix delete properties with keys that start with prefix. - * If NULL, delete all properties - * @returns - * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in - * read-only mode so message cannot be modified. - * - NOTMUCH_STATUS_SUCCESS: No error occurred. + * :param message: message to operate on. + * :param prefix: delete properties with keys that start with prefix. + * If ``NULL``, delete all properties + * + * :return: + * + * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: Database was + * opened in read-only mode so message cannot be modified. * - * @since libnotmuch 5.1 (notmuch 0.26) + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: No error occurred. + * + * :since: libnotmuch 5.1 (notmuch 0.26) */ notmuch_status_t notmuch_message_remove_all_properties_with_prefix (notmuch_message_t *message, const char *prefix); @@ -2115,20 +2276,21 @@ notmuch_message_remove_all_properties_with_prefix (notmuch_message_t *message, c typedef struct _notmuch_string_map_iterator notmuch_message_properties_t; /** - * Get the properties for *message*, returning a - * notmuch_message_properties_t object which can be used to iterate - * over all properties. + * Get the properties for ``message``, returning a + * :c:type:`notmuch_message_properties_t` object which can be used to + * iterate over all properties. * - * The notmuch_message_properties_t object is owned by the message and - * as such, will only be valid for as long as the message is valid, - * (which is until the query from which it derived is destroyed). + * The :c:type:`notmuch_message_properties_t` object is owned by the + * message and as such, will only be valid for as long as the message + * is valid, (which is until the query from which it derived is + * destroyed). * - * @param[in] message The message to examine - * @param[in] key key or key prefix - * @param[in] exact if TRUE, require exact match with key. Otherwise - * treat as prefix. + * :param message: The message to examine + * :param key: key or key prefix + * :param 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; * @@ -2140,11 +2302,12 @@ typedef struct _notmuch_string_map_iterator notmuch_message_properties_t; * notmuch_message_properties_destroy (list); * * Note that there's no explicit destructor needed for the - * notmuch_message_properties_t object. (For consistency, we do - * provide a notmuch_message_properities_destroy function, but there's - * no good reason to call it if the message is about to be destroyed). + * :c:type:`notmuch_message_properties_t` object. (For consistency, we + * do provide a :c:func:`notmuch_message_properties_destroy` function, + * but there's no good reason to call it if the message is about to be + * destroyed). * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_message_properties_t * notmuch_message_get_properties (notmuch_message_t *message, const char *key, notmuch_bool_t exact); @@ -2152,49 +2315,52 @@ notmuch_message_get_properties (notmuch_message_t *message, const char *key, not /** * Return the number of properties named "key" belonging to the specific message. * - * @param[in] message The message to examine - * @param[in] key key to count - * @param[out] count The number of matching properties associated with this message. + * :param message: The message to examine + * :param key: key to count + * :param count: The number of matching properties associated with this message. * - * @returns + * :return: * - * NOTMUCH_STATUS_SUCCESS: successful count, possibly some other error. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: successful count, + * possibly some other error. * - * @since libnotmuch 5.2 (notmuch 0.27) + * :since: libnotmuch 5.2 (notmuch 0.27) */ notmuch_status_t notmuch_message_count_properties (notmuch_message_t *message, const char *key, unsigned int *count); /** - * Is the given *properties* iterator pointing at a valid (key,value) + * Is the given ``properties`` iterator pointing at a valid (key,value) * pair. * - * When this function returns TRUE, + * When this function returns ``TRUE``, * notmuch_message_properties_{key,value} will return a valid string, - * and notmuch_message_properties_move_to_next will do what it - * says. Whereas when this function returns FALSE, calling any of - * these functions results in undefined behaviour. + * and :c:func:`notmuch_message_properties_move_to_next` will do what + * it says. Whereas when this function returns ``FALSE``, calling any + * of these functions results in undefined behaviour. * - * See the documentation of notmuch_message_get_properties for example - * code showing how to iterate over a notmuch_message_properties_t - * object. + * See the documentation of :c:func:`notmuch_message_get_properties` + * for example code showing how to iterate over a + * :c:type:`notmuch_message_properties_t` object. * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_bool_t notmuch_message_properties_valid (notmuch_message_properties_t *properties); /** - * Move the *properties* iterator to the next (key,value) pair + * Move the ``properties`` iterator to the next (key,value) pair * - * If *properties* is already pointing at the last pair then the iterator - * will be moved to a point just beyond that last pair, (where - * notmuch_message_properties_valid will return FALSE). + * If ``properties`` is already pointing at the last pair then the + * iterator will be moved to a point just beyond that last pair, + * (where :c:func:`notmuch_message_properties_valid` will return + * ``FALSE``). * - * See the documentation of notmuch_message_get_properties for example - * code showing how to iterate over a notmuch_message_properties_t object. + * See the documentation of :c:func:`notmuch_message_get_properties` + * for example code showing how to iterate over a + * :c:type:`notmuch_message_properties_t` object. * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ void notmuch_message_properties_move_to_next (notmuch_message_properties_t *properties); @@ -2204,7 +2370,7 @@ notmuch_message_properties_move_to_next (notmuch_message_properties_t *propertie * * this could be useful if iterating for a prefix * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ const char * notmuch_message_properties_key (notmuch_message_properties_t *properties); @@ -2214,80 +2380,82 @@ notmuch_message_properties_key (notmuch_message_properties_t *properties); * * This could be useful if iterating for a prefix. * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ const char * notmuch_message_properties_value (notmuch_message_properties_t *properties); /** - * Destroy a notmuch_message_properties_t object. + * Destroy a :c:type:`notmuch_message_properties_t` object. * * It's not strictly necessary to call this function. All memory from - * the notmuch_message_properties_t object will be reclaimed when the - * containing message object is destroyed. + * the :c:type:`notmuch_message_properties_t` object will be reclaimed + * when the containing message object is destroyed. * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ void notmuch_message_properties_destroy (notmuch_message_properties_t *properties); -/**@}*/ - /** - * Is the given 'tags' iterator pointing at a valid tag. + * Is the given ``tags`` iterator pointing at a valid tag. * - * When this function returns TRUE, notmuch_tags_get will return a - * valid string. Whereas when this function returns FALSE, - * notmuch_tags_get will return NULL. + * When this function returns ``TRUE``, :c:func:`notmuch_tags_get` + * will return a valid string. Whereas when this function returns + * ``FALSE``, :c:func:`notmuch_tags_get` will return ``NULL``. * - * See the documentation of notmuch_message_get_tags for example code - * showing how to iterate over a notmuch_tags_t object. + * See the documentation of :c:func:`notmuch_message_get_tags` for + * example code showing how to iterate over a :c:type:`notmuch_tags_t` + * object. */ notmuch_bool_t notmuch_tags_valid (notmuch_tags_t *tags); /** - * Get the current tag from 'tags' as a string. + * Get the current tag from ``tags`` as a string. * - * Note: The returned string belongs to 'tags' and has a lifetime + * Note: The returned string belongs to ``tags`` and has a lifetime * identical to it (and the query to which it ultimately belongs). * - * See the documentation of notmuch_message_get_tags for example code - * showing how to iterate over a notmuch_tags_t object. + * See the documentation of :c:func:`notmuch_message_get_tags` for + * example code showing how to iterate over a :c:type:`notmuch_tags_t` + * object. */ const char * notmuch_tags_get (notmuch_tags_t *tags); /** - * Move the 'tags' iterator to the next tag. + * Move the ``tags`` iterator to the next tag. * - * If 'tags' is already pointing at the last tag then the iterator + * If ``tags`` is already pointing at the last tag then the iterator * will be moved to a point just beyond that last tag, (where - * notmuch_tags_valid will return FALSE and notmuch_tags_get will - * return NULL). + * :c:func:`notmuch_tags_valid` will return ``FALSE`` and + * :c:func:`notmuch_tags_get` will return ``NULL``). * - * See the documentation of notmuch_message_get_tags for example code - * showing how to iterate over a notmuch_tags_t object. + * See the documentation of :c:func:`notmuch_message_get_tags` for + * example code showing how to iterate over a :c:type:`notmuch_tags_t` + * object. */ void notmuch_tags_move_to_next (notmuch_tags_t *tags); /** - * Destroy a notmuch_tags_t object. + * Destroy a :c:type:`notmuch_tags_t` object. * * It's not strictly necessary to call this function. All memory from - * the notmuch_tags_t object will be reclaimed when the containing - * message or query objects are destroyed. + * the :c:type:`notmuch_tags_t` object will be reclaimed when the + * containing message or query objects are destroyed. */ void notmuch_tags_destroy (notmuch_tags_t *tags); /** - * Store an mtime within the database for 'directory'. + * Store an mtime within the database for ``directory``. * - * The 'directory' should be an object retrieved from the database - * with notmuch_database_get_directory for a particular path. + * The ``directory`` should be an object retrieved from the database + * with :c:func:`notmuch_database_get_directory` for a particular + * path. * * The intention is for the caller to use the mtime to allow efficient * identification of new messages to be added to the database. The @@ -2297,28 +2465,29 @@ notmuch_tags_destroy (notmuch_tags_t *tags); * * o Call index_file for all mail files in the directory * - * o Call notmuch_directory_set_mtime with the mtime read from the + * o Call :c:func:`notmuch_directory_set_mtime` with the mtime read from the * filesystem. * * Then, when wanting to check for updates to the directory in the - * future, the client can call notmuch_directory_get_mtime and know - * that it only needs to add files if the mtime of the directory and - * files are newer than the stored timestamp. + * future, the client can call :c:func:`notmuch_directory_get_mtime` + * and know that it only needs to add files if the mtime of the + * directory and files are newer than the stored timestamp. * - * Note: The notmuch_directory_get_mtime function does not allow the - * caller to distinguish a timestamp of 0 from a non-existent - * timestamp. So don't store a timestamp of 0 unless you are - * comfortable with that. + * Note: The :c:func:`notmuch_directory_get_mtime` function does not + * allow the caller to distinguish a timestamp of 0 from a + * non-existent timestamp. So don't store a timestamp of 0 unless you + * are comfortable with that. * - * Return value: + * :return: * - * NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database. + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: mtime successfully + * stored in database. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception - * occurred, mtime not stored. + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian + * exception occurred, mtime not stored. * - * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only - * mode so directory mtime cannot be modified. + * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: Database was + * opened in read-only mode so directory mtime cannot be modified. */ notmuch_status_t notmuch_directory_set_mtime (notmuch_directory_t *directory, @@ -2326,7 +2495,7 @@ notmuch_directory_set_mtime (notmuch_directory_t *directory, /** * Get the mtime of a directory, (as previously stored with - * notmuch_directory_set_mtime). + * :c:func:`notmuch_directory_set_mtime`). * * Returns 0 if no mtime has previously been stored for this * directory. @@ -2335,92 +2504,95 @@ time_t notmuch_directory_get_mtime (notmuch_directory_t *directory); /** - * Get a notmuch_filenames_t iterator listing all the filenames of - * messages in the database within the given directory. + * Get a :c:type:`notmuch_filenames_t` iterator listing all the + * filenames of messages in the database within the given directory. * * The returned filenames will be the basename-entries only (not * complete paths). * - * Returns NULL if it triggers a Xapian exception + * Returns ``NULL`` if it triggers a Xapian exception */ notmuch_filenames_t * notmuch_directory_get_child_files (notmuch_directory_t *directory); /** - * Get a notmuch_filenames_t iterator listing all the filenames of - * sub-directories in the database within the given directory. + * Get a :c:type:`notmuch_filenames_t` iterator listing all the + * filenames of sub-directories in the database within the given + * directory. * * The returned filenames will be the basename-entries only (not * complete paths). * - * Returns NULL if it triggers a Xapian exception + * Returns ``NULL`` if it triggers a Xapian exception */ notmuch_filenames_t * notmuch_directory_get_child_directories (notmuch_directory_t *directory); /** * Delete directory document from the database, and destroy the - * notmuch_directory_t object. Assumes any child directories and files - * have been deleted by the caller. + * :c:type:`notmuch_directory_t` object. Assumes any child directories + * and files have been deleted by the caller. * - * @since libnotmuch 4.3 (notmuch 0.21) + * :since: libnotmuch 4.3 (notmuch 0.21) */ notmuch_status_t notmuch_directory_delete (notmuch_directory_t *directory); /** - * Destroy a notmuch_directory_t object. + * Destroy a :c:type:`notmuch_directory_t` object. */ void notmuch_directory_destroy (notmuch_directory_t *directory); /** - * Is the given 'filenames' iterator pointing at a valid filename. + * Is the given ``filenames`` iterator pointing at a valid filename. * - * When this function returns TRUE, notmuch_filenames_get will return - * a valid string. Whereas when this function returns FALSE, - * notmuch_filenames_get will return NULL. + * When this function returns ``TRUE``, + * :c:func:`notmuch_filenames_get` will return a valid string. Whereas + * when this function returns ``FALSE``, + * :c:func:`notmuch_filenames_get` will return ``NULL``. * - * It is acceptable to pass NULL for 'filenames', in which case this - * function will always return FALSE. + * It is acceptable to pass ``NULL`` for ``filenames``, in which case + * this function will always return ``FALSE``. */ notmuch_bool_t notmuch_filenames_valid (notmuch_filenames_t *filenames); /** - * Get the current filename from 'filenames' as a string. + * Get the current filename from ``filenames`` as a string. * - * Note: The returned string belongs to 'filenames' and has a lifetime - * identical to it (and the directory to which it ultimately belongs). + * Note: The returned string belongs to ``filenames`` and has a + * lifetime identical to it (and the directory to which it ultimately + * belongs). * - * It is acceptable to pass NULL for 'filenames', in which case this - * function will always return NULL. + * It is acceptable to pass ``NULL`` for ``filenames``, in which case + * this function will always return ``NULL``. */ const char * notmuch_filenames_get (notmuch_filenames_t *filenames); /** - * Move the 'filenames' iterator to the next filename. + * Move the ``filenames`` iterator to the next filename. * - * If 'filenames' is already pointing at the last filename then the + * If ``filenames`` is already pointing at the last filename then the * iterator will be moved to a point just beyond that last filename, - * (where notmuch_filenames_valid will return FALSE and - * notmuch_filenames_get will return NULL). + * (where :c:func:`notmuch_filenames_valid` will return ``FALSE`` and + * :c:func:`notmuch_filenames_get` will return ``NULL``). * - * It is acceptable to pass NULL for 'filenames', in which case this + * It is acceptable to pass ``NULL`` for ``filenames``, in which case this * function will do nothing. */ void notmuch_filenames_move_to_next (notmuch_filenames_t *filenames); /** - * Destroy a notmuch_filenames_t object. + * Destroy a :c:type:`notmuch_filenames_t` object. * * It's not strictly necessary to call this function. All memory from - * the notmuch_filenames_t object will be reclaimed when the + * the :c:type:`notmuch_filenames_t` object will be reclaimed when the * containing directory object is destroyed. * - * It is acceptable to pass NULL for 'filenames', in which case this + * It is acceptable to pass ``NULL`` for ``filenames``, in which case this * function will do nothing. */ void @@ -2428,29 +2600,33 @@ notmuch_filenames_destroy (notmuch_filenames_t *filenames); /** - * set config 'key' to 'value' + * set config ``key`` to ``value`` + * + * :return: + * + * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS` * - * @since libnotmuch 4.4 (notmuch 0.23) - * @retval #NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in - * read-only mode so message cannot be modified. - * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION: an exception was thrown - * accessing the database. - * @retval #NOTMUCH_STATUS_SUCCESS + * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: Database was + * opened in read-only mode so message cannot be modified. + * + * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: an exception + * was thrown accessing the database. + * + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t notmuch_database_set_config (notmuch_database_t *db, const char *key, const char *value); /** - * retrieve config item 'key', assign to 'value' + * retrieve config item ``key``, assign to ``value`` * - * keys which have not been previously set with n_d_set_config will - * return an empty string. + * keys which have not been previously set with + * :c:func:`notmuch_database_set_config` will return an empty string. * * return value is allocated by malloc and should be freed by the * caller. * - * @since libnotmuch 4.4 (notmuch 0.23) - * + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t notmuch_database_get_config (notmuch_database_t *db, const char *key, char **value); @@ -2458,16 +2634,16 @@ notmuch_database_get_config (notmuch_database_t *db, const char *key, char **val /** * Create an iterator for all config items with keys matching a given prefix * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_status_t notmuch_database_get_config_list (notmuch_database_t *db, const char *prefix, notmuch_config_list_t **out); /** - * Is 'config_list' iterator valid (i.e. _key, _value, _move_to_next can be called). + * Is ``config_list`` iterator valid (i.e. _key, _value, _move_to_next can be called). * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_bool_t notmuch_config_list_valid (notmuch_config_list_t *config_list); @@ -2476,38 +2652,41 @@ notmuch_config_list_valid (notmuch_config_list_t *config_list); * return key for current config pair * * return value is owned by the iterator, and will be destroyed by the - * next call to notmuch_config_list_key or notmuch_config_list_destroy. + * next call to :c:func:`notmuch_config_list_key` or + * :c:func:`notmuch_config_list_destroy`. * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ const char * notmuch_config_list_key (notmuch_config_list_t *config_list); /** - * return 'value' for current config pair + * return ``value`` for current config pair * * return value is owned by the iterator, and will be destroyed by the - * next call to notmuch_config_list_value or notmuch config_list_destroy + * next call to :c:func:`notmuch_config_list_value` or + * :c:func:`notmuch_config_list_destroy` * - * @since libnotmuch 4.4 (notmuch 0.23) - * @retval NULL for errors + * :return: ``NULL`` for errors + * + * :since: libnotmuch 4.4 (notmuch 0.23) */ const char * notmuch_config_list_value (notmuch_config_list_t *config_list); /** - * move 'config_list' iterator to the next pair + * move ``config_list`` iterator to the next pair * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ void notmuch_config_list_move_to_next (notmuch_config_list_t *config_list); /** - * free any resources held by 'config_list' + * free any resources held by ``config_list`` * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ void notmuch_config_list_destroy (notmuch_config_list_t *config_list); @@ -2538,14 +2717,14 @@ typedef enum { * This value reflects all configuration information given at the time * the database was opened. * - * @param[in] notmuch database - * @param[in] key configuration key + * :param notmuch: database + * :param key: configuration key * - * @since libnotmuch 5.4 (notmuch 0.32) + * :return: ``NULL`` if ``key`` unknown or if no value is known for + * ``key``. Otherwise returns a string owned by notmuch which + * should not be modified nor freed by the caller. * - * @retval NULL if 'key' unknown or if no value is known for - * 'key'. Otherwise returns a string owned by notmuch which should - * not be modified nor freed by the caller. + * :since: libnotmuch 5.4 (notmuch 0.32) */ const char * notmuch_config_get (notmuch_database_t *notmuch, notmuch_config_key_t key); @@ -2556,13 +2735,13 @@ notmuch_config_get (notmuch_database_t *notmuch, notmuch_config_key_t key); * This value reflects all configuration information given at the time * the database was opened. * - * @param[in,out] notmuch database open read/write - * @param[in] key configuration key - * @param[in] val configuration value + * :param notmuch: database open read/write + * :param key: configuration key + * :param val: configuration value * - * @since libnotmuch 5.4 (notmuch 0.32) + * :return: returns any return value for notmuch_database_set_config. * - * @retval returns any return value for notmuch_database_set_config. + * :since: libnotmuch 5.4 (notmuch 0.32) */ notmuch_status_t notmuch_config_set (notmuch_database_t *notmuch, notmuch_config_key_t key, const char *val); @@ -2573,12 +2752,12 @@ notmuch_config_set (notmuch_database_t *notmuch, notmuch_config_key_t key, const * These values reflect all configuration information given at the * time the database was opened. * - * @param[in] notmuch database - * @param[in] key configuration key + * :param notmuch: database + * :param key: configuration key * - * @since libnotmuch 5.4 (notmuch 0.32) + * :return: ``NULL`` in case of error. * - * @retval NULL in case of error. + * :since: libnotmuch 5.4 (notmuch 0.32) */ notmuch_config_values_t * notmuch_config_get_values (notmuch_database_t *notmuch, notmuch_config_key_t key); @@ -2589,12 +2768,12 @@ notmuch_config_get_values (notmuch_database_t *notmuch, notmuch_config_key_t key * These values reflect all configuration information given at the * time the database was opened. * - * @param[in] notmuch database - * @param[in] key configuration key + * :param notmuch: database + * :param key: configuration key * - * @since libnotmuch 5.4 (notmuch 0.32) + * :return: ``NULL`` in case of error. * - * @retval NULL in case of error. + * :since: libnotmuch 5.4 (notmuch 0.32) */ notmuch_config_values_t * notmuch_config_get_values_string (notmuch_database_t *notmuch, const char *key); @@ -2602,12 +2781,12 @@ notmuch_config_get_values_string (notmuch_database_t *notmuch, const char *key); /** * Is the given 'config_values' iterator pointing at a valid element. * - * @param[in] values iterator - * - * @since libnotmuch 5.4 (notmuch 0.32) + * :param values: iterator * - * @retval FALSE if passed a NULL pointer, or the iterator is exhausted. + * :return: ``FALSE`` if passed a ``NULL`` pointer, or the iterator is + * exhausted. * + * :since: libnotmuch 5.4 (notmuch 0.32) */ notmuch_bool_t notmuch_config_values_valid (notmuch_config_values_t *values); @@ -2615,11 +2794,11 @@ notmuch_config_values_valid (notmuch_config_values_t *values); /** * Get the current value from the 'values' iterator * - * @param[in] values iterator + * :param values: iterator * - * @since libnotmuch 5.4 (notmuch 0.32) + * :return: a string with the same lifetime as the iterator * - * @retval a string with the same lifetime as the iterator + * :since: libnotmuch 5.4 (notmuch 0.32) */ const char * notmuch_config_values_get (notmuch_config_values_t *values); @@ -2627,9 +2806,9 @@ notmuch_config_values_get (notmuch_config_values_t *values); /** * Move the 'values' iterator to the next element * - * @param[in,out] values iterator + * :param values: iterator * - * @since libnotmuch 5.4 (notmuch 0.32) + * :since: libnotmuch 5.4 (notmuch 0.32) * */ void @@ -2639,10 +2818,9 @@ notmuch_config_values_move_to_next (notmuch_config_values_t *values); /** * reset the 'values' iterator to the first element * - * @param[in,out] values iterator. A NULL value is ignored. - * - * @since libnotmuch 5.4 (notmuch 0.32) + * :param values: iterator. A ``NULL`` value is ignored. * + * :since: libnotmuch 5.4 (notmuch 0.32) */ void notmuch_config_values_start (notmuch_config_values_t *values); @@ -2651,9 +2829,9 @@ notmuch_config_values_start (notmuch_config_values_t *values); * Destroy a config values iterator, along with any associated * resources. * - * @param[in,out] values iterator + * :param values: iterator * - * @since libnotmuch 5.4 (notmuch 0.32) + * :since: libnotmuch 5.4 (notmuch 0.32) */ void notmuch_config_values_destroy (notmuch_config_values_t *values); @@ -2662,12 +2840,12 @@ notmuch_config_values_destroy (notmuch_config_values_t *values); /** * Returns an iterator for a (key, value) configuration pairs * - * @param[in] notmuch database - * @param[in] prefix prefix for keys. Pass "" for all keys. + * :param notmuch: database + * :param prefix: prefix for keys. Pass "" for all keys. * - * @since libnotmuch 5.4 (notmuch 0.32) + * :return: ``NULL`` in case of error. * - * @retval NULL in case of error. + * :since: libnotmuch 5.4 (notmuch 0.32) */ notmuch_config_pairs_t * notmuch_config_get_pairs (notmuch_database_t *notmuch, @@ -2676,12 +2854,12 @@ notmuch_config_get_pairs (notmuch_database_t *notmuch, /** * Is the given 'config_pairs' iterator pointing at a valid element. * - * @param[in] pairs iterator - * - * @since libnotmuch 5.4 (notmuch 0.32) + * :param pairs: iterator * - * @retval FALSE if passed a NULL pointer, or the iterator is exhausted. + * :return: ``FALSE`` if passed a ``NULL`` pointer, or the iterator is + * exhausted. * + * :since: libnotmuch 5.4 (notmuch 0.32) */ notmuch_bool_t notmuch_config_pairs_valid (notmuch_config_pairs_t *pairs); @@ -2689,10 +2867,9 @@ notmuch_config_pairs_valid (notmuch_config_pairs_t *pairs); /** * Move the 'config_pairs' iterator to the next element * - * @param[in,out] pairs iterator - * - * @since libnotmuch 5.4 (notmuch 0.32) + * :param pairs: iterator * + * :since: libnotmuch 5.4 (notmuch 0.32) */ void notmuch_config_pairs_move_to_next (notmuch_config_pairs_t *pairs); @@ -2700,11 +2877,11 @@ notmuch_config_pairs_move_to_next (notmuch_config_pairs_t *pairs); /** * Get the current key from the 'config_pairs' iterator * - * @param[in] pairs iterator + * :param pairs: iterator * - * @since libnotmuch 5.4 (notmuch 0.32) + * :return: a string with the same lifetime as the iterator * - * @retval a string with the same lifetime as the iterator + * :since: libnotmuch 5.4 (notmuch 0.32) */ const char * notmuch_config_pairs_key (notmuch_config_pairs_t *pairs); @@ -2712,11 +2889,11 @@ notmuch_config_pairs_key (notmuch_config_pairs_t *pairs); /** * Get the current value from the 'config_pairs' iterator * - * @param[in] pairs iterator + * :param pairs: iterator * - * @since libnotmuch 5.4 (notmuch 0.32) + * :return: a string with the same lifetime as the iterator * - * @retval a string with the same lifetime as the iterator + * :since: libnotmuch 5.4 (notmuch 0.32) */ const char * notmuch_config_pairs_value (notmuch_config_pairs_t *pairs); @@ -2725,9 +2902,9 @@ notmuch_config_pairs_value (notmuch_config_pairs_t *pairs); * Destroy a config_pairs iterator, along with any associated * resources. * - * @param[in,out] pairs iterator + * :param pairs: iterator * - * @since libnotmuch 5.4 (notmuch 0.32) + * :since: libnotmuch 5.4 (notmuch 0.32) */ void notmuch_config_pairs_destroy (notmuch_config_pairs_t *pairs); @@ -2738,14 +2915,14 @@ notmuch_config_pairs_destroy (notmuch_config_pairs_t *pairs); * This value reflects all configuration information given at the time * the database was opened. * - * @param[in] notmuch database - * @param[in] key configuration key - * @param[out] val configuration value, converted to Boolean + * :param notmuch: database + * :param key: configuration key + * :param val: configuration value, converted to Boolean * - * @since libnotmuch 5.4 (notmuch 0.32) + * :return: :c:enumerator:`NOTMUCH_STATUS_ILLEGAL_ARGUMENT` if either key is unknown + * or the corresponding value does not convert to Boolean. * - * @retval #NOTMUCH_STATUS_ILLEGAL_ARGUMENT if either key is unknown - * or the corresponding value does not convert to Boolean. + * :since: libnotmuch 5.4 (notmuch 0.32) */ notmuch_status_t notmuch_config_get_bool (notmuch_database_t *notmuch, @@ -2755,7 +2932,7 @@ notmuch_config_get_bool (notmuch_database_t *notmuch, /** * return the path of the config file loaded, if any * - * @retval NULL if no config file was loaded + * :return: ``NULL`` if no config file was loaded */ const char * notmuch_config_path (notmuch_database_t *notmuch); @@ -2765,13 +2942,14 @@ notmuch_config_path (notmuch_database_t *notmuch); * * This object will survive until the database itself is destroyed, * but the caller may also release it earlier with - * notmuch_indexopts_destroy. + * :c:func:`notmuch_indexopts_destroy`. * * This object represents a set of options on how a message can be * added to the index. At the moment it is a featureless stub. * - * @since libnotmuch 5.1 (notmuch 0.26) - * @retval NULL in case of error + * :return: ``NULL`` in case of error + * + * :since: libnotmuch 5.1 (notmuch 0.26) */ notmuch_indexopts_t * notmuch_database_get_default_indexopts (notmuch_database_t *db); @@ -2779,7 +2957,7 @@ notmuch_database_get_default_indexopts (notmuch_database_t *db); /** * Stating a policy about how to decrypt messages. * - * See index.decrypt in notmuch-config(1) for more details. + * See ``index.decrypt`` in :any:`notmuch-config(1)` for more details. */ typedef enum { NOTMUCH_DECRYPT_FALSE, @@ -2791,12 +2969,14 @@ typedef enum { /** * Specify whether to decrypt encrypted parts while indexing. * - * Be aware that the index is likely sufficient to reconstruct the - * cleartext of the message itself, so please ensure that the notmuch - * message index is adequately protected. DO NOT SET THIS FLAG TO TRUE - * without considering the security of your index. + * .. warning:: + * + * Be aware that the index is likely sufficient to reconstruct the + * cleartext of the message itself, so please ensure that the + * notmuch message index is adequately protected. DO NOT SET THIS + * FLAG TO ``TRUE`` without considering the security of your index. * - * @since libnotmuch 5.1 (notmuch 0.26) + * :since: libnotmuch 5.1 (notmuch 0.26) */ notmuch_status_t notmuch_indexopts_set_decrypt_policy (notmuch_indexopts_t *indexopts, @@ -2804,17 +2984,17 @@ notmuch_indexopts_set_decrypt_policy (notmuch_indexopts_t *indexopts, /** * Return whether to decrypt encrypted parts while indexing. - * see notmuch_indexopts_set_decrypt_policy. + * see :c:func:`notmuch_indexopts_set_decrypt_policy`. * - * @since libnotmuch 5.1 (notmuch 0.26) + * :since: libnotmuch 5.1 (notmuch 0.26) */ notmuch_decryption_policy_t notmuch_indexopts_get_decrypt_policy (const notmuch_indexopts_t *indexopts); /** - * Destroy a notmuch_indexopts_t object. + * Destroy a :c:type:`notmuch_indexopts_t` object. * - * @since libnotmuch 5.1 (notmuch 0.26) + * :since: libnotmuch 5.1 (notmuch 0.26) */ void notmuch_indexopts_destroy (notmuch_indexopts_t *options); @@ -2823,11 +3003,10 @@ notmuch_indexopts_destroy (notmuch_indexopts_t *options); /** * interrogate the library for compile time features * - * @since libnotmuch 4.4 (notmuch 0.23) + * :since: libnotmuch 4.4 (notmuch 0.23) */ notmuch_bool_t notmuch_built_with (const char *name); -/**@}*/ #pragma GCC visibility pop -- 2.30.2