[RFC PATCH 4/4] lib: add reStructuredText bling for API documentation in notmuch.h

[Jani Nikula <jani@nikula.org>]

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