* [RFC 5/5] lib: documentation comment overhaul for hawkmoth
2021-10-12 18:51 [RFC 0/5] doc: api docs overhaul Jani Nikula
` (3 preceding siblings ...)
2021-10-12 18:51 ` [RFC 4/5] lib: remove #ifndef __DOXYGEN__ conditions Jani Nikula
@ 2021-10-12 18:51 ` Jani Nikula
2021-10-13 12:17 ` [RFC 0/5] doc: api docs overhaul David Bremner
5 siblings, 0 replies; 17+ messages in thread
From: Jani Nikula @ 2021-10-12 18:51 UTC (permalink / raw)
To: notmuch; +Cc: jani
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_<foo>_t see the various
* notmuch_<foo> 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
- * <em>notmuch-config(5)</em> for more information. The key-value pair
- * overrides the corresponding configuration data stored in the
- * database (see <em>notmuch_database_get_config</em>)
+ * 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 <em>config_path</em> is NULL use the path specified
+ * If ``config_path`` is ``NULL`` use the path specified
*
- * - in environment variable <em>NOTMUCH_CONFIG</em>, if non-empty
+ * - in environment variable ``NOTMUCH_CONFIG``, if non-empty.
*
- * - by <em>XDG_CONFIG_HOME</em>/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 <em>config_path</em> 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
- * <em>config_path</em> and <em>database_path</em>.
+ * :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
^ permalink raw reply related [flat|nested] 17+ messages in thread