Document notmuch_database_create() using as much bling as possible. This is pretty nice in the output, but probably too excessive in source code. Nonetheless, it's an example of what could be done. --- lib/notmuch.h | 45 +++++++++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 20 deletions(-)
diff --git a/lib/notmuch.h b/lib/notmuch.h index ab01944cb2b0..c3307d5835dd 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -229,38 +229,43 @@ typedef struct _notmuch_param notmuch_param_t; #endif /* __DOXYGEN__ */ /** - * 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. + * This call will 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_add_message. + * (: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_add_message()`. * * 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: + * @param path The ``path`` should be a top-level directory to a + * collection of plain-text email messages (one message per file). * - * NOTMUCH_STATUS_SUCCESS: Successfully created the database. + * @param database Pointer to database. * - * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL. + * @return + * :c:macro:`NOTMUCH_STATUS_SUCCESS`: Successfully created the database. * - * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory. + * :c:macro:`NOTMUCH_STATUS_NULL_POINTER`: The given ``path`` + * argument is ``NULL``. * - * 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:macro:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of memory. * - * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred. + * :c:macro:`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:macro:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian exception + * occurred. */ notmuch_status_t notmuch_database_create (const char *path, notmuch_database_t **database); -- 2.11.0 _______________________________________________ notmuch mailing list notmuch@notmuchmail.org https://notmuchmail.org/mailman/listinfo/notmuch