[RFC 5/5] lib: documentation comment overhaul for hawkmoth
Convert from Doxygen to Hawkmoth, and improve while at it.
- Use rst :param: field lists for parameters.
- Use :deprecated: and :since:.
- Cross-reference all constructs.
- Use preformatted text for TRUE, FALSE, NULL, parameter references,
etc.
Comment changes only.
---
lib/notmuch.h | 1971 +++--
1 file changed, 1075 insertions(+), 896 deletions(-)
diff --git a/lib/notmuch.h b/lib/notmuch.h
index 700e9b7b25c1..9d78ff64d7c7 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -19,13 +19,12 @@
*/
/**
- * @defgroup notmuch The notmuch API
+ * The notmuch API
*
* Not much of an email library, (just index and search)
- *
- * @{
*/
+/**/
#ifndef NOTMUCH_H
#define NOTMUCH_H
@@ -72,23 +71,25 @@ NOTMUCH_BEGIN_DECLS
/**
* Check the version of the notmuch library being compiled against.
*
- * Return true if the library being compiled against is of the
- * specified version or above. For example:
+ * :param major: major version
+ * :param minor: minor version
+ * :param micro: micro version
+ *
+ * :return: true if the library being compiled against is of the
+ * specified version or above.
+ *
+ * For example::
*
- * @code
- * #if LIBNOTMUCH_CHECK_VERSION(3, 1, 0)
- * (code requiring libnotmuch 3.1.0 or above)
- * #endif
- * @endcode
+ * #if LIBNOTMUCH_CHECK_VERSION(3, 1, 0)
+ * // (code requiring libnotmuch 3.1.0 or above)
+ * #endif
*
* LIBNOTMUCH_CHECK_VERSION has been defined since version 3.1.0; to
- * check for versions prior to that, use:
+ * check for versions prior to that, use::
*
- * @code
- * #if !defined(NOTMUCH_CHECK_VERSION)
- * (code requiring libnotmuch prior to 3.1.0)
- * #endif
- * @endcode
+ * #if !defined(NOTMUCH_CHECK_VERSION)
+ * // (code requiring libnotmuch prior to 3.1.0)
+ * #endif
*/
#define LIBNOTMUCH_CHECK_VERSION(major, minor, micro) \
(LIBNOTMUCH_MAJOR_VERSION > (major) ||
\
@@ -104,8 +105,9 @@ typedef int notmuch_bool_t;
/**
* Status codes used for the return values of most functions.
*
- * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function
- * completed without error. Any other value indicates an error.
+ * A zero value (:c:enumerator:`NOTMUCH_STATUS_SUCCESS`) indicates
+ * that the function completed without error. Any other value
+ * indicates an error.
*/
typedef enum {
/**
@@ -124,9 +126,13 @@ typedef enum {
/**
* A Xapian exception occurred.
*
- * @todo We don't really want to expose this lame XAPIAN_EXCEPTION
- * value. Instead we should map to things like DATABASE_LOCKED or
- * whatever.
+ * .. note::
+ *
+ * We don't really want to expose this lame
+ * :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`
+ * value. Instead we should map to things like
+ * :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE` or
+ * whatever.
*/
NOTMUCH_STATUS_XAPIAN_EXCEPTION,
/**
@@ -145,22 +151,22 @@ typedef enum {
*/
NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID,
/**
- * The user erroneously passed a NULL pointer to a notmuch
+ * The user erroneously passed a ``NULL`` pointer to a notmuch
* function.
*/
NOTMUCH_STATUS_NULL_POINTER,
/**
- * A tag value is too long (exceeds NOTMUCH_TAG_MAX).
+ * A tag value is too long (exceeds :c:macro:`NOTMUCH_TAG_MAX`).
*/
NOTMUCH_STATUS_TAG_TOO_LONG,
/**
- * The notmuch_message_thaw function has been called more times
- * than notmuch_message_freeze.
+ * The :c:func:`notmuch_message_thaw` function has been called
+ * more times than :c:func:`notmuch_message_freeze`.
*/
NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW,
/**
- * notmuch_database_end_atomic has been called more times than
- * notmuch_database_begin_atomic.
+ * :c:func:`notmuch_database_end_atomic` has been called more
+ * times than :c:func:`notmuch_database_begin_atomic`.
*/
NOTMUCH_STATUS_UNBALANCED_ATOMIC,
/**
@@ -227,7 +233,7 @@ typedef enum {
} notmuch_status_t;
/**
- * Get a string representation of a notmuch_status_t value.
+ * Get a string representation of a :c:type:`notmuch_status_t` value.
*
* The result is read-only.
*/
@@ -236,61 +242,78 @@ notmuch_status_to_string (notmuch_status_t status);
/* Various opaque data types. For each notmuch__t see the various
* notmuch_ functions below. */
+/** Notmuch opaque database type. */
typedef struct _notmuch_database notmuch_database_t;
+/** Notmuch opaque query type. */
typedef struct _notmuch_query notmuch_query_t;
+/** Notmuch opaque threads type. */
typedef struct _notmuch_threads notmuch_threads_t;
+/** Notmuch opaque thread type. */
typedef struct _notmuch_thread notmuch_thread_t;
+/** Notmuch opaque messages type. */
typedef struct _notmuch_messages notmuch_messages_t;
+/** Notmuch opaque message type. */
typedef struct
[RFC 4/5] lib: remove #ifndef __DOXYGEN__ conditions
These are now unnecessary. Hawkmoth does not require similar
constructs.
---
lib/notmuch.h | 7 ---
1 file changed, 7 deletions(-)
diff --git a/lib/notmuch.h b/lib/notmuch.h
index abbc5ace9d1b..700e9b7b25c1 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -29,8 +29,6 @@
#ifndef NOTMUCH_H
#define NOTMUCH_H
-#ifndef __DOXYGEN__
-
#ifdef __cplusplus
# define NOTMUCH_BEGIN_DECLS extern "C" {
# define NOTMUCH_END_DECLS}
@@ -71,9 +69,6 @@ NOTMUCH_BEGIN_DECLS
#define NOTMUCH_DEPRECATED(major, minor) __attribute__ ((deprecated))
#endif
-
-#endif /* __DOXYGEN__ */
-
/**
* Check the version of the notmuch library being compiled against.
*
@@ -241,7 +236,6 @@ notmuch_status_to_string (notmuch_status_t status);
/* Various opaque data types. For each notmuch__t see the various
* notmuch_ functions below. */
-#ifndef __DOXYGEN__
typedef struct _notmuch_database notmuch_database_t;
typedef struct _notmuch_query notmuch_query_t;
typedef struct _notmuch_threads notmuch_threads_t;
@@ -255,7 +249,6 @@ typedef struct _notmuch_config_list notmuch_config_list_t;
typedef struct _notmuch_config_values notmuch_config_values_t;
typedef struct _notmuch_config_pairs notmuch_config_pairs_t;
typedef struct _notmuch_indexopts notmuch_indexopts_t;
-#endif /* __DOXYGEN__ */
/**
* Create a new, empty notmuch database located at 'path'.
--
2.30.2
___
notmuch mailing list -- notmuch@notmuchmail.org
To unsubscribe send an email to notmuch-le...@notmuchmail.org
[RFC 3/5] lib: remove commented out NOTMUCH_DEPRECATED()
Having comments between the documentation comment and the object being
documented throws Hawkmoth off. Remove the placeholder
NOTMUCH_DEPRECATED() comments.
---
They were added in commit e5f3c3ed5024 ("lib: add stub for
notmuch_database_open_with_config"); maybe the comment markers should
be removed instead?
---
lib/notmuch.h | 2 --
1 file changed, 2 deletions(-)
diff --git a/lib/notmuch.h b/lib/notmuch.h
index ca5878a949bc..abbc5ace9d1b 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -323,7 +323,6 @@ typedef enum {
* config_path="" and error_message=NULL
* @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32)
*/
-/* NOTMUCH_DEPRECATED(5, 4) */
notmuch_status_t
notmuch_database_open (const char *path,
notmuch_database_mode_t mode,
@@ -335,7 +334,6 @@ notmuch_database_open (const char *path,
* @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32)
*
*/
-/* NOTMUCH_DEPRECATED(5, 4) */
notmuch_status_t
notmuch_database_open_verbose (const char *path,
notmuch_database_mode_t mode,
--
2.30.2
___
notmuch mailing list -- notmuch@notmuchmail.org
To unsubscribe send an email to notmuch-le...@notmuchmail.org
[RFC 2/5] lib: remove enum names from typedefs
Given the named enum typedef:
typedef enum _name_t { ... } name_t;
Hawkmoth uses _name_t as the name for documentation. Typedef the
anonymous enum:
typedef enum { ... } name_t;
instead to use name_t. We don't really need the enum names for
anything, and not all of the enum typedefs have them anyway.
---
lib/notmuch.h | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/lib/notmuch.h b/lib/notmuch.h
index 546643e80cbb..ca5878a949bc 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -112,7 +112,7 @@ typedef int notmuch_bool_t;
* A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function
* completed without error. Any other value indicates an error.
*/
-typedef enum _notmuch_status {
+typedef enum {
/**
* No error occurred.
*/
@@ -1678,7 +1678,7 @@ notmuch_message_reindex (notmuch_message_t *message,
/**
* Message flags.
*/
-typedef enum _notmuch_message_flag {
+typedef enum {
NOTMUCH_MESSAGE_FLAG_MATCH,
NOTMUCH_MESSAGE_FLAG_EXCLUDED,
@@ -2524,7 +2524,7 @@ notmuch_config_list_destroy (notmuch_config_list_t
*config_list);
/**
* Configuration keys known to libnotmuch
*/
-typedef enum _notmuch_config_key {
+typedef enum {
NOTMUCH_CONFIG_FIRST,
NOTMUCH_CONFIG_DATABASE_PATH = NOTMUCH_CONFIG_FIRST,
NOTMUCH_CONFIG_MAIL_ROOT,
--
2.30.2
___
notmuch mailing list -- notmuch@notmuchmail.org
To unsubscribe send an email to notmuch-le...@notmuchmail.org
[RFC 1/5] doc: replace doxygen with hawkmoth sphinx extension for api docs
Hawkmoth is a Sphinx extension for incorporating documentation
comments from C source to Sphinx. For Notmuch API documentation needs,
Doxygen is overkill, and Hawkmoth also directly integrates with
Sphinx.
Hawkmoth is currently not packaged for distros, just PyPI. To try this
out on Debian:
$ sudo apt install python3-clang-11 python3-venv
$ python3 -m venv --system-site-packages .venv
$ . .venv/bin/activate
$ pip install hawkmoth
$ ./configure
$ make build-man sphinx-html
Note that Doxygen also depends on libclang; the additional dependency
are the clang python bindings.
Initially, there will be lots of warnings due to documentation comment
formatting. These will be fixed in separate changes.
For more information on Hawkmoth, see
https://github.com/jnikula/hawkmoth
---
configure| 27 ++--
doc/.gitignore | 1 -
doc/Makefile.local | 54 +++-
doc/conf.py | 13 ++
doc/doxygen.cfg | 298 ---
doc/index.rst| 1 +
doc/man3/notmuch.rst | 5 +
7 files changed, 53 insertions(+), 346 deletions(-)
delete mode 100644 doc/doxygen.cfg
create mode 100644 doc/man3/notmuch.rst
diff --git a/configure b/configure
index 6c3a38f1098a..4d6c62645561 100755
--- a/configure
+++ b/configure
@@ -867,17 +867,6 @@ if [ $WITH_EMACS = "1" ]; then
fi
fi
-have_doxygen=0
-if [ $WITH_API_DOCS = "1" ] ; then
-printf "Checking if doxygen is available... "
-if command -v doxygen > /dev/null; then
- printf "Yes.\n"
- have_doxygen=1
-else
- printf "No (so will not install api docs)\n"
-fi
-fi
-
have_ruby_dev=0
if [ $WITH_RUBY = "1" ] ; then
printf "Checking for ruby development files... "
@@ -914,6 +903,15 @@ if [ $WITH_DOCS = "1" ] ; then
else
printf "No (so will not install info pages).\n"
fi
+if [ $WITH_API_DOCS = "1" ] ; then
+ printf "Checking if hawkmoth is available... "
+ if ${python} -m hawkmoth -h > /dev/null 2>&1; then
+ printf "Yes.\n"
+ else
+ printf "No (so will not install api docs)\n"
+ WITH_API_DOCS=0
+ fi
+fi
fi
if [ $WITH_DESKTOP = "1" ]; then
@@ -1372,8 +1370,8 @@ HAVE_MAKEINFO=${have_makeinfo}
# Whether there's an install-info binary available for installing info format
documentation
HAVE_INSTALL_INFO=${have_install_info}
-# Whether there's a doxygen binary available for building api documentation
-HAVE_DOXYGEN=${have_doxygen}
+# Whether there's hawkmoth sphinx extension available for building api
documentation
+WITH_API_DOCS=${WITH_API_DOCS}
# The directory to which desktop files should be installed
desktop_dir = \$(prefix)/share/applications
@@ -1576,6 +1574,9 @@ EOF
if [ $WITH_PYTHON_DOCS = "1" ]; then
echo "tags.add('WITH_PYTHON')"
fi
+if [ $WITH_API_DOCS = "1" ]; then
+echo "tags.add('WITH_API_DOCS')"
+fi
printf "rsti_dir = '%s'\n" "$(cd emacs && pwd -P)"
} > sphinx.config
diff --git a/doc/.gitignore b/doc/.gitignore
index bbb749fabda3..f25d695cccbf 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,3 +1,2 @@
*.pyc
/_build
-/config.dox
diff --git a/doc/Makefile.local b/doc/Makefile.local
index f476d1da46c9..10281a82efff 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -9,26 +9,31 @@ DOCBUILDDIR := $(dir)/_build
# Internal variables.
ALLSPHINXOPTS := $(SPHINXOPTS) $(srcdir)/$(dir)
-APIMAN := $(DOCBUILDDIR)/man/man3/notmuch.3
-DOXYFILE := $(srcdir)/$(dir)/doxygen.cfg
MAN1_RST := $(wildcard $(srcdir)/doc/man1/*.rst)
+ifeq ($(WITH_API_DOCS),1)
+ MAN3_RST := $(wildcard $(srcdir)/doc/man3/*.rst)
+else
+ MAN3_RST :=
+endif
MAN5_RST := $(wildcard $(srcdir)/doc/man5/*.rst)
MAN7_RST := $(wildcard $(srcdir)/doc/man7/*.rst)
-MAN_RST_FILES := $(MAN1_RST) $(MAN5_RST) $(MAN7_RST)
+MAN_RST_FILES := $(MAN1_RST) $(MAN3_RST) $(MAN5_RST) $(MAN7_RST)
ALL_RST_FILES := $(MAN_RST_FILES) $(srcdir)/doc/notmuch-emacs.rst
MAN1_ROFF := $(patsubst
$(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN1_RST:.rst=.1))
+MAN3_ROFF := $(patsubst
$(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN3_RST:.rst=.3))
MAN5_ROFF := $(patsubst
$(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN5_RST:.rst=.5))
MAN7_ROFF := $(patsubst
$(srcdir)/doc/%,$(DOCBUILDDIR)/man/%,$(MAN7_RST:.rst=.7))
-MAN_ROFF_FILES := $(MAN1_ROFF) $(MAN5_ROFF) $(MAN7_ROFF)
+MAN_ROFF_FILES := $(MAN1_ROFF) $(MAN3_ROFF) $(MAN5_ROFF) $(MAN7_ROFF)
MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
MAN1_TEXI := $(patsubst
$(srcdir)/doc/man1/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN1_RST))
+MAN3_TEXI := $(patsubst
$(srcdir)/doc/man3/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN3_RST))
MAN5_TEXI := $(patsubst
$(srcdir)/doc/man5/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN5_RST))
MAN7_TEXI := $(patsubst
$(srcdir)/doc/man7/%.rst,$(DOCBUILDDIR)/texinfo/%.texi,$(MAN7_RST))
-INFO_TEXI_FILES := $(MAN1_TEXI) $(MAN5_TEXI) $(MAN7_TEXI)
+INFO_TEXI_FILES := $(MAN1_TEXI)
[RFC 0/5] doc: api docs overhaul
I have a pet project to incorporate C documentation comments written in reStructuredText to Sphinx based documentation [1]. For Notmuch needs, it replaces Doxygen with something that directly integrates with Sphinx through an extension. I've split the series to configure/build changes, functional code changes in notmuch.h, and comment changes in notmuch.h. With this, the 'make sphinx-html' build includes the API, with cross-references working across the man pages, etc. We didn't have this before. The main downside is that Hawkmoth is not available via distro packaging, only PyPI. BR, Jani. [1] https://github.com/jnikula/hawkmoth Jani Nikula (5): doc: replace doxygen with hawkmoth sphinx extension for api docs lib: remove enum names from typedefs lib: remove commented out NOTMUCH_DEPRECATED() lib: remove #ifndef __DOXYGEN__ conditions lib: documentation comment overhaul for hawkmoth configure| 27 +- doc/.gitignore |1 - doc/Makefile.local | 54 +- doc/conf.py | 13 + doc/doxygen.cfg | 298 --- doc/index.rst|1 + doc/man3/notmuch.rst |5 + lib/notmuch.h| 1986 +++--- 8 files changed, 1131 insertions(+), 1254 deletions(-) delete mode 100644 doc/doxygen.cfg create mode 100644 doc/man3/notmuch.rst -- 2.30.2 ___ notmuch mailing list -- notmuch@notmuchmail.org To unsubscribe send an email to notmuch-le...@notmuchmail.org
