unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
From: Jani Nikula <jani@nikula.org>
To: notmuch@notmuchmail.org
Cc: jani@nikula.org
Subject: [RFC 5/5] lib: documentation comment overhaul for hawkmoth
Date: Tue, 12 Oct 2021 21:51:27 +0300	[thread overview]
Message-ID: <20211012185127.198348-6-jani@nikula.org> (raw)
In-Reply-To: <20211012185127.198348-1-jani@nikula.org>

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

  parent reply	other threads:[~2021-10-12 19:29 UTC|newest]

Thread overview: 17+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-10-12 18:51 [RFC 0/5] doc: api docs overhaul Jani Nikula
2021-10-12 18:51 ` [RFC 1/5] doc: replace doxygen with hawkmoth sphinx extension for api docs Jani Nikula
2021-10-13  6:26   ` Tomi Ollila
2021-10-13  9:02     ` Jani Nikula
2021-10-13 13:21   ` David Bremner
2021-10-12 18:51 ` [RFC 2/5] lib: remove enum names from typedefs Jani Nikula
2021-10-13 13:18   ` David Bremner
2021-10-13 13:28     ` Tomi Ollila
2021-10-13 14:04       ` Jani Nikula
2021-10-12 18:51 ` [RFC 3/5] lib: remove commented out NOTMUCH_DEPRECATED() Jani Nikula
2021-10-13 13:19   ` David Bremner
2021-10-13 14:04     ` Jani Nikula
2021-10-12 18:51 ` [RFC 4/5] lib: remove #ifndef __DOXYGEN__ conditions Jani Nikula
2021-10-12 18:51 ` Jani Nikula [this message]
2021-10-13 12:17 ` [RFC 0/5] doc: api docs overhaul David Bremner
2021-10-13 13:41   ` Jani Nikula
2021-10-13 13:59     ` David Bremner

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://notmuchmail.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20211012185127.198348-6-jani@nikula.org \
    --to=jani@nikula.org \
    --cc=notmuch@notmuchmail.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://yhetil.org/notmuch.git/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).