* [RFC 0/5] doc: api docs overhaul
@ 2021-10-12 18:51 Jani Nikula
2021-10-12 18:51 ` [RFC 1/5] doc: replace doxygen with hawkmoth sphinx extension for api docs Jani Nikula
` (5 more replies)
0 siblings, 6 replies; 17+ messages in thread
From: Jani Nikula @ 2021-10-12 18:51 UTC (permalink / raw)
To: notmuch; +Cc: jani
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
^ permalink raw reply [flat|nested] 17+ messages in thread
* [RFC 1/5] doc: replace doxygen with hawkmoth sphinx extension for api docs
2021-10-12 18:51 [RFC 0/5] doc: api docs overhaul Jani Nikula
@ 2021-10-12 18:51 ` Jani Nikula
2021-10-13 6:26 ` Tomi Ollila
2021-10-13 13:21 ` David Bremner
2021-10-12 18:51 ` [RFC 2/5] lib: remove enum names from typedefs Jani Nikula
` (4 subsequent siblings)
5 siblings, 2 replies; 17+ messages in thread
From: Jani Nikula @ 2021-10-12 18:51 UTC (permalink / raw)
To: notmuch; +Cc: jani
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) $(MAN3_TEXI) $(MAN5_TEXI) $(MAN7_TEXI)
ifeq ($(WITH_EMACS),1)
INFO_TEXI_FILES += $(DOCBUILDDIR)/texinfo/notmuch-emacs.texi
endif
@@ -37,7 +42,7 @@ INFO_INFO_FILES := $(INFO_TEXI_FILES:.texi=.info)
.PHONY: sphinx-html sphinx-texinfo sphinx-info
-.PHONY: install-man build-man apidocs install-apidocs
+.PHONY: install-man build-man
%.gz: %
rm -f $@ && gzip --no-name --stdout $^ > $@
@@ -48,13 +53,13 @@ endif
sphinx-html: $(DOCBUILDDIR)/.html.stamp
-$(DOCBUILDDIR)/.html.stamp: $(ALL_RST_FILES)
+$(DOCBUILDDIR)/.html.stamp: $(ALL_RST_FILES) lib/notmuch.h
$(SPHINXBUILD) -b html -d $(DOCBUILDDIR)/html_doctrees $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
touch $@
sphinx-texinfo: $(DOCBUILDDIR)/.texi.stamp
-$(DOCBUILDDIR)/.texi.stamp: $(ALL_RST_FILES)
+$(DOCBUILDDIR)/.texi.stamp: $(ALL_RST_FILES) lib/notmuch.h
$(SPHINXBUILD) -b texinfo -d $(DOCBUILDDIR)/texinfo_doctrees $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
touch $@
@@ -69,10 +74,10 @@ ${MAN_ROFF_FILES}: $(DOCBUILDDIR)/.roff.stamp
# convey to make that a single invocation of this recipe builds all
# of the roff files. This prevents parallel make from starting an
# instance of this recipe for each roff file.
-$(DOCBUILDDIR)/.roff.stamp: ${MAN_RST_FILES}
+$(DOCBUILDDIR)/.roff.stamp: ${MAN_RST_FILES} lib/notmuch.h
ifeq ($(HAVE_SPHINX),1)
$(SPHINXBUILD) -b man -d $(DOCBUILDDIR)/man_doctrees $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
- for section in 1 5 7; do \
+ for section in 1 3 5 7; do \
mkdir -p $(DOCBUILDDIR)/man/man$${section}; \
mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
done
@@ -82,25 +87,6 @@ else
endif
touch $@
-install-man: install-apidocs
-
-ifeq ($(HAVE_DOXYGEN),1)
-MAN_GZIP_FILES += ${APIMAN}.gz
-apidocs: $(APIMAN)
-install-apidocs: ${APIMAN}.gz
- mkdir -p "$(DESTDIR)$(mandir)/man3"
- install -m0644 $(filter %.3.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man3
-
-$(APIMAN): $(dir)/config.dox $(srcdir)/$(dir)/doxygen.cfg $(srcdir)/lib/notmuch.h
- mkdir -p $(DOCBUILDDIR)/man/man3
- doxygen $(DOXYFILE)
- rm -f $(DOCBUILDDIR)/man/man3/_*.3
- perl -pi -e 's/^[.]RI "\\fI/.RI "\\fP/' $(APIMAN)
-else
-apidocs:
-install-apidocs:
-endif
-
# Do not try to build or install man pages if a man page converter is
# not available.
ifeq ($(HAVE_SPHINX),0)
@@ -117,6 +103,10 @@ install-man: ${MAN_GZIP_FILES}
install -m0644 $(filter %.5.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man5
install -m0644 $(filter %.7.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man7
cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz
+ifeq ($(WITH_API_DOCS),1)
+ mkdir -m0755 -p "$(DESTDIR)$(mandir)/man3"
+ install -m0644 $(filter %.3.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man3
+endif
endif
ifneq ($(HAVE_SPHINX)$(HAVE_MAKEINFO),11)
@@ -136,10 +126,6 @@ install-info: build-info
for file in $(INFO_INFO_FILES); do install-info $$file $(DESTDIR)$(infodir)/dir; done
endif
-$(dir)/config.dox: version.stamp
- echo "PROJECT_NAME = \"Notmuch $(VERSION)\"" > $@
- echo "INPUT=${srcdir}/lib/notmuch.h" >> $@
-
CLEAN := $(CLEAN) $(DOCBUILDDIR) $(DOCBUILDDIR)/.roff.stamp $(DOCBUILDDIR)/.texi.stamp
CLEAN := $(CLEAN) $(DOCBUILDDIR)/.html.stamp
-CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc $(dir)/config.dox
+CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES) $(dir)/conf.pyc
diff --git a/doc/conf.py b/doc/conf.py
index 1fbd102bd30c..126bb075be11 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -61,6 +61,12 @@ if not tags.has('WITH_PYTHON'):
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
+if tags.has('WITH_API_DOCS'):
+ extensions.append('hawkmoth')
+ cautodoc_root = os.path.join(location, '..')
+else:
+ exclude_patterns.append('man3/notmuch.rst')
+
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
@@ -172,6 +178,13 @@ man_pages = [
[notmuch_authors], 1),
]
+if tags.has('WITH_API_DOCS'):
+ man_pages += [
+ ('man3/notmuch', 'notmuch',
+ u'notmuch library',
+ [notmuch_authors], 3),
+ ]
+
# If true, show URL addresses after external links.
#man_show_urls = False
diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg
deleted file mode 100644
index 4a022de1ce9e..000000000000
--- a/doc/doxygen.cfg
+++ /dev/null
@@ -1,298 +0,0 @@
-# Doxyfile 1.8.4
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-DOXYFILE_ENCODING = UTF-8
-@INCLUDE = "doc/config.dox"
-PROJECT_NUMBER =
-PROJECT_BRIEF =
-PROJECT_LOGO =
-OUTPUT_DIRECTORY = doc/_build
-CREATE_SUBDIRS = NO
-OUTPUT_LANGUAGE = English
-BRIEF_MEMBER_DESC = YES
-REPEAT_BRIEF = YES
-ABBREVIATE_BRIEF =
-ALWAYS_DETAILED_SEC = NO
-INLINE_INHERITED_MEMB = NO
-FULL_PATH_NAMES = NO
-STRIP_FROM_PATH =
-STRIP_FROM_INC_PATH =
-SHORT_NAMES = NO
-JAVADOC_AUTOBRIEF = YES
-QT_AUTOBRIEF = NO
-MULTILINE_CPP_IS_BRIEF = NO
-INHERIT_DOCS = YES
-SEPARATE_MEMBER_PAGES = NO
-TAB_SIZE = 8
-ALIASES =
-OPTIMIZE_OUTPUT_FOR_C = YES
-OPTIMIZE_OUTPUT_JAVA = NO
-OPTIMIZE_FOR_FORTRAN = NO
-OPTIMIZE_OUTPUT_VHDL = NO
-EXTENSION_MAPPING =
-MARKDOWN_SUPPORT = YES
-AUTOLINK_SUPPORT = YES
-BUILTIN_STL_SUPPORT = NO
-CPP_CLI_SUPPORT = NO
-SIP_SUPPORT = NO
-IDL_PROPERTY_SUPPORT = YES
-DISTRIBUTE_GROUP_DOC = NO
-SUBGROUPING = YES
-INLINE_GROUPED_CLASSES = NO
-INLINE_SIMPLE_STRUCTS = NO
-TYPEDEF_HIDES_STRUCT = YES
-LOOKUP_CACHE_SIZE = 0
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL = NO
-EXTRACT_PRIVATE = NO
-EXTRACT_PACKAGE = NO
-EXTRACT_STATIC = NO
-EXTRACT_LOCAL_CLASSES = YES
-EXTRACT_LOCAL_METHODS = NO
-EXTRACT_ANON_NSPACES = NO
-HIDE_UNDOC_MEMBERS = NO
-HIDE_UNDOC_CLASSES = NO
-HIDE_FRIEND_COMPOUNDS = NO
-HIDE_IN_BODY_DOCS = NO
-INTERNAL_DOCS = NO
-CASE_SENSE_NAMES = YES
-HIDE_SCOPE_NAMES = NO
-SHOW_INCLUDE_FILES = NO
-FORCE_LOCAL_INCLUDES = NO
-INLINE_INFO = YES
-SORT_MEMBER_DOCS = NO
-SORT_BRIEF_DOCS = NO
-SORT_MEMBERS_CTORS_1ST = NO
-SORT_GROUP_NAMES = NO
-SORT_BY_SCOPE_NAME = NO
-STRICT_PROTO_MATCHING = NO
-GENERATE_TODOLIST = NO
-GENERATE_TESTLIST = NO
-GENERATE_BUGLIST = NO
-GENERATE_DEPRECATEDLIST= YES
-ENABLED_SECTIONS =
-MAX_INITIALIZER_LINES = 30
-SHOW_USED_FILES = NO
-SHOW_FILES = NO
-SHOW_NAMESPACES = NO
-FILE_VERSION_FILTER =
-LAYOUT_FILE =
-CITE_BIB_FILES =
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET = YES
-WARNINGS = YES
-WARN_IF_UNDOCUMENTED = YES
-WARN_IF_DOC_ERROR = YES
-WARN_NO_PARAMDOC = NO
-WARN_FORMAT = "$file:$line: $text"
-WARN_LOGFILE =
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT_ENCODING = UTF-8
-FILE_PATTERNS =
-RECURSIVE = NO
-EXCLUDE =
-EXCLUDE_SYMLINKS = NO
-EXCLUDE_PATTERNS =
-EXCLUDE_SYMBOLS =
-EXAMPLE_PATH =
-EXAMPLE_PATTERNS =
-EXAMPLE_RECURSIVE = NO
-IMAGE_PATH =
-INPUT_FILTER =
-FILTER_PATTERNS =
-FILTER_SOURCE_FILES = NO
-FILTER_SOURCE_PATTERNS =
-USE_MDFILE_AS_MAINPAGE =
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER = NO
-INLINE_SOURCES = NO
-STRIP_CODE_COMMENTS = YES
-REFERENCED_BY_RELATION = NO
-REFERENCES_RELATION = NO
-REFERENCES_LINK_SOURCE = YES
-USE_HTAGS = NO
-VERBATIM_HEADERS = NO
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX = NO
-COLS_IN_ALPHA_INDEX = 5
-IGNORE_PREFIX =
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML = NO
-HTML_OUTPUT = html
-HTML_FILE_EXTENSION = .html
-HTML_HEADER =
-HTML_FOOTER =
-HTML_STYLESHEET =
-HTML_EXTRA_STYLESHEET =
-HTML_EXTRA_FILES =
-HTML_COLORSTYLE_HUE = 220
-HTML_COLORSTYLE_SAT = 100
-HTML_COLORSTYLE_GAMMA = 80
-HTML_TIMESTAMP = YES
-HTML_DYNAMIC_SECTIONS = NO
-HTML_INDEX_NUM_ENTRIES = 100
-GENERATE_DOCSET = NO
-DOCSET_FEEDNAME = "Doxygen generated docs"
-DOCSET_BUNDLE_ID = org.doxygen.Project
-DOCSET_PUBLISHER_ID = org.doxygen.Publisher
-DOCSET_PUBLISHER_NAME = Publisher
-GENERATE_HTMLHELP = NO
-CHM_FILE =
-HHC_LOCATION =
-GENERATE_CHI = NO
-CHM_INDEX_ENCODING =
-BINARY_TOC = NO
-TOC_EXPAND = NO
-GENERATE_QHP = NO
-QCH_FILE =
-QHP_NAMESPACE = org.doxygen.Project
-QHP_VIRTUAL_FOLDER = doc
-QHP_CUST_FILTER_NAME =
-QHP_CUST_FILTER_ATTRS =
-QHP_SECT_FILTER_ATTRS =
-QHG_LOCATION =
-GENERATE_ECLIPSEHELP = NO
-ECLIPSE_DOC_ID = org.doxygen.Project
-DISABLE_INDEX = NO
-GENERATE_TREEVIEW = NO
-ENUM_VALUES_PER_LINE = 4
-TREEVIEW_WIDTH = 250
-EXT_LINKS_IN_WINDOW = NO
-FORMULA_FONTSIZE = 10
-FORMULA_TRANSPARENT = YES
-USE_MATHJAX = NO
-MATHJAX_FORMAT = HTML-CSS
-MATHJAX_RELPATH = https://cdn.mathjax.org/mathjax/latest
-MATHJAX_EXTENSIONS =
-MATHJAX_CODEFILE =
-SEARCHENGINE = YES
-SERVER_BASED_SEARCH = NO
-EXTERNAL_SEARCH = NO
-SEARCHENGINE_URL =
-SEARCHDATA_FILE = searchdata.xml
-EXTERNAL_SEARCH_ID =
-EXTRA_SEARCH_MAPPINGS =
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX = NO
-LATEX_OUTPUT = latex
-LATEX_CMD_NAME = latex
-MAKEINDEX_CMD_NAME = makeindex
-COMPACT_LATEX = NO
-PAPER_TYPE = a4
-EXTRA_PACKAGES =
-LATEX_HEADER =
-LATEX_FOOTER =
-LATEX_EXTRA_FILES =
-PDF_HYPERLINKS = YES
-USE_PDFLATEX = YES
-LATEX_BATCHMODE = NO
-LATEX_HIDE_INDICES = NO
-LATEX_SOURCE_CODE = NO
-LATEX_BIB_STYLE = plain
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF = NO
-RTF_OUTPUT = rtf
-COMPACT_RTF = NO
-RTF_HYPERLINKS = NO
-RTF_STYLESHEET_FILE =
-RTF_EXTENSIONS_FILE =
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN = YES
-MAN_OUTPUT = man
-MAN_EXTENSION = .3
-MAN_LINKS = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML = NO
-XML_OUTPUT = xml
-XML_PROGRAMLISTING = YES
-#---------------------------------------------------------------------------
-# configuration options related to the DOCBOOK output
-#---------------------------------------------------------------------------
-GENERATE_DOCBOOK = NO
-DOCBOOK_OUTPUT = docbook
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD = NO
-PERLMOD_LATEX = NO
-PERLMOD_PRETTY = YES
-PERLMOD_MAKEVAR_PREFIX =
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING = YES
-MACRO_EXPANSION = NO
-EXPAND_ONLY_PREDEF = NO
-SEARCH_INCLUDES = NO
-INCLUDE_PATH =
-INCLUDE_FILE_PATTERNS =
-PREDEFINED = __DOXYGEN__
-EXPAND_AS_DEFINED =
-SKIP_FUNCTION_MACROS = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to external references
-#---------------------------------------------------------------------------
-TAGFILES =
-GENERATE_TAGFILE =
-ALLEXTERNALS = NO
-EXTERNAL_GROUPS = NO
-EXTERNAL_PAGES = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS = NO
-HIDE_UNDOC_RELATIONS = YES
-HAVE_DOT = NO
-DOT_NUM_THREADS = 0
-DOT_FONTNAME = Helvetica
-DOT_FONTSIZE = 10
-DOT_FONTPATH =
-CLASS_GRAPH = YES
-COLLABORATION_GRAPH = YES
-GROUP_GRAPHS = YES
-UML_LOOK = NO
-UML_LIMIT_NUM_FIELDS = 10
-TEMPLATE_RELATIONS = NO
-INCLUDE_GRAPH = NO
-INCLUDED_BY_GRAPH = NO
-CALL_GRAPH = NO
-CALLER_GRAPH = NO
-GRAPHICAL_HIERARCHY = NO
-DIRECTORY_GRAPH = NO
-DOT_IMAGE_FORMAT = png
-INTERACTIVE_SVG = NO
-DOT_PATH =
-DOTFILE_DIRS =
-MSCFILE_DIRS =
-DOT_GRAPH_MAX_NODES = 50
-MAX_DOT_GRAPH_DEPTH = 0
-DOT_TRANSPARENT = NO
-DOT_MULTI_TARGETS = YES
-GENERATE_LEGEND = NO
-DOT_CLEANUP = YES
diff --git a/doc/index.rst b/doc/index.rst
index fbdcf779bdca..6d0a31360354 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -27,6 +27,7 @@ Contents:
man7/notmuch-sexp-queries
man1/notmuch-show
man1/notmuch-tag
+ man3/notmuch
python-bindings
Indices and tables
diff --git a/doc/man3/notmuch.rst b/doc/man3/notmuch.rst
new file mode 100644
index 000000000000..05a5bbc41bbb
--- /dev/null
+++ b/doc/man3/notmuch.rst
@@ -0,0 +1,5 @@
+==========
+libnotmuch
+==========
+
+.. c:autodoc:: lib/notmuch.h
--
2.30.2
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [RFC 2/5] lib: remove enum names from typedefs
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-12 18:51 ` Jani Nikula
2021-10-13 13:18 ` David Bremner
2021-10-12 18:51 ` [RFC 3/5] lib: remove commented out NOTMUCH_DEPRECATED() Jani Nikula
` (3 subsequent siblings)
5 siblings, 1 reply; 17+ messages in thread
From: Jani Nikula @ 2021-10-12 18:51 UTC (permalink / raw)
To: notmuch; +Cc: jani
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
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [RFC 3/5] lib: remove commented out NOTMUCH_DEPRECATED()
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-12 18:51 ` [RFC 2/5] lib: remove enum names from typedefs Jani Nikula
@ 2021-10-12 18:51 ` Jani Nikula
2021-10-13 13:19 ` David Bremner
2021-10-12 18:51 ` [RFC 4/5] lib: remove #ifndef __DOXYGEN__ conditions Jani Nikula
` (2 subsequent siblings)
5 siblings, 1 reply; 17+ messages in thread
From: Jani Nikula @ 2021-10-12 18:51 UTC (permalink / raw)
To: notmuch; +Cc: jani
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
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [RFC 4/5] lib: remove #ifndef __DOXYGEN__ conditions
2021-10-12 18:51 [RFC 0/5] doc: api docs overhaul Jani Nikula
` (2 preceding siblings ...)
2021-10-12 18:51 ` [RFC 3/5] lib: remove commented out NOTMUCH_DEPRECATED() Jani Nikula
@ 2021-10-12 18:51 ` Jani Nikula
2021-10-12 18:51 ` [RFC 5/5] lib: documentation comment overhaul for hawkmoth Jani Nikula
2021-10-13 12:17 ` [RFC 0/5] doc: api docs overhaul David Bremner
5 siblings, 0 replies; 17+ messages in thread
From: Jani Nikula @ 2021-10-12 18:51 UTC (permalink / raw)
To: notmuch; +Cc: jani
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_<foo>_t see the various
* notmuch_<foo> 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
^ permalink raw reply related [flat|nested] 17+ messages in thread
* [RFC 5/5] lib: documentation comment overhaul for hawkmoth
2021-10-12 18:51 [RFC 0/5] doc: api docs overhaul Jani Nikula
` (3 preceding siblings ...)
2021-10-12 18:51 ` [RFC 4/5] lib: remove #ifndef __DOXYGEN__ conditions Jani Nikula
@ 2021-10-12 18:51 ` Jani Nikula
2021-10-13 12:17 ` [RFC 0/5] doc: api docs overhaul David Bremner
5 siblings, 0 replies; 17+ messages in thread
From: Jani Nikula @ 2021-10-12 18:51 UTC (permalink / raw)
To: notmuch; +Cc: jani
Convert from Doxygen to Hawkmoth, and improve while at it.
- Use rst :param: field lists for parameters.
- Use :deprecated: and :since:.
- Cross-reference all constructs.
- Use preformatted text for TRUE, FALSE, NULL, parameter references,
etc.
Comment changes only.
---
lib/notmuch.h | 1971 +++++++++++++++++++++++++++----------------------
1 file changed, 1075 insertions(+), 896 deletions(-)
diff --git a/lib/notmuch.h b/lib/notmuch.h
index 700e9b7b25c1..9d78ff64d7c7 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -19,13 +19,12 @@
*/
/**
- * @defgroup notmuch The notmuch API
+ * The notmuch API
*
* Not much of an email library, (just index and search)
- *
- * @{
*/
+/**/
#ifndef NOTMUCH_H
#define NOTMUCH_H
@@ -72,23 +71,25 @@ NOTMUCH_BEGIN_DECLS
/**
* Check the version of the notmuch library being compiled against.
*
- * Return true if the library being compiled against is of the
- * specified version or above. For example:
+ * :param major: major version
+ * :param minor: minor version
+ * :param micro: micro version
+ *
+ * :return: true if the library being compiled against is of the
+ * specified version or above.
+ *
+ * For example::
*
- * @code
- * #if LIBNOTMUCH_CHECK_VERSION(3, 1, 0)
- * (code requiring libnotmuch 3.1.0 or above)
- * #endif
- * @endcode
+ * #if LIBNOTMUCH_CHECK_VERSION(3, 1, 0)
+ * // (code requiring libnotmuch 3.1.0 or above)
+ * #endif
*
* LIBNOTMUCH_CHECK_VERSION has been defined since version 3.1.0; to
- * check for versions prior to that, use:
+ * check for versions prior to that, use::
*
- * @code
- * #if !defined(NOTMUCH_CHECK_VERSION)
- * (code requiring libnotmuch prior to 3.1.0)
- * #endif
- * @endcode
+ * #if !defined(NOTMUCH_CHECK_VERSION)
+ * // (code requiring libnotmuch prior to 3.1.0)
+ * #endif
*/
#define LIBNOTMUCH_CHECK_VERSION(major, minor, micro) \
(LIBNOTMUCH_MAJOR_VERSION > (major) || \
@@ -104,8 +105,9 @@ typedef int notmuch_bool_t;
/**
* Status codes used for the return values of most functions.
*
- * A zero value (NOTMUCH_STATUS_SUCCESS) indicates that the function
- * completed without error. Any other value indicates an error.
+ * A zero value (:c:enumerator:`NOTMUCH_STATUS_SUCCESS`) indicates
+ * that the function completed without error. Any other value
+ * indicates an error.
*/
typedef enum {
/**
@@ -124,9 +126,13 @@ typedef enum {
/**
* A Xapian exception occurred.
*
- * @todo We don't really want to expose this lame XAPIAN_EXCEPTION
- * value. Instead we should map to things like DATABASE_LOCKED or
- * whatever.
+ * .. note::
+ *
+ * We don't really want to expose this lame
+ * :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`
+ * value. Instead we should map to things like
+ * :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE` or
+ * whatever.
*/
NOTMUCH_STATUS_XAPIAN_EXCEPTION,
/**
@@ -145,22 +151,22 @@ typedef enum {
*/
NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID,
/**
- * The user erroneously passed a NULL pointer to a notmuch
+ * The user erroneously passed a ``NULL`` pointer to a notmuch
* function.
*/
NOTMUCH_STATUS_NULL_POINTER,
/**
- * A tag value is too long (exceeds NOTMUCH_TAG_MAX).
+ * A tag value is too long (exceeds :c:macro:`NOTMUCH_TAG_MAX`).
*/
NOTMUCH_STATUS_TAG_TOO_LONG,
/**
- * The notmuch_message_thaw function has been called more times
- * than notmuch_message_freeze.
+ * The :c:func:`notmuch_message_thaw` function has been called
+ * more times than :c:func:`notmuch_message_freeze`.
*/
NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW,
/**
- * notmuch_database_end_atomic has been called more times than
- * notmuch_database_begin_atomic.
+ * :c:func:`notmuch_database_end_atomic` has been called more
+ * times than :c:func:`notmuch_database_begin_atomic`.
*/
NOTMUCH_STATUS_UNBALANCED_ATOMIC,
/**
@@ -227,7 +233,7 @@ typedef enum {
} notmuch_status_t;
/**
- * Get a string representation of a notmuch_status_t value.
+ * Get a string representation of a :c:type:`notmuch_status_t` value.
*
* The result is read-only.
*/
@@ -236,61 +242,78 @@ notmuch_status_to_string (notmuch_status_t status);
/* Various opaque data types. For each notmuch_<foo>_t see the various
* notmuch_<foo> functions below. */
+/** Notmuch opaque database type. */
typedef struct _notmuch_database notmuch_database_t;
+/** Notmuch opaque query type. */
typedef struct _notmuch_query notmuch_query_t;
+/** Notmuch opaque threads type. */
typedef struct _notmuch_threads notmuch_threads_t;
+/** Notmuch opaque thread type. */
typedef struct _notmuch_thread notmuch_thread_t;
+/** Notmuch opaque messages type. */
typedef struct _notmuch_messages notmuch_messages_t;
+/** Notmuch opaque message type. */
typedef struct _notmuch_message notmuch_message_t;
+/** Notmuch opaque tags type. */
typedef struct _notmuch_tags notmuch_tags_t;
+/** Notmuch opaque directory type. */
typedef struct _notmuch_directory notmuch_directory_t;
+/** Notmuch opaque filenames type. */
typedef struct _notmuch_filenames notmuch_filenames_t;
+/** Notmuch opaque config list type. */
typedef struct _notmuch_config_list notmuch_config_list_t;
+/** Notmuch opaque type. */
typedef struct _notmuch_config_values notmuch_config_values_t;
+/** Notmuch opaque config values type. */
typedef struct _notmuch_config_pairs notmuch_config_pairs_t;
+/** Notmuch opaque indexing options type. */
typedef struct _notmuch_indexopts notmuch_indexopts_t;
/**
- * Create a new, empty notmuch database located at 'path'.
+ * Create a new, empty notmuch database located at ``path``.
*
* The path should be a top-level directory to a collection of
* plain-text email messages (one message per file). This call will
- * create a new ".notmuch" directory within 'path' where notmuch will
- * store its data.
+ * create a new ".notmuch" directory within ``path`` where notmuch
+ * will store its data.
*
- * After a successful call to notmuch_database_create, the returned
- * database will be open so the caller should call
- * notmuch_database_destroy when finished with it.
+ * After a successful call to :c:func:`notmuch_database_create`, the
+ * returned database will be open so the caller should call
+ * :c:func:`notmuch_database_destroy` when finished with it.
*
* The database will not yet have any data in it
- * (notmuch_database_create itself is a very cheap function). Messages
- * contained within 'path' can be added to the database by calling
- * notmuch_database_index_file.
+ * (:c:func:`notmuch_database_create` itself is a very cheap
+ * function). Messages contained within ``path`` can be added to the
+ * database by calling :c:func:`notmuch_database_index_file`.
*
* In case of any failure, this function returns an error status and
- * sets *database to NULL (after printing an error message on stderr).
+ * sets ``*database`` to ``NULL`` (after printing an error message on
+ * ``stderr``).
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Successfully created the database.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully created
+ * the database.
*
- * NOTMUCH_STATUS_NULL_POINTER: The given 'path' argument is NULL.
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The given ``path``
+ * argument is ``NULL``.
*
- * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory.
+ * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of memory.
*
- * NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to create the
- * database file (such as permission denied, or file not found,
- * etc.), or the database already exists.
+ * - :c:enumerator:`NOTMUCH_STATUS_FILE_ERROR`: An error occurred
+ * trying to create the database file (such as permission denied,
+ * or file not found, etc.), or the database already exists.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred.
*/
notmuch_status_t
notmuch_database_create (const char *path, notmuch_database_t **database);
/**
- * Like notmuch_database_create, except optionally return an error
- * message. This message is allocated by malloc and should be freed by
- * the caller.
+ * Like :c:func:`notmuch_database_create`, except optionally return an
+ * error message. This message is allocated by malloc and should be
+ * freed by the caller.
*/
notmuch_status_t
notmuch_database_create_verbose (const char *path,
@@ -298,7 +321,7 @@ notmuch_database_create_verbose (const char *path,
char **error_message);
/**
- * Database open mode for notmuch_database_open.
+ * Database open mode for :c:func:`notmuch_database_open`.
*/
typedef enum {
/**
@@ -312,20 +335,20 @@ typedef enum {
} notmuch_database_mode_t;
/**
- * Deprecated alias for notmuch_database_open_with_config with
- * config_path="" and error_message=NULL
- * @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32)
+ * Deprecated alias for :c:func:`notmuch_database_open_with_config`
+ * with config_path="" and error_message=NULL
+ *
+ * :deprecated: Deprecated as of libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_status_t
notmuch_database_open (const char *path,
notmuch_database_mode_t mode,
notmuch_database_t **database);
/**
- * Deprecated alias for notmuch_database_open_with_config with
+ * Deprecated alias for :c:func:`notmuch_database_open_with_config` with
* config_path=""
*
- * @deprecated Deprecated as of libnotmuch 5.4 (notmuch 0.32)
- *
+ * :deprecated: Deprecated as of libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_status_t
notmuch_database_open_verbose (const char *path,
@@ -337,102 +360,100 @@ notmuch_database_open_verbose (const char *path,
* Open an existing notmuch database located at 'database_path', using
* configuration in 'config_path'.
*
- * @param[in] database_path
- * @parblock
- * Path to existing database.
+ * :param database_path:
+ * Path to existing database.
*
- * A notmuch database is a Xapian database containing appropriate
- * metadata.
+ * A notmuch database is a Xapian database containing appropriate
+ * metadata.
*
- * The database should have been created at some time in the past,
- * (not necessarily by this process), by calling
- * notmuch_database_create.
+ * The database should have been created at some time in the past,
+ * (not necessarily by this process), by calling
+ * notmuch_database_create.
*
- * If 'database_path' is NULL, use the location specified
+ * If 'database_path' is ``NULL``, use the location specified
*
- * - in the environment variable NOTMUCH_DATABASE, if non-empty
+ * - in the environment variable ``NOTMUCH_DATABASE``, if non-empty
*
- * - in a configuration file, located as described under 'config_path'
+ * - in a configuration file, located as described under ``config_path``
*
- * - by $XDG_DATA_HOME/notmuch/$PROFILE where XDG_DATA_HOME defaults
- * to "$HOME/.local/share" and PROFILE as as discussed in
- * 'profile'
+ * - by ``$XDG_DATA_HOME/notmuch/$PROFILE`` where
+ * ``XDG_DATA_HOME`` defaults to ``$HOME/.local/share`` and
+ * ``PROFILE`` as as discussed in 'profile'
*
- * If 'database_path' is non-NULL, but does not appear to be a Xapian
- * database, check for a directory '.notmuch/xapian' below
- * 'database_path' (this is the behavior of
- * notmuch_database_open_verbose pre-0.32).
+ * If ``database_path`` is non-``NULL``, but does not appear to be a
+ * Xapian database, check for a directory ``.notmuch/xapian`` below
+ * ``database_path`` (this is the behavior of
+ * :c:func:`notmuch_database_open_verbose` pre-0.32).
*
- * @endparblock
- * @param[in] mode
- * @parblock
- * Mode to open database. Use one of #NOTMUCH_DATABASE_MODE_READ_WRITE
- * or #NOTMUCH_DATABASE_MODE_READ_ONLY
+ * :param mode: Mode to open database. Use one of
+ * :c:enumerator:`NOTMUCH_DATABASE_MODE_READ_WRITE` or
+ * :c:enumerator:`NOTMUCH_DATABASE_MODE_READ_ONLY`
*
- * @endparblock
- * @param[in] config_path
- * @parblock
- * Path to config file.
+ * :param config_path:
+ * Path to config file.
*
- * Config file is key-value, with mandatory sections. See
- * <em>notmuch-config(5)</em> for more information. The key-value pair
- * overrides the corresponding configuration data stored in the
- * database (see <em>notmuch_database_get_config</em>)
+ * Config file is key-value, with mandatory sections. See
+ * :any:`notmuch-config(1)` for more information. The key-value pair
+ * overrides the corresponding configuration data stored in the
+ * database (see :c:func:`notmuch_database_get_config`).
*
- * If <em>config_path</em> is NULL use the path specified
+ * If ``config_path`` is ``NULL`` use the path specified
*
- * - in environment variable <em>NOTMUCH_CONFIG</em>, if non-empty
+ * - in environment variable ``NOTMUCH_CONFIG``, if non-empty.
*
- * - by <em>XDG_CONFIG_HOME</em>/notmuch/ where
- * XDG_CONFIG_HOME defaults to "$HOME/.config".
+ * - by ``XDG_CONFIG_HOME/notmuch/`` where ``XDG_CONFIG_HOME``
+ * defaults to ``$HOME/.config``.
*
- * - by $HOME/.notmuch-config
+ * - by ``$HOME/.notmuch-config``.
*
- * If <em>config_path</em> is "" (empty string) then do not
- * open any configuration file.
- * @endparblock
- * @param[in] profile:
- * @parblock
- * Name of profile (configuration/database variant).
+ * If ``config_path`` is "" (empty string) then do not open any
+ * configuration file.
*
- * If non-NULL, append to the directory / file path determined for
- * <em>config_path</em> and <em>database_path</em>.
+ * :param profile:
+ * Name of profile (configuration/database variant).
*
- * If NULL then use
- * - environment variable NOTMUCH_PROFILE if defined,
- * - otherwise "default" for directories and "" (empty string) for paths.
+ * If non-``NULL``, append to the directory / file path determined
+ * for ``config_path`` and ``database_path``.
*
- * @endparblock
- * @param[out] database
- * @parblock
- * Pointer to database object. May not be NULL.
+ * If ``NULL`` then use
*
- * The caller should call notmuch_database_destroy when finished with
- * this database.
+ * - environment variable ``NOTMUCH_PROFILE`` if defined,
*
- * In case of any failure, this function returns an error status and
- * sets *database to NULL.
+ * - otherwise "default" for directories and "" (empty string) for paths.
+ *
+ * :param database:
+ * Pointer to database object. May not be ``NULL``.
+ *
+ * The caller should call :c:func:`notmuch_database_destroy` when
+ * finished with this database.
+ *
+ * In case of any failure, this function returns an error status and
+ * sets ``*database`` to ``NULL``.
+ *
+ * :param error_message:
+ * If non-``NULL``, store error message from opening the database.
+ * Any such message is allocated by **malloc(3)** and should be freed
+ * by the caller.
*
- * @endparblock
- * @param[out] error_message
- * If non-NULL, store error message from opening the database.
- * Any such message is allocated by \a malloc(3) and should be freed
- * by the caller.
+ * :return:
*
- * @retval NOTMUCH_STATUS_SUCCESS: Successfully opened the database.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully opened the
+ * database.
*
- * @retval NOTMUCH_STATUS_NULL_POINTER: The given \a database
- * argument is NULL.
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The given database
+ * argument is ``NULL``.
*
- * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory.
+ * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of memory.
*
- * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the
- * database or config file (such as permission denied, or file not found,
- * etc.), or the database version is unknown.
+ * - :c:enumerator:`NOTMUCH_STATUS_FILE_ERROR`: An error occurred
+ * trying to open the database or config file (such as permission
+ * denied, or file not found, etc.), or the database version is
+ * unknown.
*
- * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred.
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_status_t
@@ -447,26 +468,31 @@ notmuch_database_open_with_config (const char *database_path,
/**
* Loads configuration from config file, database, and/or defaults
*
- * For description of arguments, @see notmuch_database_open_with_config
+ * For description of arguments, see
+ * :c:func:`notmuch_database_open_with_config`
*
- * @retval NOTMUCH_STATUS_SUCCESS: Successfully loaded configuration.
+ * :return:
*
- * @retval NOTMUCH_STATUS_NO_CONFIG: No config file was loaded. Not fatal.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully loaded
+ * configuration.
*
- * @retval NOTMUCH_STATUS_NO_DATABASE: No config information was
- * loaded from a database. Not fatal.
+ * - :c:enumerator:`NOTMUCH_STATUS_NO_CONFIG`: No config file was
+ * loaded. Not fatal.
*
- * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory.
+ * - :c:enumerator:`NOTMUCH_STATUS_NO_DATABASE`: No config
+ * information was loaded from a database. Not fatal.
*
- * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the
- * database or config file (such as permission denied, or file not found,
- * etc.)
+ * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of memory.
*
- * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred.
+ * - :c:enumerator:`NOTMUCH_STATUS_FILE_ERROR`: An error occurred
+ * trying to open the database or config file (such as permission
+ * denied, or file not found, etc.)
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred.
+ *
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
-
notmuch_status_t
notmuch_database_load_config (const char *database_path,
const char *config_path,
@@ -478,21 +504,27 @@ notmuch_database_load_config (const char *database_path,
* Create a new notmuch database located at 'database_path', using
* configuration in 'config_path'.
*
- * For description of arguments, @see notmuch_database_open_with_config
+ * For description of arguments, see :c:func:`notmuch_database_open_with_config`
+ *
+ * :return:
*
- * @retval NOTMUCH_STATUS_SUCCESS: Successfully created the database.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully
+ * created the database.
*
- * @retval NOTMUCH_STATUS_DATABASE_EXISTS: Database already exists, not created
+ * - :c:enumerator:`NOTMUCH_STATUS_DATABASE_EXISTS`: Database
+ * already exists, not created
*
- * @retval NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory.
+ * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of
+ * memory.
*
- * @retval NOTMUCH_STATUS_FILE_ERROR: An error occurred trying to open the
- * database or config file (such as permission denied, or file not found,
- * etc.)
+ * - :c:enumerator:`NOTMUCH_STATUS_FILE_ERROR`: An error
+ * occurred trying to open the database or config file (such as
+ * permission denied, or file not found, etc.)
*
- * @retval NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred.
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_status_t
@@ -504,7 +536,6 @@ notmuch_database_create_with_config (const char *database_path,
/**
* Retrieve last status string for given database.
- *
*/
const char *
notmuch_database_status_string (const notmuch_database_t *notmuch);
@@ -512,37 +543,39 @@ notmuch_database_status_string (const notmuch_database_t *notmuch);
/**
* Commit changes and close the given notmuch database.
*
- * After notmuch_database_close has been called, calls to other
+ * After :c:func:`notmuch_database_close` has been called, calls to other
* functions on objects derived from this database may either behave
* as if the database had not been closed (e.g., if the required data
* has been cached) or may fail with a
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION. The only further operation
+ * :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`. The only further operation
* permitted on the database itself is to call
- * notmuch_database_destroy.
+ * :c:func:`notmuch_database_destroy`.
*
- * notmuch_database_close can be called multiple times. Later calls
- * have no effect.
+ * :c:func:`notmuch_database_close` can be called multiple times.
+ * Later calls have no effect.
*
- * For writable databases, notmuch_database_close commits all changes
+ * For writable databases, :c:func:`notmuch_database_close` commits all changes
* to disk before closing the database, unless the caller is currently
- * in an atomic section (there was a notmuch_database_begin_atomic
- * without a matching notmuch_database_end_atomic). In this case
- * changes since the last commit are discarded. @see
- * notmuch_database_end_atomic for more information.
+ * in an atomic section (there was a :c:func:`notmuch_database_begin_atomic`
+ * without a matching :c:func:`notmuch_database_end_atomic`). In this case
+ * changes since the last commit are discarded. See
+ * :c:func:`notmuch_database_end_atomic` for more information.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Successfully closed the database.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully closed the
+ * database.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred; the
- * database has been closed but there are no guarantees the
- * changes to the database, if any, have been flushed to disk.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred; the database has been closed but there are
+ * no guarantees the changes to the database, if any, have been
+ * flushed to disk.
*/
notmuch_status_t
notmuch_database_close (notmuch_database_t *database);
/**
- * A callback invoked by notmuch_database_compact to notify the user
+ * A callback invoked by :c:func:`notmuch_database_compact` to notify the user
* of the progress of the compaction process.
*/
typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure);
@@ -551,12 +584,13 @@ typedef void (*notmuch_compact_status_cb_t)(const char *message, void *closure);
* Compact a notmuch database, backing up the original database to the
* given path.
*
- * The database will be opened with NOTMUCH_DATABASE_MODE_READ_WRITE
- * during the compaction process to ensure no writes are made.
+ * The database will be opened with
+ * :c:enumerator:`NOTMUCH_DATABASE_MODE_READ_WRITE` during the
+ * compaction process to ensure no writes are made.
*
- * If the optional callback function 'status_cb' is non-NULL, it will
- * be called with diagnostic and informational messages. The argument
- * 'closure' is passed verbatim to any callback invoked.
+ * If the optional callback function ``status_cb`` is non-``NULL``, it
+ * will be called with diagnostic and informational messages. The
+ * argument ``closure`` is passed verbatim to any callback invoked.
*/
notmuch_status_t
notmuch_database_compact (const char *path,
@@ -568,7 +602,7 @@ notmuch_database_compact (const char *path,
* Like notmuch_database_compact, but take an open database as a
* parameter.
*
- * @since libnnotmuch 5.4 (notmuch 0.32)
+ * :since: libnnotmuch 5.4 (notmuch 0.32)
*/
notmuch_status_t
notmuch_database_compact_db (notmuch_database_t *database,
@@ -580,8 +614,9 @@ notmuch_database_compact_db (notmuch_database_t *database,
* Destroy the notmuch database, closing it if necessary and freeing
* all associated resources.
*
- * Return value as in notmuch_database_close if the database was open;
- * notmuch_database_destroy itself has no failure modes.
+ * Return value as in :c:func:`notmuch_database_close` if the database
+ * was open; :c:func:`notmuch_database_destroy` itself has no failure
+ * modes.
*/
notmuch_status_t
notmuch_database_destroy (notmuch_database_t *database);
@@ -598,7 +633,7 @@ notmuch_database_get_path (notmuch_database_t *database);
/**
* Return the database format version of the given database.
*
- * @retval 0 on error
+ * :return: Database format version, or 0 on error.
*/
unsigned int
notmuch_database_get_version (notmuch_database_t *database);
@@ -606,15 +641,15 @@ notmuch_database_get_version (notmuch_database_t *database);
/**
* Can the database be upgraded to a newer database version?
*
- * If this function returns TRUE, then the caller may call
- * notmuch_database_upgrade to upgrade the database. If the caller
- * does not upgrade an out-of-date database, then some functions may
- * fail with NOTMUCH_STATUS_UPGRADE_REQUIRED. This always returns
- * FALSE for a read-only database because there's no way to upgrade a
- * read-only database.
- *
- * Also returns FALSE if an error occurs accessing the database.
+ * If this function returns ``TRUE``, then the caller may call
+ * :c:func:`notmuch_database_upgrade` to upgrade the database. If the
+ * caller does not upgrade an out-of-date database, then some
+ * functions may fail with
+ * :c:enumerator:`NOTMUCH_STATUS_UPGRADE_REQUIRED`. This always
+ * returns ``FALSE`` for a read-only database because there's no way
+ * to upgrade a read-only database.
*
+ * Also returns ``FALSE`` if an error occurs accessing the database.
*/
notmuch_bool_t
notmuch_database_needs_upgrade (notmuch_database_t *database);
@@ -625,16 +660,17 @@ notmuch_database_needs_upgrade (notmuch_database_t *database);
* This ensures that all current notmuch functionality will be
* available on the database. After opening a database in read-write
* mode, it is recommended that clients check if an upgrade is needed
- * (notmuch_database_needs_upgrade) and if so, upgrade with this
- * function before making any modifications. If
- * notmuch_database_needs_upgrade returns FALSE, this will be a no-op.
+ * (:c:func:`notmuch_database_needs_upgrade`) and if so, upgrade with
+ * this function before making any modifications. If
+ * :c:func:`notmuch_database_needs_upgrade` returns ``FALSE``, this
+ * will be a no-op.
*
* The optional progress_notify callback can be used by the caller to
- * provide progress indication to the user. If non-NULL it will be
- * called periodically with 'progress' as a floating-point value in
+ * provide progress indication to the user. If non-``NULL`` it will be
+ * called periodically with ``progress`` as a floating-point value in
* the range of [0.0 .. 1.0] indicating the progress made so far in
- * the upgrade process. The argument 'closure' is passed verbatim to
- * any callback invoked.
+ * the upgrade process. The argument ``closure`` is passed verbatim
+ * to any callback invoked.
*/
notmuch_status_t
notmuch_database_upgrade (notmuch_database_t *database,
@@ -646,20 +682,21 @@ notmuch_database_upgrade (notmuch_database_t *database,
* Begin an atomic database operation.
*
* Any modifications performed between a successful begin and a
- * notmuch_database_end_atomic will be applied to the database
- * atomically. Note that, unlike a typical database transaction, this
- * only ensures atomicity, not durability; neither begin nor end
- * necessarily flush modifications to disk.
+ * :c:func:`notmuch_database_end_atomic` will be applied to the
+ * database atomically. Note that, unlike a typical database
+ * transaction, this only ensures atomicity, not durability; neither
+ * begin nor end necessarily flush modifications to disk.
*
* Atomic sections may be nested. begin_atomic and end_atomic must
* always be called in pairs.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Successfully entered atomic section.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully
+ * entered atomic section.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
- * atomic section not entered.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred; atomic section not entered.
*/
notmuch_status_t
notmuch_database_begin_atomic (notmuch_database_t *notmuch);
@@ -670,15 +707,16 @@ notmuch_database_begin_atomic (notmuch_database_t *notmuch);
* times, commit the the transaction and all previous (non-cancelled)
* transactions to the database.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Successfully completed atomic section.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully
+ * completed atomic section.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
- * atomic section not ended.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred; atomic section not ended.
*
- * NOTMUCH_STATUS_UNBALANCED_ATOMIC: The database is not currently in
- * an atomic section.
+ * - :c:enumerator:`NOTMUCH_STATUS_UNBALANCED_ATOMIC`: The
+ * database is not currently in an atomic section.
*/
notmuch_status_t
notmuch_database_end_atomic (notmuch_database_t *notmuch);
@@ -693,39 +731,43 @@ notmuch_database_end_atomic (notmuch_database_t *notmuch);
* messages committed in the future will be assigned a modification
* revision > the committed database revision.
*
- * The UUID is a NUL-terminated opaque string that uniquely identifies
- * this database. Two revision numbers are only comparable if they
- * have the same database UUID.
+ * The UUID is a ``NUL``-terminated opaque string that uniquely
+ * identifies this database. Two revision numbers are only comparable
+ * if they have the same database UUID.
*/
unsigned long
notmuch_database_get_revision (notmuch_database_t *notmuch,
const char **uuid);
/**
- * Retrieve a directory object from the database for 'path'.
+ * Retrieve a directory object from the database for ``path``.
*
- * Here, 'path' should be a path relative to the path of 'database'
- * (see notmuch_database_get_path), or else should be an absolute path
- * with initial components that match the path of 'database'.
+ * Here, ``path`` should be a path relative to the path of
+ * ``database`` (see :c:func:`notmuch_database_get_path`), or else
+ * should be an absolute path with initial components that match the
+ * path of ``database``.
*
* If this directory object does not exist in the database, this
- * returns NOTMUCH_STATUS_SUCCESS and sets *directory to NULL.
+ * returns :c:enumerator:`NOTMUCH_STATUS_SUCCESS` and sets
+ * ``*directory`` to ``NULL``.
*
* Otherwise the returned directory object is owned by the database
- * and as such, will only be valid until notmuch_database_destroy is
- * called.
+ * and as such, will only be valid until
+ * :c:func:`notmuch_database_destroy` is called.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Successfully retrieved directory.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successfully retrieved
+ * directory.
*
- * NOTMUCH_STATUS_NULL_POINTER: The given 'directory' argument is NULL.
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The given
+ * ``directory`` argument is ``NULL``.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred;
- * directory not retrieved.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred; directory not retrieved.
*
- * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
- * database to use this function.
+ * - :c:enumerator:`NOTMUCH_STATUS_UPGRADE_REQUIRED`: The caller
+ * must upgrade the database to use this function.
*/
notmuch_status_t
notmuch_database_get_directory (notmuch_database_t *database,
@@ -738,10 +780,10 @@ notmuch_database_get_directory (notmuch_database_t *database,
* ID as the specified file, their indexes will be merged, and this
* new filename will also be associated with the existing message.
*
- * Here, 'filename' should be a path relative to the path of
- * 'database' (see notmuch_database_get_path), or else should be an
- * absolute filename with initial components that match the path of
- * 'database'.
+ * Here, ``filename`` should be a path relative to the path of
+ * ``database`` (see :c:func:`notmuch_database_get_path`), or else
+ * should be an absolute filename with initial components that match
+ * the path of ``database``.
*
* The file should be a single mail message (not a multi-message mbox)
* that is expected to remain at its current location, (since the
@@ -751,46 +793,50 @@ notmuch_database_get_directory (notmuch_database_t *database,
* If another message with the same message ID already exists in the
* database, rather than creating a new message, this adds the search
* terms from the identified file to the existing message's index, and
- * adds 'filename' to the list of filenames known for the message.
+ * adds ``filename`` to the list of filenames known for the message.
*
- * The 'indexopts' parameter can be NULL (meaning, use the indexing
+ * The ``indexopts`` parameter can be ``NULL`` (meaning, use the indexing
* defaults from the database), or can be an explicit choice of
* indexing options that should govern the indexing of this specific
- * 'filename'.
+ * ``filename``.
*
- * If 'message' is not NULL, then, on successful return
- * (NOTMUCH_STATUS_SUCCESS or NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) '*message'
+ * If ``message`` is not ``NULL``, then, on successful return
+ * (:c:enumerator:`NOTMUCH_STATUS_SUCCESS` or
+ * :c:enumerator:`NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID`) ``*message``
* will be initialized to a message object that can be used for things
* such as adding tags to the just-added message. The user should call
- * notmuch_message_destroy when done with the message. On any failure
- * '*message' will be set to NULL.
+ * :c:func:`notmuch_message_destroy` when done with the message. On
+ * any failure ``*message`` will be set to ``NULL``.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Message successfully added to database.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Message successfully
+ * added to database.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
- * message not added.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred, message not added.
*
- * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: Message has the same message
- * ID as another message already in the database. The new
- * filename was successfully added to the message in the database
- * (if not already present) and the existing message is returned.
+ * - :c:enumerator:`NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID`: Message
+ * has the same message ID as another message already in the
+ * database. The new filename was successfully added to the
+ * message in the database (if not already present) and the
+ * existing message is returned.
*
- * NOTMUCH_STATUS_FILE_ERROR: an error occurred trying to open the
- * file, (such as permission denied, or file not found,
- * etc.). Nothing added to the database.
+ * - :c:enumerator:`NOTMUCH_STATUS_FILE_ERROR`: an error occurred
+ * trying to open the file, (such as permission denied, or file
+ * not found, etc.). Nothing added to the database.
*
- * NOTMUCH_STATUS_FILE_NOT_EMAIL: the contents of filename don't look
- * like an email message. Nothing added to the database.
+ * - :c:enumerator:`NOTMUCH_STATUS_FILE_NOT_EMAIL`: the contents of
+ * filename don't look like an email message. Nothing added to the
+ * database.
*
- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
- * mode so no message can be added.
+ * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: Database was
+ * opened in read-only mode so no message can be added.
*
- * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
- * database to use this function.
+ * - :c:enumerator:`NOTMUCH_STATUS_UPGRADE_REQUIRED`: The caller
+ * must upgrade the database to use this function.
*
- * @since libnotmuch 5.1 (notmuch 0.26)
+ * :since: libnotmuch 5.1 (notmuch 0.26)
*/
notmuch_status_t
notmuch_database_index_file (notmuch_database_t *database,
@@ -799,11 +845,11 @@ notmuch_database_index_file (notmuch_database_t *database,
notmuch_message_t **message);
/**
- * Deprecated alias for notmuch_database_index_file called with
- * NULL indexopts.
+ * Deprecated alias for :c:func:`notmuch_database_index_file` called
+ * with ``NULL`` indexopts.
*
- * @deprecated Deprecated as of libnotmuch 5.1 (notmuch 0.26). Please
- * use notmuch_database_index_file instead.
+ * :deprecated: Deprecated as of libnotmuch 5.1 (notmuch 0.26). Please
+ * use :c:func:`notmuch_database_index_file` instead.
*
*/
NOTMUCH_DEPRECATED (5, 1)
@@ -822,23 +868,24 @@ notmuch_database_add_message (notmuch_database_t *database,
* a particular message, the database content for that message will be
* entirely removed.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: The last filename was removed and the
- * message was removed from the database.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: The last filename
+ * was removed and the message was removed from the database.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred,
- * message not removed.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred, message not removed.
*
- * NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: This filename was removed but
- * the message persists in the database with at least one other
- * filename.
+ * - :c:enumerator:`NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID`: This
+ * filename was removed but the message persists in the database
+ * with at least one other filename.
*
- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
- * mode so no message can be removed.
+ * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`:
+ * Database was opened in read-only mode so no message can be
+ * removed.
*
- * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
- * database to use this function.
+ * - :c:enumerator:`NOTMUCH_STATUS_UPGRADE_REQUIRED`: The caller
+ * must upgrade the database to use this function.
*/
notmuch_status_t
notmuch_database_remove_message (notmuch_database_t *database,
@@ -847,25 +894,30 @@ notmuch_database_remove_message (notmuch_database_t *database,
/**
* Find a message with the given message_id.
*
- * If a message with the given message_id is found then, on successful return
- * (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to a message
- * object. The caller should call notmuch_message_destroy when done with the
- * message.
+ * If a message with the given message_id is found then, on successful
+ * return (:c:enumerator:`NOTMUCH_STATUS_SUCCESS`) ``*message`` will
+ * be initialized to a message object. The caller should call
+ * :c:func:`notmuch_message_destroy` when done with the message.
*
- * On any failure or when the message is not found, this function initializes
- * '*message' to NULL. This means, when NOTMUCH_STATUS_SUCCESS is returned, the
- * caller is supposed to check '*message' for NULL to find out whether the
+ * On any failure or when the message is not found, this function
+ * initializes ``*message`` to ``NULL``. This means, when
+ * :c:enumerator:`NOTMUCH_STATUS_SUCCESS` is returned, the caller is
+ * supposed to check ``*message`` for ``NULL`` to find out whether the
* message with the given message_id was found.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Successful return, check '*message'.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successful return,
+ * check ``*message``.
*
- * NOTMUCH_STATUS_NULL_POINTER: The given 'message' argument is NULL
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The given
+ * ``message`` argument is ``NULL``
*
- * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating message object
+ * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of
+ * memory, creating message object
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred
*/
notmuch_status_t
notmuch_database_find_message (notmuch_database_t *database,
@@ -876,27 +928,33 @@ notmuch_database_find_message (notmuch_database_t *database,
* Find a message with the given filename.
*
* If the database contains a message with the given filename then, on
- * successful return (NOTMUCH_STATUS_SUCCESS) '*message' will be initialized to
- * a message object. The caller should call notmuch_message_destroy when done
- * with the message.
+ * successful return (:c:enumerator:`NOTMUCH_STATUS_SUCCESS`)
+ * ``*message`` will be initialized to a message object. The caller
+ * should call :c:func:`notmuch_message_destroy` when done with the
+ * message.
*
- * On any failure or when the message is not found, this function initializes
- * '*message' to NULL. This means, when NOTMUCH_STATUS_SUCCESS is returned, the
- * caller is supposed to check '*message' for NULL to find out whether the
+ * On any failure or when the message is not found, this function
+ * initializes ``*message`` to ``NULL``. This means, when
+ * :c:enumerator:`NOTMUCH_STATUS_SUCCESS` is returned, the caller is
+ * supposed to check ``*message`` for ``NULL`` to find out whether the
* message with the given filename is found.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Successful return, check '*message'
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Successful return,
+ * check ``*message``
*
- * NOTMUCH_STATUS_NULL_POINTER: The given 'message' argument is NULL
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The given
+ * ``message`` argument is ``NULL``
*
- * NOTMUCH_STATUS_OUT_OF_MEMORY: Out of memory, creating the message object
+ * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Out of
+ * memory, creating the message object
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception occurred
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred
*
- * NOTMUCH_STATUS_UPGRADE_REQUIRED: The caller must upgrade the
- * database to use this function.
+ * - :c:enumerator:`NOTMUCH_STATUS_UPGRADE_REQUIRED`: The
+ * caller must upgrade the database to use this function.
*/
notmuch_status_t
notmuch_database_find_message_by_filename (notmuch_database_t *notmuch,
@@ -907,9 +965,10 @@ notmuch_database_find_message_by_filename (notmuch_database_t *notmuch,
* Return a list of all tags found in the database.
*
* This function creates a list of all tags found in the database. The
- * resulting list contains all tags from all messages found in the database.
+ * resulting list contains all tags from all messages found in the
+ * database.
*
- * On error this function returns NULL.
+ * On error this function returns ``NULL``.
*/
notmuch_tags_t *
notmuch_database_get_all_tags (notmuch_database_t *db);
@@ -917,12 +976,18 @@ notmuch_database_get_all_tags (notmuch_database_t *db);
/**
* Reopen an open notmuch database.
*
- * @param [in] db open notmuch database
- * @param [in] mode mode (read only or read-write) for reopened database.
+ * :param db: open notmuch database
+ * :param mode: mode (read only or read-write) for reopened database.
+ *
+ * :return:
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`
*
- * @retval #NOTMUCH_STATUS_SUCCESS
- * @retval #NOTMUCH_STATUS_ILLEGAL_ARGUMENT The passed database was not open.
- * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION A Xapian exception occured
+ * - :c:enumerator:`NOTMUCH_STATUS_ILLEGAL_ARGUMENT`: The passed
+ * database was not open.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occured.
*/
notmuch_status_t
notmuch_database_reopen (notmuch_database_t *db, notmuch_database_mode_t mode);
@@ -930,8 +995,9 @@ notmuch_database_reopen (notmuch_database_t *db, notmuch_database_mode_t mode);
/**
* Create a new query for 'database'.
*
- * Here, 'database' should be an open database, (see
- * notmuch_database_open and notmuch_database_create).
+ * Here, ``database`` should be an open database, (see
+ * :c:func:`notmuch_database_open` and
+ * :c:func:`notmuch_database_create`).
*
* For the query string, we'll document the syntax here more
* completely in the future, but it's likely to be a specialized
@@ -939,18 +1005,19 @@ notmuch_database_reopen (notmuch_database_t *db, notmuch_database_mode_t mode);
*
* https://xapian.org/docs/queryparser.html
*
- * As a special case, passing either a length-zero string, (that is ""),
- * or a string consisting of a single asterisk (that is "*"), will
- * result in a query that returns all messages in the database.
- *
- * See notmuch_query_set_sort for controlling the order of results.
- * See notmuch_query_search_messages and notmuch_query_search_threads
- * to actually execute the query.
+ * As a special case, passing either a length-zero string, (that is
+ * ""), or a string consisting of a single asterisk (that is "*"),
+ * will result in a query that returns all messages in the database.
*
- * User should call notmuch_query_destroy when finished with this
+ * See :c:func:`notmuch_query_set_sort` for controlling the order of
+ * results. See :c:func:`notmuch_query_search_messages` and
+ * :c:func:`notmuch_query_search_threads` to actually execute the
* query.
*
- * Will return NULL if insufficient memory is available.
+ * User should call :c:func:`notmuch_query_destroy` when finished with
+ * this query.
+ *
+ * Will return ``NULL`` if insufficient memory is available.
*/
notmuch_query_t *
notmuch_query_create (notmuch_database_t *database,
@@ -967,7 +1034,7 @@ notmuch_query_create_with_syntax (notmuch_database_t *database,
notmuch_query_syntax_t syntax,
notmuch_query_t **output);
/**
- * Sort values for notmuch_query_set_sort.
+ * Sort values for :c:func:`notmuch_query_set_sort`.
*/
typedef enum {
/**
@@ -989,7 +1056,8 @@ typedef enum {
} notmuch_sort_t;
/**
- * Return the query_string of this query. See notmuch_query_create.
+ * Return the query_string of this query. See
+ * :c:func:`notmuch_query_create`.
*/
const char *
notmuch_query_get_query_string (const notmuch_query_t *query);
@@ -1001,44 +1069,58 @@ notmuch_database_t *
notmuch_query_get_database (const notmuch_query_t *query);
/**
- * Exclude values for notmuch_query_set_omit_excluded. The strange
- * order is to maintain backward compatibility: the old FALSE/TRUE
- * options correspond to the new
- * NOTMUCH_EXCLUDE_FLAG/NOTMUCH_EXCLUDE_TRUE options.
+ * Exclude values for :c:func:`notmuch_query_set_omit_excluded`. The
+ * strange order is to maintain backward compatibility: the old
+ * ``FALSE``/``TRUE`` options correspond to the new
+ * :c:enumerator:`NOTMUCH_EXCLUDE_FLAG`/:c:enumerator:`NOTMUCH_EXCLUDE_TRUE`
+ * options.
*/
typedef enum {
+ /** See :c:func:`notmuch_query_set_omit_excluded`. */
NOTMUCH_EXCLUDE_FLAG,
+ /** See :c:func:`notmuch_query_set_omit_excluded`. */
NOTMUCH_EXCLUDE_TRUE,
+ /** See :c:func:`notmuch_query_set_omit_excluded`. */
NOTMUCH_EXCLUDE_FALSE,
+ /** See :c:func:`notmuch_query_set_omit_excluded`. */
NOTMUCH_EXCLUDE_ALL
} notmuch_exclude_t;
/**
* Specify whether to omit excluded results or simply flag them. By
- * default, this is set to TRUE.
- *
- * If set to TRUE or ALL, notmuch_query_search_messages will omit excluded
- * messages from the results, and notmuch_query_search_threads will omit
- * threads that match only in excluded messages. If set to TRUE,
- * notmuch_query_search_threads will include all messages in threads that
- * match in at least one non-excluded message. Otherwise, if set to ALL,
- * notmuch_query_search_threads will omit excluded messages from all threads.
- *
- * If set to FALSE or FLAG then both notmuch_query_search_messages and
- * notmuch_query_search_threads will return all matching
- * messages/threads regardless of exclude status. If set to FLAG then
- * the exclude flag will be set for any excluded message that is
- * returned by notmuch_query_search_messages, and the thread counts
- * for threads returned by notmuch_query_search_threads will be the
- * number of non-excluded messages/matches. Otherwise, if set to
- * FALSE, then the exclude status is completely ignored.
+ * default, this is set to :c:enumerator:`NOTMUCH_EXCLUDE_TRUE`.
+ *
+ * If set to :c:enumerator:`NOTMUCH_EXCLUDE_TRUE` or
+ * :c:enumerator:`NOTMUCH_EXCLUDE_ALL`,
+ * :c:func:`notmuch_query_search_messages` will omit excluded messages
+ * from the results, and :c:func:`notmuch_query_search_threads` will
+ * omit threads that match only in excluded messages. If set to
+ * :c:enumerator:`NOTMUCH_EXCLUDE_TRUE`,
+ * :c:func:`notmuch_query_search_threads` will include all messages in
+ * threads that match in at least one non-excluded message.
+ * Otherwise, if set to :c:enumerator:`NOTMUCH_EXCLUDE_ALL`,
+ * :c:func:`notmuch_query_search_threads` will omit excluded messages
+ * from all threads.
+ *
+ * If set to :c:enumerator:`NOTMUCH_EXCLUDE_FALSE` or
+ * :c:enumerator:`NOTMUCH_EXCLUDE_FLAG` then both
+ * :c:func:`notmuch_query_search_messages` and
+ * :c:func:`notmuch_query_search_threads` will return all matching
+ * messages/threads regardless of exclude status. If set to
+ * :c:enumerator:`NOTMUCH_EXCLUDE_FLAG` then the exclude flag will be
+ * set for any excluded message that is returned by
+ * :c:func:`notmuch_query_search_messages`, and the thread counts for
+ * threads returned by :c:func:`notmuch_query_search_threads` will be
+ * the number of non-excluded messages/matches. Otherwise, if set to
+ * :c:enumerator:`NOTMUCH_EXCLUDE_FALSE`, then the exclude status is
+ * completely ignored.
*
* The performance difference when calling
- * notmuch_query_search_messages should be relatively small (and both
- * should be very fast). However, in some cases,
- * notmuch_query_search_threads is very much faster when omitting
- * excluded messages as it does not need to construct the threads that
- * only match in excluded messages.
+ * :c:func:`notmuch_query_search_messages` should be relatively small
+ * (and both should be very fast). However, in some cases,
+ * :c:func:`notmuch_query_search_threads` is very much faster when
+ * omitting excluded messages as it does not need to construct the
+ * threads that only match in excluded messages.
*/
void
notmuch_query_set_omit_excluded (notmuch_query_t *query,
@@ -1052,7 +1134,7 @@ notmuch_query_set_sort (notmuch_query_t *query, notmuch_sort_t sort);
/**
* Return the sort specified for this query. See
- * notmuch_query_set_sort.
+ * :c:func:`notmuch_query_set_sort`.
*/
notmuch_sort_t
notmuch_query_get_sort (const notmuch_query_t *query);
@@ -1062,26 +1144,29 @@ notmuch_query_get_sort (const notmuch_query_t *query);
* This exclusion will be ignored if this tag appears explicitly in
* the query.
*
- * @returns
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: excluded was added successfully.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: excluded was added
+ * successfully.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred.
- * Most likely a problem lazily parsing the query string.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: a Xapian
+ * exception occurred. Most likely a problem lazily parsing the
+ * query string.
*
- * NOTMUCH_STATUS_IGNORED: tag is explicitly present in the query, so
- * not excluded.
+ * - :c:enumerator:`NOTMUCH_STATUS_IGNORED`: tag is explicitly
+ * present in the query, so not excluded.
*/
notmuch_status_t
notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
/**
- * Execute a query for threads, returning a notmuch_threads_t object
- * which can be used to iterate over the results. The returned threads
- * object is owned by the query and as such, will only be valid until
- * notmuch_query_destroy.
+ * Execute a query for threads, returning a
+ * :c:type:`notmuch_threads_t` object which can be used to iterate
+ * over the results. The returned threads object is owned by the query
+ * and as such, will only be valid until
+ * :c:func:`notmuch_query_destroy`.
*
- * Typical usage might be:
+ * Typical usage might be::
*
* notmuch_query_t *query;
* notmuch_threads_t *threads;
@@ -1103,28 +1188,28 @@ notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
* notmuch_query_destroy (query);
*
* Note: If you are finished with a thread before its containing
- * query, you can call notmuch_thread_destroy to clean up some memory
- * sooner (as in the above example). Otherwise, if your thread objects
- * are long-lived, then you don't need to call notmuch_thread_destroy
- * and all the memory will still be reclaimed when the query is
- * destroyed.
+ * query, you can call :c:func:`notmuch_thread_destroy` to clean up
+ * some memory sooner (as in the above example). Otherwise, if your
+ * thread objects are long-lived, then you don't need to call
+ * :c:func:`notmuch_thread_destroy` and all the memory will still be
+ * reclaimed when the query is destroyed.
*
* Note that there's no explicit destructor needed for the
- * notmuch_threads_t object. (For consistency, we do provide a
- * notmuch_threads_destroy function, but there's no good reason
- * to call it if the query is about to be destroyed).
+ * :c:type:`notmuch_threads_t` object. (For consistency, we do provide
+ * a :c:func:`notmuch_threads_destroy` function, but there's no good
+ * reason to call it if the query is about to be destroyed).
*
- * @since libnotmuch 5.0 (notmuch 0.25)
+ * :since: libnotmuch 5.0 (notmuch 0.25)
*/
notmuch_status_t
notmuch_query_search_threads (notmuch_query_t *query,
notmuch_threads_t **out);
/**
- * Deprecated alias for notmuch_query_search_threads.
+ * Deprecated alias for :c:func:`notmuch_query_search_threads`.
*
- * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please
- * use notmuch_query_search_threads instead.
+ * :deprecated: Deprecated as of libnotmuch 5 (notmuch 0.25). Please
+ * use :c:func:`notmuch_query_search_threads` instead.
*
*/
NOTMUCH_DEPRECATED (5, 0)
@@ -1132,12 +1217,13 @@ notmuch_status_t
notmuch_query_search_threads_st (notmuch_query_t *query, notmuch_threads_t **out);
/**
- * Execute a query for messages, returning a notmuch_messages_t object
- * which can be used to iterate over the results. The returned
- * messages object is owned by the query and as such, will only be
- * valid until notmuch_query_destroy.
+ * Execute a query for messages, returning a
+ * :c:type:`notmuch_messages_t` object which can be used to iterate
+ * over the results. The returned messages object is owned by the
+ * query and as such, will only be valid until
+ * :c:func:`notmuch_query_destroy`.
*
- * Typical usage might be:
+ * Typical usage might be::
*
* notmuch_query_t *query;
* notmuch_messages_t *messages;
@@ -1157,29 +1243,29 @@ notmuch_query_search_threads_st (notmuch_query_t *query, notmuch_threads_t **out
* notmuch_query_destroy (query);
*
* Note: If you are finished with a message before its containing
- * query, you can call notmuch_message_destroy to clean up some memory
- * sooner (as in the above example). Otherwise, if your message
- * objects are long-lived, then you don't need to call
- * notmuch_message_destroy and all the memory will still be reclaimed
- * when the query is destroyed.
+ * query, you can call :c:func:`notmuch_message_destroy` to clean up
+ * some memory sooner (as in the above example). Otherwise, if your
+ * message objects are long-lived, then you don't need to call
+ * :c:func:`notmuch_message_destroy` and all the memory will still be
+ * reclaimed when the query is destroyed.
*
* Note that there's no explicit destructor needed for the
- * notmuch_messages_t object. (For consistency, we do provide a
- * notmuch_messages_destroy function, but there's no good
- * reason to call it if the query is about to be destroyed).
+ * :c:type:`notmuch_messages_t` object. (For consistency, we do
+ * provide a :c:func:`notmuch_messages_destroy` function, but there's
+ * no good reason to call it if the query is about to be destroyed).
*
- * If a Xapian exception occurs this function will return NULL.
+ * If a Xapian exception occurs this function will return ``NULL``.
*
- * @since libnotmuch 5 (notmuch 0.25)
+ * :since: libnotmuch 5 (notmuch 0.25)
*/
notmuch_status_t
notmuch_query_search_messages (notmuch_query_t *query,
notmuch_messages_t **out);
/**
- * Deprecated alias for notmuch_query_search_messages
+ * Deprecated alias for :c:func:`notmuch_query_search_messages`
*
- * @deprecated Deprecated as of libnotmuch 5 (notmuch 0.25). Please use
- * notmuch_query_search_messages instead.
+ * :deprecated: Deprecated as of libnotmuch 5 (notmuch 0.25). Please
+ * use :c:func:`notmuch_query_search_messages` instead.
*
*/
@@ -1189,66 +1275,71 @@ notmuch_query_search_messages_st (notmuch_query_t *query,
notmuch_messages_t **out);
/**
- * Destroy a notmuch_query_t along with any associated resources.
+ * Destroy a :c:type:`notmuch_query_t` along with any associated
+ * resources.
*
- * This will in turn destroy any notmuch_threads_t and
- * notmuch_messages_t objects generated by this query, (and in
- * turn any notmuch_thread_t and notmuch_message_t objects generated
- * from those results, etc.), if such objects haven't already been
- * destroyed.
+ * This will in turn destroy any :c:type:`notmuch_threads_t` and
+ * :c:type:`notmuch_messages_t` objects generated by this query, (and
+ * in turn any :c:type:`notmuch_thread_t` and
+ * :c:type:`notmuch_message_t` objects generated from those results,
+ * etc.), if such objects haven't already been destroyed.
*/
void
notmuch_query_destroy (notmuch_query_t *query);
/**
- * Is the given 'threads' iterator pointing at a valid thread.
+ * Is the given ``threads`` iterator pointing at a valid thread.
*
- * When this function returns TRUE, notmuch_threads_get will return a
- * valid object. Whereas when this function returns FALSE,
- * notmuch_threads_get will return NULL.
+ * When this function returns ``TRUE``, :c:func:`notmuch_threads_get`
+ * will return a valid object. Whereas when this function returns
+ * ``FALSE``, :c:func:`notmuch_threads_get` will return ``NULL``.
*
- * If passed a NULL pointer, this function returns FALSE
+ * If passed a ``NULL`` pointer, this function returns ``FALSE``
*
- * See the documentation of notmuch_query_search_threads for example
- * code showing how to iterate over a notmuch_threads_t object.
+ * See the documentation of :c:func:`notmuch_query_search_threads` for
+ * example code showing how to iterate over a
+ * :c:type:`notmuch_threads_t` object.
*/
notmuch_bool_t
notmuch_threads_valid (notmuch_threads_t *threads);
/**
- * Get the current thread from 'threads' as a notmuch_thread_t.
+ * Get the current thread from ``threads`` as a
+ * :c:type:`notmuch_thread_t`.
*
- * Note: The returned thread belongs to 'threads' and has a lifetime
+ * Note: The returned thread belongs to ``threads`` and has a lifetime
* identical to it (and the query to which it belongs).
*
- * See the documentation of notmuch_query_search_threads for example
- * code showing how to iterate over a notmuch_threads_t object.
+ * See the documentation of :c:func:`notmuch_query_search_threads` for
+ * example code showing how to iterate over a
+ * :c:type:`notmuch_threads_t` object.
*
* If an out-of-memory situation occurs, this function will return
- * NULL.
+ * ``NULL``.
*/
notmuch_thread_t *
notmuch_threads_get (notmuch_threads_t *threads);
/**
- * Move the 'threads' iterator to the next thread.
+ * Move the ``threads`` iterator to the next thread.
*
- * If 'threads' is already pointing at the last thread then the
+ * If ``threads`` is already pointing at the last thread then the
* iterator will be moved to a point just beyond that last thread,
- * (where notmuch_threads_valid will return FALSE and
- * notmuch_threads_get will return NULL).
+ * (where :c:func:`notmuch_threads_valid` will return ``FALSE`` and
+ * :c:func:`notmuch_threads_get` will return ``NULL``).
*
- * See the documentation of notmuch_query_search_threads for example
- * code showing how to iterate over a notmuch_threads_t object.
+ * See the documentation of :c:func:`notmuch_query_search_threads` for
+ * example code showing how to iterate over a
+ * :c:type:`notmuch_threads_t` object.
*/
void
notmuch_threads_move_to_next (notmuch_threads_t *threads);
/**
- * Destroy a notmuch_threads_t object.
+ * Destroy a :c:type:`notmuch_threads_t` object.
*
* It's not strictly necessary to call this function. All memory from
- * the notmuch_threads_t object will be reclaimed when the
+ * the :c:type:`notmuch_threads_t` object will be reclaimed when the
* containing query object is destroyed.
*/
void
@@ -1260,24 +1351,22 @@ notmuch_threads_destroy (notmuch_threads_t *threads);
* This function performs a search and returns the number of matching
* messages.
*
- * @returns
- *
- * NOTMUCH_STATUS_SUCCESS: query completed successfully.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: query completed
+ * successfully.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The
- * value of *count is not defined.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: a Xapian
+ * exception occurred. The value of ``*count`` is not defined.
*
- * @since libnotmuch 5 (notmuch 0.25)
+ * :since: libnotmuch 5 (notmuch 0.25)
*/
notmuch_status_t
notmuch_query_count_messages (notmuch_query_t *query, unsigned int *count);
/**
- * Deprecated alias for notmuch_query_count_messages
- *
+ * Deprecated alias for :c:func:`notmuch_query_count_messages`
*
- * @deprecated Deprecated since libnotmuch 5.0 (notmuch 0.25). Please
- * use notmuch_query_count_messages instead.
+ * :deprecated: Deprecated since libnotmuch 5.0 (notmuch 0.25). Please
+ * use :c:func:`notmuch_query_count_messages` instead.
*/
NOTMUCH_DEPRECATED (5, 0)
notmuch_status_t
@@ -1286,73 +1375,78 @@ notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count);
/**
* Return the number of threads matching a search.
*
- * This function performs a search and returns the number of unique thread IDs
- * in the matching messages. This is the same as number of threads matching a
- * search.
+ * This function performs a search and returns the number of unique
+ * thread IDs in the matching messages. This is the same as number of
+ * threads matching a search.
*
* Note that this is a significantly heavier operation than
- * notmuch_query_count_messages{_st}().
+ * :c:func:`notmuch_query_count_messages` or
+ * :c:func:`notmuch_query_count_messages_st`.
*
- * @returns
+ * :return:
*
- * NOTMUCH_STATUS_OUT_OF_MEMORY: Memory allocation failed. The value
- * of *count is not defined
+ * - :c:enumerator:`NOTMUCH_STATUS_OUT_OF_MEMORY`: Memory allocation
+ * failed. The value of ``*count`` is not defined
*
- * NOTMUCH_STATUS_SUCCESS: query completed successfully.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Query completed
+ * successfully.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The
- * value of *count is not defined.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred. The value of ``*count`` is not defined.
*
- * @since libnotmuch 5 (notmuch 0.25)
+ * :since: libnotmuch 5 (notmuch 0.25)
*/
notmuch_status_t
notmuch_query_count_threads (notmuch_query_t *query, unsigned *count);
/**
- * Deprecated alias for notmuch_query_count_threads
+ * Deprecated alias for :c:func:`notmuch_query_count_threads`
*
- * @deprecated Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please
- * use notmuch_query_count_threads_st instead.
+ * :deprecated: Deprecated as of libnotmuch 5.0 (notmuch 0.25). Please
+ * use :c:func:`notmuch_query_count_threads_st` instead.
*/
NOTMUCH_DEPRECATED (5, 0)
notmuch_status_t
notmuch_query_count_threads_st (notmuch_query_t *query, unsigned *count);
/**
- * Get the thread ID of 'thread'.
+ * Get the thread ID of ``thread``.
*
- * The returned string belongs to 'thread' and as such, should not be
- * modified by the caller and will only be valid for as long as the
- * thread is valid, (which is until notmuch_thread_destroy or until
- * the query from which it derived is destroyed).
+ * The returned string belongs to ``thread`` and as such, should not
+ * be modified by the caller and will only be valid for as long as the
+ * thread is valid, (which is until :c:func:`notmuch_thread_destroy`
+ * or until the query from which it derived is destroyed).
*/
const char *
notmuch_thread_get_thread_id (notmuch_thread_t *thread);
/**
- * Get the total number of messages in 'thread'.
+ * Get the total number of messages in ``thread``.
*
* This count consists of all messages in the database belonging to
- * this thread. Contrast with notmuch_thread_get_matched_messages() .
+ * this thread. Contrast with
+ * :c:func:`notmuch_thread_get_matched_messages`.
*/
int
notmuch_thread_get_total_messages (notmuch_thread_t *thread);
/**
- * Get the total number of files in 'thread'.
+ * Get the total number of files in ``thread``.
*
- * This sums notmuch_message_count_files over all messages in the
- * thread
- * @returns Non-negative integer
- * @since libnotmuch 5.0 (notmuch 0.25)
+ * This sums :c:func:`notmuch_message_count_files` over all messages
+ * in the thread
+ *
+ * :return: Non-negative integer
+ *
+ * :since: libnotmuch 5.0 (notmuch 0.25)
*/
int
notmuch_thread_get_total_files (notmuch_thread_t *thread);
/**
- * Get a notmuch_messages_t iterator for the top-level messages in
- * 'thread' in oldest-first order.
+ * Get a :c:type:`notmuch_messages_t` iterator for the top-level
+ * messages in ``thread`` in oldest-first order.
*
* This iterator will not necessarily iterate over all of the messages
* in the thread. It will only iterate over the messages in the thread
@@ -1364,8 +1458,8 @@ notmuch_messages_t *
notmuch_thread_get_toplevel_messages (notmuch_thread_t *thread);
/**
- * Get a notmuch_thread_t iterator for all messages in 'thread' in
- * oldest-first order.
+ * Get a :c:type:`notmuch_thread_t` iterator for all messages in
+ * ``thread`` in oldest-first order.
*
* The returned list will be destroyed when the thread is destroyed.
*/
@@ -1373,66 +1467,66 @@ notmuch_messages_t *
notmuch_thread_get_messages (notmuch_thread_t *thread);
/**
- * Get the number of messages in 'thread' that matched the search.
+ * Get the number of messages in ``thread`` that matched the search.
*
* This count includes only the messages in this thread that were
* matched by the search from which the thread was created and were
* not excluded by any exclude tags passed in with the query (see
- * notmuch_query_add_tag_exclude). Contrast with
- * notmuch_thread_get_total_messages() .
+ * :c:func:`notmuch_query_add_tag_exclude`). Contrast with
+ * :c:func:`notmuch_thread_get_total_messages`.
*/
int
notmuch_thread_get_matched_messages (notmuch_thread_t *thread);
/**
- * Get the authors of 'thread' as a UTF-8 string.
+ * Get the authors of ``thread`` as a UTF-8 string.
*
* The returned string is a comma-separated list of the names of the
* authors of mail messages in the query results that belong to this
* thread.
*
- * The string contains authors of messages matching the query first, then
- * non-matched authors (with the two groups separated by '|'). Within
- * each group, authors are ordered by date.
+ * The string contains authors of messages matching the query first,
+ * then non-matched authors (with the two groups separated by
+ * '|'). Within each group, authors are ordered by date.
*
- * The returned string belongs to 'thread' and as such, should not be
- * modified by the caller and will only be valid for as long as the
- * thread is valid, (which is until notmuch_thread_destroy or until
- * the query from which it derived is destroyed).
+ * The returned string belongs to ``thread`` and as such, should not
+ * be modified by the caller and will only be valid for as long as the
+ * thread is valid, (which is until :c:func:`notmuch_thread_destroy`
+ * or until the query from which it derived is destroyed).
*/
const char *
notmuch_thread_get_authors (notmuch_thread_t *thread);
/**
- * Get the subject of 'thread' as a UTF-8 string.
+ * Get the subject of ``thread`` as a UTF-8 string.
*
* The subject is taken from the first message (according to the query
- * order---see notmuch_query_set_sort) in the query results that
- * belongs to this thread.
+ * order---see :c:func:`notmuch_query_set_sort`) in the query results
+ * that belongs to this thread.
*
- * The returned string belongs to 'thread' and as such, should not be
- * modified by the caller and will only be valid for as long as the
- * thread is valid, (which is until notmuch_thread_destroy or until
- * the query from which it derived is destroyed).
+ * The returned string belongs to ``thread`` and as such, should not
+ * be modified by the caller and will only be valid for as long as the
+ * thread is valid, (which is until :c:func:`notmuch_thread_destroy`
+ * or until the query from which it derived is destroyed).
*/
const char *
notmuch_thread_get_subject (notmuch_thread_t *thread);
/**
- * Get the date of the oldest message in 'thread' as a time_t value.
+ * Get the date of the oldest message in ``thread`` as a time_t value.
*/
time_t
notmuch_thread_get_oldest_date (notmuch_thread_t *thread);
/**
- * Get the date of the newest message in 'thread' as a time_t value.
+ * Get the date of the newest message in ``thread`` as a time_t value.
*/
time_t
notmuch_thread_get_newest_date (notmuch_thread_t *thread);
/**
- * Get the tags for 'thread', returning a notmuch_tags_t object which
- * can be used to iterate over all tags.
+ * Get the tags for ``thread``, returning a :c:type:`notmuch_tags_t`
+ * object which can be used to iterate over all tags.
*
* Note: In the Notmuch database, tags are stored on individual
* messages, not on threads. So the tags returned here will be all
@@ -1441,10 +1535,10 @@ notmuch_thread_get_newest_date (notmuch_thread_t *thread);
*
* The tags object is owned by the thread and as such, will only be
* valid for as long as the thread is valid, (for example, until
- * notmuch_thread_destroy or until the query from which it derived is
- * destroyed).
+ * :c:func:`notmuch_thread_destroy` or until the query from which it
+ * derived is destroyed).
*
- * Typical usage might be:
+ * Typical usage might be::
*
* notmuch_thread_t *thread;
* notmuch_tags_t *tags;
@@ -1463,67 +1557,71 @@ notmuch_thread_get_newest_date (notmuch_thread_t *thread);
* notmuch_thread_destroy (thread);
*
* Note that there's no explicit destructor needed for the
- * notmuch_tags_t object. (For consistency, we do provide a
- * notmuch_tags_destroy function, but there's no good reason to call
- * it if the message is about to be destroyed).
+ * :c:type:`notmuch_tags_t` object. (For consistency, we do provide a
+ * :c:func:`notmuch_tags_destroy` function, but there's no good reason
+ * to call it if the message is about to be destroyed).
*/
notmuch_tags_t *
notmuch_thread_get_tags (notmuch_thread_t *thread);
/**
- * Destroy a notmuch_thread_t object.
+ * Destroy a :c:type:`notmuch_thread_t` object.
*/
void
notmuch_thread_destroy (notmuch_thread_t *thread);
/**
- * Is the given 'messages' iterator pointing at a valid message.
+ * Is the given ``messages`` iterator pointing at a valid message.
*
- * When this function returns TRUE, notmuch_messages_get will return a
- * valid object. Whereas when this function returns FALSE,
- * notmuch_messages_get will return NULL.
+ * When this function returns ``TRUE``, :c:func:`notmuch_messages_get`
+ * will return a valid object. Whereas when this function returns
+ * ``FALSE``, :c:func:`notmuch_messages_get` will return ``NULL``.
*
- * See the documentation of notmuch_query_search_messages for example
- * code showing how to iterate over a notmuch_messages_t object.
+ * See the documentation of :c:func:`notmuch_query_search_messages`
+ * for example code showing how to iterate over a
+ * :c:type:`notmuch_messages_t` object.
*/
notmuch_bool_t
notmuch_messages_valid (notmuch_messages_t *messages);
/**
- * Get the current message from 'messages' as a notmuch_message_t.
+ * Get the current message from ``messages`` as a
+ * :c:type:`notmuch_message_t`.
*
- * Note: The returned message belongs to 'messages' and has a lifetime
- * identical to it (and the query to which it belongs).
+ * Note: The returned message belongs to ``messages`` and has a
+ * lifetime identical to it (and the query to which it belongs).
*
- * See the documentation of notmuch_query_search_messages for example
- * code showing how to iterate over a notmuch_messages_t object.
+ * See the documentation of :c:func:`notmuch_query_search_messages`
+ * for example code showing how to iterate over a
+ * :c:type:`notmuch_messages_t` object.
*
* If an out-of-memory situation occurs, this function will return
- * NULL.
+ * ``NULL``.
*/
notmuch_message_t *
notmuch_messages_get (notmuch_messages_t *messages);
/**
- * Move the 'messages' iterator to the next message.
+ * Move the ``messages`` iterator to the next message.
*
- * If 'messages' is already pointing at the last message then the
+ * If ``messages`` is already pointing at the last message then the
* iterator will be moved to a point just beyond that last message,
- * (where notmuch_messages_valid will return FALSE and
- * notmuch_messages_get will return NULL).
+ * (where :c:func:`notmuch_messages_valid` will return ``FALSE`` and
+ * :c:func:`notmuch_messages_get` will return ``NULL``).
*
- * See the documentation of notmuch_query_search_messages for example
- * code showing how to iterate over a notmuch_messages_t object.
+ * See the documentation of :c:func:`notmuch_query_search_messages`
+ * for example code showing how to iterate over a
+ * :c:type:`notmuch_messages_t` object.
*/
void
notmuch_messages_move_to_next (notmuch_messages_t *messages);
/**
- * Destroy a notmuch_messages_t object.
+ * Destroy a :c:type:`notmuch_messages_t` object.
*
* It's not strictly necessary to call this function. All memory from
- * the notmuch_messages_t object will be reclaimed when the containing
- * query object is destroyed.
+ * the :c:type:`notmuch_messages_t` object will be reclaimed when the
+ * containing query object is destroyed.
*/
void
notmuch_messages_destroy (notmuch_messages_t *messages);
@@ -1533,13 +1631,15 @@ notmuch_messages_destroy (notmuch_messages_t *messages);
*
* The resulting list is guaranteed not to contain duplicated tags.
*
- * WARNING: You can no longer iterate over messages after calling this
- * function, because the iterator will point at the end of the list.
- * We do not have a function to reset the iterator yet and the only
- * way how you can iterate over the list again is to recreate the
- * message list.
+ * .. warning::
+ *
+ * You can no longer iterate over messages after calling this
+ * function, because the iterator will point at the end of the list.
+ * We do not have a function to reset the iterator yet and the only
+ * way how you can iterate over the list again is to recreate the
+ * message list.
*
- * The function returns NULL on error.
+ * The function returns ``NULL`` on error.
*/
notmuch_tags_t *
notmuch_messages_collect_tags (notmuch_messages_t *messages);
@@ -1547,80 +1647,83 @@ notmuch_messages_collect_tags (notmuch_messages_t *messages);
/**
* Get the database associated with this message.
*
- * @since libnotmuch 5.2 (notmuch 0.27)
+ * :since: libnotmuch 5.2 (notmuch 0.27)
*/
notmuch_database_t *
notmuch_message_get_database (const notmuch_message_t *message);
/**
- * Get the message ID of 'message'.
+ * Get the message ID of ``message``.
*
- * The returned string belongs to 'message' and as such, should not be
- * modified by the caller and will only be valid for as long as the
+ * The returned string belongs to ``message`` and as such, should not
+ * be modified by the caller and will only be valid for as long as the
* message is valid, (which is until the query from which it derived
* is destroyed).
*
- * This function will return NULL if triggers an unhandled Xapian
+ * This function will return ``NULL`` if triggers an unhandled Xapian
* exception.
*/
const char *
notmuch_message_get_message_id (notmuch_message_t *message);
/**
- * Get the thread ID of 'message'.
+ * Get the thread ID of ``message``.
*
- * The returned string belongs to 'message' and as such, should not be
- * modified by the caller and will only be valid for as long as the
+ * The returned string belongs to ``message`` and as such, should not
+ * be modified by the caller and will only be valid for as long as the
* message is valid, (for example, until the user calls
- * notmuch_message_destroy on 'message' or until a query from which it
- * derived is destroyed).
+ * :c:func:`notmuch_message_destroy` on ``message`` or until a query
+ * from which it derived is destroyed).
*
- * This function will return NULL if triggers an unhandled Xapian
+ * This function will return ``NULL`` if triggers an unhandled Xapian
* exception.
*/
const char *
notmuch_message_get_thread_id (notmuch_message_t *message);
/**
- * Get a notmuch_messages_t iterator for all of the replies to
- * 'message'.
+ * Get a :c:type:`notmuch_messages_t` iterator for all of the replies to
+ * ``message``.
*
- * Note: This call only makes sense if 'message' was ultimately
- * obtained from a notmuch_thread_t object, (such as by coming
- * directly from the result of calling notmuch_thread_get_
- * toplevel_messages or by any number of subsequent
- * calls to notmuch_message_get_replies).
+ * Note: This call only makes sense if ``message`` was ultimately
+ * obtained from a :c:type:`notmuch_thread_t` object, (such as by
+ * coming directly from the result of calling
+ * :c:func:`notmuch_thread_get_toplevel_messages` or by any number of
+ * subsequent calls to :c:func:`notmuch_message_get_replies`).
*
- * If 'message' was obtained through some non-thread means, (such as
- * by a call to notmuch_query_search_messages), then this function
- * will return NULL.
+ * If ``message`` was obtained through some non-thread means, (such as
+ * by a call to :c:func:`notmuch_query_search_messages`), then this
+ * function will return ``NULL``.
*
- * If there are no replies to 'message', this function will return
- * NULL. (Note that notmuch_messages_valid will accept that NULL
- * value as legitimate, and simply return FALSE for it.)
+ * If there are no replies to ``message``, this function will return
+ * ``NULL``. (Note that :c:func:`notmuch_messages_valid` will accept
+ * that ``NULL`` value as legitimate, and simply return ``FALSE`` for
+ * it.)
*
- * This function also returns NULL if it triggers a Xapian exception.
+ * This function also returns ``NULL`` if it triggers a Xapian
+ * exception.
*
- * The returned list will be destroyed when the thread is
- * destroyed.
+ * The returned list will be destroyed when the thread is destroyed.
*/
notmuch_messages_t *
notmuch_message_get_replies (notmuch_message_t *message);
/**
* Get the total number of files associated with a message.
- * @returns Non-negative integer for file count.
- * @returns Negative integer for error.
- * @since libnotmuch 5.0 (notmuch 0.25)
+ *
+ * :return: Non-negative integer for file count, negative integer for
+ * error.
+ *
+ * :since: libnotmuch 5.0 (notmuch 0.25)
*/
int
notmuch_message_count_files (notmuch_message_t *message);
/**
- * Get a filename for the email corresponding to 'message'.
+ * Get a filename for the email corresponding to ``message``.
*
* The returned filename is an absolute filename, (the initial
- * component will match notmuch_database_get_path() ).
+ * component will match :c:func:`notmuch_database_get_path`).
*
* The returned string belongs to the message so should not be
* modified or freed by the caller (nor should it be referenced after
@@ -1629,38 +1732,39 @@ notmuch_message_count_files (notmuch_message_t *message);
* Note: If this message corresponds to multiple files in the mail
* store, (that is, multiple files contain identical message IDs),
* this function will arbitrarily return a single one of those
- * filenames. See notmuch_message_get_filenames for returning the
- * complete list of filenames.
+ * filenames. See :c:func:`notmuch_message_get_filenames` for
+ * returning the complete list of filenames.
*
- * This function returns NULL if it triggers a Xapian exception.
+ * This function returns ``NULL`` if it triggers a Xapian exception.
*/
const char *
notmuch_message_get_filename (notmuch_message_t *message);
/**
- * Get all filenames for the email corresponding to 'message'.
+ * Get all filenames for the email corresponding to ``message``.
*
- * Returns a notmuch_filenames_t iterator listing all the filenames
- * associated with 'message'. These files may not have identical
- * content, but each will have the identical Message-ID.
+ * Returns a :c:type:`notmuch_filenames_t` iterator listing all the
+ * filenames associated with ``message``. These files may not have
+ * identical content, but each will have the identical Message-ID.
*
* Each filename in the iterator is an absolute filename, (the initial
- * component will match notmuch_database_get_path() ).
+ * component will match :c:func:`notmuch_database_get_path`).
*
- * This function returns NULL if it triggers a Xapian exception.
+ * This function returns ``NULL`` if it triggers a Xapian exception.
*/
notmuch_filenames_t *
notmuch_message_get_filenames (notmuch_message_t *message);
/**
- * Re-index the e-mail corresponding to 'message' using the supplied index options
+ * Re-index the e-mail corresponding to ``message`` using the supplied
+ * index options
*
* Returns the status of the re-index operation. (see the return
- * codes documented in notmuch_database_index_file)
+ * codes documented in :c:func:`notmuch_database_index_file`)
*
* After reindexing, the user should discard the message object passed
- * in here by calling notmuch_message_destroy, since it refers to the
- * original message, not to the reindexed message.
+ * in here by calling :c:func:`notmuch_message_destroy`, since it
+ * refers to the original message, not to the reindexed message.
*/
notmuch_status_t
notmuch_message_reindex (notmuch_message_t *message,
@@ -1682,12 +1786,12 @@ typedef enum {
} notmuch_message_flag_t;
/**
- * Get a value of a flag for the email corresponding to 'message'.
+ * Get a value of a flag for the email corresponding to ``message``.
*
- * returns FALSE in case of errors.
+ * returns ``FALSE`` in case of errors.
*
- * @deprecated Deprecated as of libnotmuch 5.3 (notmuch 0.31). Please
- * use notmuch_message_get_flag_st instead.
+ * :deprecated: Deprecated as of libnotmuch 5.3 (notmuch 0.31). Please
+ * use :c:func:`notmuch_message_get_flag_st` instead.
*/
NOTMUCH_DEPRECATED (5, 3)
notmuch_bool_t
@@ -1695,18 +1799,23 @@ notmuch_message_get_flag (notmuch_message_t *message,
notmuch_message_flag_t flag);
/**
- * Get a value of a flag for the email corresponding to 'message'.
+ * Get a value of a flag for the email corresponding to ``message``.
+ *
+ * :param message: a message object
+ * :param flag: flag to check
+ * :param is_set: pointer to boolean to store flag value.
*
- * @param message a message object
- * @param flag flag to check
- * @param is_set pointer to boolean to store flag value.
+ * :return:
*
- * @retval #NOTMUCH_STATUS_SUCCESS
- * @retval #NOTMUCH_STATUS_NULL_POINTER is_set is NULL
- * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION Accessing the database
- * triggered an exception.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`
+
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: is_set is
+ * ``NULL``
*
- * @since libnotmuch 5.3 (notmuch 0.31)
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: Accessing
+ * the database triggered an exception.
+ *
+ * :since: libnotmuch 5.3 (notmuch 0.31)
*/
notmuch_status_t
notmuch_message_get_flag_st (notmuch_message_t *message,
@@ -1714,18 +1823,18 @@ notmuch_message_get_flag_st (notmuch_message_t *message,
notmuch_bool_t *is_set);
/**
- * Set a value of a flag for the email corresponding to 'message'.
+ * Set a value of a flag for the email corresponding to ``message``.
*/
void
notmuch_message_set_flag (notmuch_message_t *message,
notmuch_message_flag_t flag, notmuch_bool_t value);
/**
- * Get the date of 'message' as a time_t value.
+ * Get the date of ``message`` as a time_t value.
*
* For the original textual representation of the Date header from the
- * message call notmuch_message_get_header() with a header value of
- * "date".
+ * message call :c:func:`notmuch_message_get_header` with a header
+ * value of "date".
*
* Returns 0 in case of error.
*/
@@ -1733,7 +1842,8 @@ time_t
notmuch_message_get_date (notmuch_message_t *message);
/**
- * Get the value of the specified header from 'message' as a UTF-8 string.
+ * Get the value of the specified header from ``message`` as a UTF-8
+ * string.
*
* Common headers are stored in the database when the message is
* indexed and will be returned from the database. Other headers will
@@ -1746,20 +1856,21 @@ notmuch_message_get_date (notmuch_message_t *message);
* the message is destroyed).
*
* Returns an empty string ("") if the message does not contain a
- * header line matching 'header'. Returns NULL if any error occurs.
+ * header line matching ``header``. Returns ``NULL`` if any error
+ * occurs.
*/
const char *
notmuch_message_get_header (notmuch_message_t *message, const char *header);
/**
- * Get the tags for 'message', returning a notmuch_tags_t object which
- * can be used to iterate over all tags.
+ * Get the tags for ``message``, returning a :c:type:`notmuch_tags_t`
+ * object which can be used to iterate over all tags.
*
* The tags object is owned by the message and as such, will only be
* valid for as long as the message is valid, (which is until the
* query from which it derived is destroyed).
*
- * Typical usage might be:
+ * Typical usage might be::
*
* notmuch_message_t *message;
* notmuch_tags_t *tags;
@@ -1778,9 +1889,9 @@ notmuch_message_get_header (notmuch_message_t *message, const char *header);
* notmuch_message_destroy (message);
*
* Note that there's no explicit destructor needed for the
- * notmuch_tags_t object. (For consistency, we do provide a
- * notmuch_tags_destroy function, but there's no good reason to call
- * it if the message is about to be destroyed).
+ * :c:type:`notmuch_tags_t` object. (For consistency, we do provide a
+ * :c:func:`notmuch_tags_destroy` function, but there's no good reason
+ * to call it if the message is about to be destroyed).
*/
notmuch_tags_t *
notmuch_message_get_tags (notmuch_message_t *message);
@@ -1793,17 +1904,20 @@ notmuch_message_get_tags (notmuch_message_t *message);
/**
* Add a tag to the given message.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Tag successfully added to message
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Tag successfully
+ * added to message
*
- * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The ``tag``
+ * argument is ``NULL``
*
- * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long
- * (exceeds NOTMUCH_TAG_MAX)
+ * - :c:enumerator:`NOTMUCH_STATUS_TAG_TOO_LONG`: The length of
+ * ``tag`` is too long (exceeds :c:macro:`NOTMUCH_TAG_MAX`)
*
- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
- * mode so message cannot be modified.
+ * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`:
+ * Database was opened in read-only mode so message cannot be
+ * modified.
*/
notmuch_status_t
notmuch_message_add_tag (notmuch_message_t *message, const char *tag);
@@ -1811,17 +1925,20 @@ notmuch_message_add_tag (notmuch_message_t *message, const char *tag);
/**
* Remove a tag from the given message.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Tag successfully removed from message
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Tag successfully
+ * removed from message
*
- * NOTMUCH_STATUS_NULL_POINTER: The 'tag' argument is NULL
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: The ``tag``
+ * argument is ``NULL``
*
- * NOTMUCH_STATUS_TAG_TOO_LONG: The length of 'tag' is too long
- * (exceeds NOTMUCH_TAG_MAX)
+ * - :c:enumerator:`NOTMUCH_STATUS_TAG_TOO_LONG`: The length of
+ * ``tag`` is too long (exceeds :c:macro:`NOTMUCH_TAG_MAX`)
*
- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
- * mode so message cannot be modified.
+ * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`:
+ * Database was opened in read-only mode so message cannot be
+ * modified.
*/
notmuch_status_t
notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);
@@ -1829,13 +1946,17 @@ notmuch_message_remove_tag (notmuch_message_t *message, const char *tag);
/**
* Remove all tags from the given message.
*
- * See notmuch_message_freeze for an example showing how to safely
- * replace tag values.
+ * See :c:func:`notmuch_message_freeze` for an example showing how to
+ * safely replace tag values.
+ *
+ * :return:
*
- * @retval #NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in
- * read-only mode so message cannot be modified.
- * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION: an exception was thrown
- * accessing the database.
+ * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`:
+ * Database was opened in read-only mode so message cannot be
+ * modified.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: An
+ * exception was thrown accessing the database.
*/
notmuch_status_t
notmuch_message_remove_all_tags (notmuch_message_t *message);
@@ -1843,23 +1964,25 @@ notmuch_message_remove_all_tags (notmuch_message_t *message);
/**
* Add/remove tags according to maildir flags in the message filename(s).
*
- * This function examines the filenames of 'message' for maildir
- * flags, and adds or removes tags on 'message' as follows when these
- * flags are present:
+ * This function examines the filenames of ``message`` for maildir
+ * flags, and adds or removes tags on ``message`` as follows when
+ * these flags are present:
*
- * Flag Action if present
- * ---- -----------------
- * 'D' Adds the "draft" tag to the message
- * 'F' Adds the "flagged" tag to the message
- * 'P' Adds the "passed" tag to the message
- * 'R' Adds the "replied" tag to the message
- * 'S' Removes the "unread" tag from the message
+ * ===== ==============================================
+ * Flag Action if present
+ * ===== ==============================================
+ * ``D`` Adds the "draft" tag to the message
+ * ``F`` Adds the "flagged" tag to the message
+ * ``P`` Adds the "passed" tag to the message
+ * ``R`` Adds the "replied" tag to the message
+ * ``S`` Removes the "unread" tag from the message
+ * ===== ==============================================
*
* For each flag that is not present, the opposite action (add/remove)
* is performed for the corresponding tags.
*
* Flags are identified as trailing components of the filename after a
- * sequence of ":2,".
+ * sequence of ``:2,``.
*
* If there are multiple filenames associated with this message, the
* flag is considered present if it appears in one or more
@@ -1868,21 +1991,23 @@ notmuch_message_remove_all_tags (notmuch_message_t *message);
*
* A client can ensure that notmuch database tags remain synchronized
* with maildir flags by calling this function after each call to
- * notmuch_database_index_file. See also
- * notmuch_message_tags_to_maildir_flags for synchronizing tag changes
- * back to maildir flags.
+ * :c:func:`notmuch_database_index_file`. See also
+ * :c:func:`notmuch_message_tags_to_maildir_flags` for synchronizing
+ * tag changes back to maildir flags.
*/
notmuch_status_t
notmuch_message_maildir_flags_to_tags (notmuch_message_t *message);
/**
- * return TRUE if any filename of 'message' has maildir flag 'flag',
- * FALSE otherwise.
+ * return ``TRUE`` if any filename of ``message`` has maildir flag
+ * ``flag``, ``FALSE`` otherwise.
+ *
+ * Deprecated wrapper for
+ * :c:func:`notmuch_message_has_maildir_flag_st`
*
- * Deprecated wrapper for notmuch_message_has_maildir_flag_st
+ * :return: ``FALSE`` in case of error
*
- * @returns FALSE in case of error
- * @deprecated libnotmuch 5.3 (notmuch 0.31)
+ * :deprecated: libnotmuch 5.3 (notmuch 0.31)
*/
NOTMUCH_DEPRECATED (5, 3)
notmuch_bool_t
@@ -1891,14 +2016,19 @@ notmuch_message_has_maildir_flag (notmuch_message_t *message, char flag);
/**
* check message for maildir flag
*
- * @param [in,out] message message to check
- * @param [in] flag flag to check for
- * @param [out] is_set pointer to boolean
+ * :param message: message message to check
+ * :param flag: flag to check for
+ * :param is_set: pointer to boolean
+ *
+ * :return:
*
- * @retval #NOTMUCH_STATUS_SUCCESS
- * @retval #NOTMUCH_STATUS_NULL_POINTER is_set is NULL
- * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION Accessing the database
- * triggered an exception.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: ``is_set`` is
+ * ``NULL``.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: Accessing the
+ * database triggered an exception.
*/
notmuch_status_t
notmuch_message_has_maildir_flag_st (notmuch_message_t *message,
@@ -1911,44 +2041,48 @@ notmuch_message_has_maildir_flag_st (notmuch_message_t *message,
* Specifically, for each filename corresponding to this message:
*
* If the filename is not in a maildir directory, do nothing. (A
- * maildir directory is determined as a directory named "new" or
- * "cur".) Similarly, if the filename has invalid maildir info,
- * (repeated or outof-ASCII-order flag characters after ":2,"), then
+ * maildir directory is determined as a directory named ``new`` or
+ * ``cur``.) Similarly, if the filename has invalid maildir info,
+ * (repeated or outof-ASCII-order flag characters after ``:2,``), then
* do nothing.
*
* If the filename is in a maildir directory, rename the file so that
- * its filename ends with the sequence ":2," followed by zero or more
- * of the following single-character flags (in ASCII order):
+ * its filename ends with the sequence ``:2,`` followed by zero or
+ * more of the following single-character flags (in ASCII order):
*
- * * flag 'D' iff the message has the "draft" tag
- * * flag 'F' iff the message has the "flagged" tag
- * * flag 'P' iff the message has the "passed" tag
- * * flag 'R' iff the message has the "replied" tag
- * * flag 'S' iff the message does not have the "unread" tag
+ * * flag ``D`` iff the message has the "draft" tag
+ * * flag ``F`` iff the message has the "flagged" tag
+ * * flag ``P`` iff the message has the "passed" tag
+ * * flag ``R`` iff the message has the "replied" tag
+ * * flag ``S`` iff the message does not have the "unread" tag
*
* Any existing flags unmentioned in the list above will be preserved
* in the renaming.
*
- * Also, if this filename is in a directory named "new", rename it to
- * be within the neighboring directory named "cur".
+ * Also, if this filename is in a directory named ``new``, rename it
+ * to be within the neighboring directory named ``cur``.
*
* A client can ensure that maildir filename flags remain synchronized
* with notmuch database tags by calling this function after changing
- * tags, (after calls to notmuch_message_add_tag,
- * notmuch_message_remove_tag, or notmuch_message_freeze/
- * notmuch_message_thaw). See also notmuch_message_maildir_flags_to_tags
- * for synchronizing maildir flag changes back to tags.
+ * tags, (after calls to :c:func:`notmuch_message_add_tag`,
+ * :c:func:`notmuch_message_remove_tag`, or
+ * :c:func:`notmuch_message_freeze`/
+ * :c:func:`notmuch_message_thaw`). See also
+ * :c:func:`notmuch_message_maildir_flags_to_tags` for synchronizing
+ * maildir flag changes back to tags.
*/
notmuch_status_t
notmuch_message_tags_to_maildir_flags (notmuch_message_t *message);
/**
- * Freeze the current state of 'message' within the database.
+ * Freeze the current state of ``message`` within the database.
*
* This means that changes to the message state, (via
- * notmuch_message_add_tag, notmuch_message_remove_tag, and
- * notmuch_message_remove_all_tags), will not be committed to the
- * database until the message is thawed with notmuch_message_thaw.
+ * :c:func:`notmuch_message_add_tag`,
+ * :c:func:`notmuch_message_remove_tag`, and
+ * :c:func:`notmuch_message_remove_all_tags`), will not be committed
+ * to the database until the message is thawed with
+ * :c:func:`notmuch_message_thaw`.
*
* Multiple calls to freeze/thaw are valid and these calls will
* "stack". That is there must be as many calls to thaw as to freeze
@@ -1956,7 +2090,7 @@ notmuch_message_tags_to_maildir_flags (notmuch_message_t *message);
*
* The ability to do freeze/thaw allows for safe transactions to
* change tag values. For example, explicitly setting a message to
- * have a given set of tags might look like this:
+ * have a given set of tags might look like this::
*
* notmuch_message_freeze (message);
*
@@ -1974,44 +2108,48 @@ notmuch_message_tags_to_maildir_flags (notmuch_message_t *message);
* Imagine the example above without freeze/thaw and the operation
* somehow getting interrupted. This could result in the message being
* left with no tags if the interruption happened after
- * notmuch_message_remove_all_tags but before notmuch_message_add_tag.
+ * :c:func:`notmuch_message_remove_all_tags` but before
+ * :c:func:`notmuch_message_add_tag`.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Message successfully frozen.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Message successfully
+ * frozen.
*
- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
- * mode so message cannot be modified.
+ * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: Database was
+ * opened in read-only mode so message cannot be modified.
*/
notmuch_status_t
notmuch_message_freeze (notmuch_message_t *message);
/**
- * Thaw the current 'message', synchronizing any changes that may have
- * occurred while 'message' was frozen into the notmuch database.
+ * Thaw the current ``message``, synchronizing any changes that may have
+ * occurred while ``message`` was frozen into the notmuch database.
*
- * See notmuch_message_freeze for an example of how to use this
- * function to safely provide tag changes.
+ * See :c:func:`notmuch_message_freeze` for an example of how to use
+ * this function to safely provide tag changes.
*
* Multiple calls to freeze/thaw are valid and these calls with
* "stack". That is there must be as many calls to thaw as to freeze
* before a message is actually thawed.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: Message successfully thawed, (or at least
- * its frozen count has successfully been reduced by 1).
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: Message
+ * successfully thawed, (or at least its frozen count has
+ * successfully been reduced by 1).
*
- * NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW: An attempt was made to thaw
- * an unfrozen message. That is, there have been an unbalanced
- * number of calls to notmuch_message_freeze and
- * notmuch_message_thaw.
+ * - :c:enumerator:`NOTMUCH_STATUS_UNBALANCED_FREEZE_THAW`: An
+ * attempt was made to thaw an unfrozen message. That is, there have
+ * been an unbalanced number of calls to
+ * :c:func:`notmuch_message_freeze` and
+ * :c:func:`notmuch_message_thaw`.
*/
notmuch_status_t
notmuch_message_thaw (notmuch_message_t *message);
/**
- * Destroy a notmuch_message_t object.
+ * Destroy a :c:type:`notmuch_message_t` object.
*
* It can be useful to call this function in the case of a single
* query object with many messages in the result, (such as iterating
@@ -2023,7 +2161,7 @@ void
notmuch_message_destroy (notmuch_message_t *message);
/**
- * @name Message Properties
+ * Message Properties
*
* This interface provides the ability to attach arbitrary (key,value)
* string pairs to a message, to remove such pairs, and to iterate
@@ -2031,22 +2169,26 @@ notmuch_message_destroy (notmuch_message_t *message);
* add or delete values for, as other subsystems or extensions may
* depend on these properties.
*
- * Please see notmuch-properties(7) for more details about specific
+ * Please see :any:`notmuch-properties(7)` for more details about specific
* properties and conventions around their use.
*
*/
-/**@{*/
+
/**
* Retrieve the value for a single property key
*
- * *value* is set to a string owned by the message or NULL if there is
+ * ``value`` is set to a string owned by the message or ``NULL`` if there is
* no such key. In the case of multiple values for the given key, the
* first one is retrieved.
*
- * @returns
- * - NOTMUCH_STATUS_NULL_POINTER: *value* may not be NULL.
- * - NOTMUCH_STATUS_SUCCESS: No error occurred.
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :return:
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: ``value`` may
+ * not be ``NULL``.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: No error occurred.
+ *
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_status_t
notmuch_message_get_property (notmuch_message_t *message, const char *key, const char **value);
@@ -2054,11 +2196,17 @@ notmuch_message_get_property (notmuch_message_t *message, const char *key, const
/**
* Add a (key,value) pair to a message
*
- * @returns
- * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character.
- * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL.
- * - NOTMUCH_STATUS_SUCCESS: No error occurred.
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :return:
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_ILLEGAL_ARGUMENT`: ``key`` may
+ * not contain an '=' character.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: Neither
+ * ``key`` nor ``value`` may be ``NULL``.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: No error occurred.
+ *
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_status_t
notmuch_message_add_property (notmuch_message_t *message, const char *key, const char *value);
@@ -2068,11 +2216,17 @@ notmuch_message_add_property (notmuch_message_t *message, const char *key, const
*
* It is not an error to remove a non-existent (key,value) pair
*
- * @returns
- * - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character.
- * - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL.
- * - NOTMUCH_STATUS_SUCCESS: No error occurred.
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :return:
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_ILLEGAL_ARGUMENT`: ``key``
+ * may not contain an '=' character.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_NULL_POINTER`: Neither
+ * ``key`` nor ``value`` may be ``NULL``.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: No error occurred.
+ *
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_status_t
notmuch_message_remove_property (notmuch_message_t *message, const char *key, const char *value);
@@ -2080,15 +2234,19 @@ notmuch_message_remove_property (notmuch_message_t *message, const char *key, co
/**
* Remove all (key,value) pairs from the given message.
*
- * @param[in,out] message message to operate on.
- * @param[in] key key to delete properties for. If NULL, delete
- * properties for all keys
- * @returns
- * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in
- * read-only mode so message cannot be modified.
- * - NOTMUCH_STATUS_SUCCESS: No error occurred.
+ * :param message: message to operate on.
+ * :param key: key to delete properties for. If ``NULL``, delete
+ * properties for all keys
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :return:
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`:
+ * Database was opened in read-only mode so message cannot be
+ * modified.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: No error occurred.
+ *
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_status_t
notmuch_message_remove_all_properties (notmuch_message_t *message, const char *key);
@@ -2096,15 +2254,18 @@ notmuch_message_remove_all_properties (notmuch_message_t *message, const char *k
/**
* Remove all (prefix*,value) pairs from the given message
*
- * @param[in,out] message message to operate on.
- * @param[in] prefix delete properties with keys that start with prefix.
- * If NULL, delete all properties
- * @returns
- * - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in
- * read-only mode so message cannot be modified.
- * - NOTMUCH_STATUS_SUCCESS: No error occurred.
+ * :param message: message to operate on.
+ * :param prefix: delete properties with keys that start with prefix.
+ * If ``NULL``, delete all properties
+ *
+ * :return:
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: Database was
+ * opened in read-only mode so message cannot be modified.
*
- * @since libnotmuch 5.1 (notmuch 0.26)
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: No error occurred.
+ *
+ * :since: libnotmuch 5.1 (notmuch 0.26)
*/
notmuch_status_t
notmuch_message_remove_all_properties_with_prefix (notmuch_message_t *message, const char *prefix);
@@ -2115,20 +2276,21 @@ notmuch_message_remove_all_properties_with_prefix (notmuch_message_t *message, c
typedef struct _notmuch_string_map_iterator notmuch_message_properties_t;
/**
- * Get the properties for *message*, returning a
- * notmuch_message_properties_t object which can be used to iterate
- * over all properties.
+ * Get the properties for ``message``, returning a
+ * :c:type:`notmuch_message_properties_t` object which can be used to
+ * iterate over all properties.
*
- * The notmuch_message_properties_t object is owned by the message and
- * as such, will only be valid for as long as the message is valid,
- * (which is until the query from which it derived is destroyed).
+ * The :c:type:`notmuch_message_properties_t` object is owned by the
+ * message and as such, will only be valid for as long as the message
+ * is valid, (which is until the query from which it derived is
+ * destroyed).
*
- * @param[in] message The message to examine
- * @param[in] key key or key prefix
- * @param[in] exact if TRUE, require exact match with key. Otherwise
- * treat as prefix.
+ * :param message: The message to examine
+ * :param key: key or key prefix
+ * :param exact: if ``TRUE``, require exact match with key. Otherwise
+ * treat as prefix.
*
- * Typical usage might be:
+ * Typical usage might be::
*
* notmuch_message_properties_t *list;
*
@@ -2140,11 +2302,12 @@ typedef struct _notmuch_string_map_iterator notmuch_message_properties_t;
* notmuch_message_properties_destroy (list);
*
* Note that there's no explicit destructor needed for the
- * notmuch_message_properties_t object. (For consistency, we do
- * provide a notmuch_message_properities_destroy function, but there's
- * no good reason to call it if the message is about to be destroyed).
+ * :c:type:`notmuch_message_properties_t` object. (For consistency, we
+ * do provide a :c:func:`notmuch_message_properties_destroy` function,
+ * but there's no good reason to call it if the message is about to be
+ * destroyed).
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_message_properties_t *
notmuch_message_get_properties (notmuch_message_t *message, const char *key, notmuch_bool_t exact);
@@ -2152,49 +2315,52 @@ notmuch_message_get_properties (notmuch_message_t *message, const char *key, not
/**
* Return the number of properties named "key" belonging to the specific message.
*
- * @param[in] message The message to examine
- * @param[in] key key to count
- * @param[out] count The number of matching properties associated with this message.
+ * :param message: The message to examine
+ * :param key: key to count
+ * :param count: The number of matching properties associated with this message.
*
- * @returns
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: successful count, possibly some other error.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: successful count,
+ * possibly some other error.
*
- * @since libnotmuch 5.2 (notmuch 0.27)
+ * :since: libnotmuch 5.2 (notmuch 0.27)
*/
notmuch_status_t
notmuch_message_count_properties (notmuch_message_t *message, const char *key, unsigned int *count);
/**
- * Is the given *properties* iterator pointing at a valid (key,value)
+ * Is the given ``properties`` iterator pointing at a valid (key,value)
* pair.
*
- * When this function returns TRUE,
+ * When this function returns ``TRUE``,
* notmuch_message_properties_{key,value} will return a valid string,
- * and notmuch_message_properties_move_to_next will do what it
- * says. Whereas when this function returns FALSE, calling any of
- * these functions results in undefined behaviour.
+ * and :c:func:`notmuch_message_properties_move_to_next` will do what
+ * it says. Whereas when this function returns ``FALSE``, calling any
+ * of these functions results in undefined behaviour.
*
- * See the documentation of notmuch_message_get_properties for example
- * code showing how to iterate over a notmuch_message_properties_t
- * object.
+ * See the documentation of :c:func:`notmuch_message_get_properties`
+ * for example code showing how to iterate over a
+ * :c:type:`notmuch_message_properties_t` object.
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_bool_t
notmuch_message_properties_valid (notmuch_message_properties_t *properties);
/**
- * Move the *properties* iterator to the next (key,value) pair
+ * Move the ``properties`` iterator to the next (key,value) pair
*
- * If *properties* is already pointing at the last pair then the iterator
- * will be moved to a point just beyond that last pair, (where
- * notmuch_message_properties_valid will return FALSE).
+ * If ``properties`` is already pointing at the last pair then the
+ * iterator will be moved to a point just beyond that last pair,
+ * (where :c:func:`notmuch_message_properties_valid` will return
+ * ``FALSE``).
*
- * See the documentation of notmuch_message_get_properties for example
- * code showing how to iterate over a notmuch_message_properties_t object.
+ * See the documentation of :c:func:`notmuch_message_get_properties`
+ * for example code showing how to iterate over a
+ * :c:type:`notmuch_message_properties_t` object.
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
void
notmuch_message_properties_move_to_next (notmuch_message_properties_t *properties);
@@ -2204,7 +2370,7 @@ notmuch_message_properties_move_to_next (notmuch_message_properties_t *propertie
*
* this could be useful if iterating for a prefix
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
const char *
notmuch_message_properties_key (notmuch_message_properties_t *properties);
@@ -2214,80 +2380,82 @@ notmuch_message_properties_key (notmuch_message_properties_t *properties);
*
* This could be useful if iterating for a prefix.
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
const char *
notmuch_message_properties_value (notmuch_message_properties_t *properties);
/**
- * Destroy a notmuch_message_properties_t object.
+ * Destroy a :c:type:`notmuch_message_properties_t` object.
*
* It's not strictly necessary to call this function. All memory from
- * the notmuch_message_properties_t object will be reclaimed when the
- * containing message object is destroyed.
+ * the :c:type:`notmuch_message_properties_t` object will be reclaimed
+ * when the containing message object is destroyed.
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
void
notmuch_message_properties_destroy (notmuch_message_properties_t *properties);
-/**@}*/
-
/**
- * Is the given 'tags' iterator pointing at a valid tag.
+ * Is the given ``tags`` iterator pointing at a valid tag.
*
- * When this function returns TRUE, notmuch_tags_get will return a
- * valid string. Whereas when this function returns FALSE,
- * notmuch_tags_get will return NULL.
+ * When this function returns ``TRUE``, :c:func:`notmuch_tags_get`
+ * will return a valid string. Whereas when this function returns
+ * ``FALSE``, :c:func:`notmuch_tags_get` will return ``NULL``.
*
- * See the documentation of notmuch_message_get_tags for example code
- * showing how to iterate over a notmuch_tags_t object.
+ * See the documentation of :c:func:`notmuch_message_get_tags` for
+ * example code showing how to iterate over a :c:type:`notmuch_tags_t`
+ * object.
*/
notmuch_bool_t
notmuch_tags_valid (notmuch_tags_t *tags);
/**
- * Get the current tag from 'tags' as a string.
+ * Get the current tag from ``tags`` as a string.
*
- * Note: The returned string belongs to 'tags' and has a lifetime
+ * Note: The returned string belongs to ``tags`` and has a lifetime
* identical to it (and the query to which it ultimately belongs).
*
- * See the documentation of notmuch_message_get_tags for example code
- * showing how to iterate over a notmuch_tags_t object.
+ * See the documentation of :c:func:`notmuch_message_get_tags` for
+ * example code showing how to iterate over a :c:type:`notmuch_tags_t`
+ * object.
*/
const char *
notmuch_tags_get (notmuch_tags_t *tags);
/**
- * Move the 'tags' iterator to the next tag.
+ * Move the ``tags`` iterator to the next tag.
*
- * If 'tags' is already pointing at the last tag then the iterator
+ * If ``tags`` is already pointing at the last tag then the iterator
* will be moved to a point just beyond that last tag, (where
- * notmuch_tags_valid will return FALSE and notmuch_tags_get will
- * return NULL).
+ * :c:func:`notmuch_tags_valid` will return ``FALSE`` and
+ * :c:func:`notmuch_tags_get` will return ``NULL``).
*
- * See the documentation of notmuch_message_get_tags for example code
- * showing how to iterate over a notmuch_tags_t object.
+ * See the documentation of :c:func:`notmuch_message_get_tags` for
+ * example code showing how to iterate over a :c:type:`notmuch_tags_t`
+ * object.
*/
void
notmuch_tags_move_to_next (notmuch_tags_t *tags);
/**
- * Destroy a notmuch_tags_t object.
+ * Destroy a :c:type:`notmuch_tags_t` object.
*
* It's not strictly necessary to call this function. All memory from
- * the notmuch_tags_t object will be reclaimed when the containing
- * message or query objects are destroyed.
+ * the :c:type:`notmuch_tags_t` object will be reclaimed when the
+ * containing message or query objects are destroyed.
*/
void
notmuch_tags_destroy (notmuch_tags_t *tags);
/**
- * Store an mtime within the database for 'directory'.
+ * Store an mtime within the database for ``directory``.
*
- * The 'directory' should be an object retrieved from the database
- * with notmuch_database_get_directory for a particular path.
+ * The ``directory`` should be an object retrieved from the database
+ * with :c:func:`notmuch_database_get_directory` for a particular
+ * path.
*
* The intention is for the caller to use the mtime to allow efficient
* identification of new messages to be added to the database. The
@@ -2297,28 +2465,29 @@ notmuch_tags_destroy (notmuch_tags_t *tags);
*
* o Call index_file for all mail files in the directory
*
- * o Call notmuch_directory_set_mtime with the mtime read from the
+ * o Call :c:func:`notmuch_directory_set_mtime` with the mtime read from the
* filesystem.
*
* Then, when wanting to check for updates to the directory in the
- * future, the client can call notmuch_directory_get_mtime and know
- * that it only needs to add files if the mtime of the directory and
- * files are newer than the stored timestamp.
+ * future, the client can call :c:func:`notmuch_directory_get_mtime`
+ * and know that it only needs to add files if the mtime of the
+ * directory and files are newer than the stored timestamp.
*
- * Note: The notmuch_directory_get_mtime function does not allow the
- * caller to distinguish a timestamp of 0 from a non-existent
- * timestamp. So don't store a timestamp of 0 unless you are
- * comfortable with that.
+ * Note: The :c:func:`notmuch_directory_get_mtime` function does not
+ * allow the caller to distinguish a timestamp of 0 from a
+ * non-existent timestamp. So don't store a timestamp of 0 unless you
+ * are comfortable with that.
*
- * Return value:
+ * :return:
*
- * NOTMUCH_STATUS_SUCCESS: mtime successfully stored in database.
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`: mtime successfully
+ * stored in database.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: A Xapian exception
- * occurred, mtime not stored.
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: A Xapian
+ * exception occurred, mtime not stored.
*
- * NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in read-only
- * mode so directory mtime cannot be modified.
+ * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: Database was
+ * opened in read-only mode so directory mtime cannot be modified.
*/
notmuch_status_t
notmuch_directory_set_mtime (notmuch_directory_t *directory,
@@ -2326,7 +2495,7 @@ notmuch_directory_set_mtime (notmuch_directory_t *directory,
/**
* Get the mtime of a directory, (as previously stored with
- * notmuch_directory_set_mtime).
+ * :c:func:`notmuch_directory_set_mtime`).
*
* Returns 0 if no mtime has previously been stored for this
* directory.
@@ -2335,92 +2504,95 @@ time_t
notmuch_directory_get_mtime (notmuch_directory_t *directory);
/**
- * Get a notmuch_filenames_t iterator listing all the filenames of
- * messages in the database within the given directory.
+ * Get a :c:type:`notmuch_filenames_t` iterator listing all the
+ * filenames of messages in the database within the given directory.
*
* The returned filenames will be the basename-entries only (not
* complete paths).
*
- * Returns NULL if it triggers a Xapian exception
+ * Returns ``NULL`` if it triggers a Xapian exception
*/
notmuch_filenames_t *
notmuch_directory_get_child_files (notmuch_directory_t *directory);
/**
- * Get a notmuch_filenames_t iterator listing all the filenames of
- * sub-directories in the database within the given directory.
+ * Get a :c:type:`notmuch_filenames_t` iterator listing all the
+ * filenames of sub-directories in the database within the given
+ * directory.
*
* The returned filenames will be the basename-entries only (not
* complete paths).
*
- * Returns NULL if it triggers a Xapian exception
+ * Returns ``NULL`` if it triggers a Xapian exception
*/
notmuch_filenames_t *
notmuch_directory_get_child_directories (notmuch_directory_t *directory);
/**
* Delete directory document from the database, and destroy the
- * notmuch_directory_t object. Assumes any child directories and files
- * have been deleted by the caller.
+ * :c:type:`notmuch_directory_t` object. Assumes any child directories
+ * and files have been deleted by the caller.
*
- * @since libnotmuch 4.3 (notmuch 0.21)
+ * :since: libnotmuch 4.3 (notmuch 0.21)
*/
notmuch_status_t
notmuch_directory_delete (notmuch_directory_t *directory);
/**
- * Destroy a notmuch_directory_t object.
+ * Destroy a :c:type:`notmuch_directory_t` object.
*/
void
notmuch_directory_destroy (notmuch_directory_t *directory);
/**
- * Is the given 'filenames' iterator pointing at a valid filename.
+ * Is the given ``filenames`` iterator pointing at a valid filename.
*
- * When this function returns TRUE, notmuch_filenames_get will return
- * a valid string. Whereas when this function returns FALSE,
- * notmuch_filenames_get will return NULL.
+ * When this function returns ``TRUE``,
+ * :c:func:`notmuch_filenames_get` will return a valid string. Whereas
+ * when this function returns ``FALSE``,
+ * :c:func:`notmuch_filenames_get` will return ``NULL``.
*
- * It is acceptable to pass NULL for 'filenames', in which case this
- * function will always return FALSE.
+ * It is acceptable to pass ``NULL`` for ``filenames``, in which case
+ * this function will always return ``FALSE``.
*/
notmuch_bool_t
notmuch_filenames_valid (notmuch_filenames_t *filenames);
/**
- * Get the current filename from 'filenames' as a string.
+ * Get the current filename from ``filenames`` as a string.
*
- * Note: The returned string belongs to 'filenames' and has a lifetime
- * identical to it (and the directory to which it ultimately belongs).
+ * Note: The returned string belongs to ``filenames`` and has a
+ * lifetime identical to it (and the directory to which it ultimately
+ * belongs).
*
- * It is acceptable to pass NULL for 'filenames', in which case this
- * function will always return NULL.
+ * It is acceptable to pass ``NULL`` for ``filenames``, in which case
+ * this function will always return ``NULL``.
*/
const char *
notmuch_filenames_get (notmuch_filenames_t *filenames);
/**
- * Move the 'filenames' iterator to the next filename.
+ * Move the ``filenames`` iterator to the next filename.
*
- * If 'filenames' is already pointing at the last filename then the
+ * If ``filenames`` is already pointing at the last filename then the
* iterator will be moved to a point just beyond that last filename,
- * (where notmuch_filenames_valid will return FALSE and
- * notmuch_filenames_get will return NULL).
+ * (where :c:func:`notmuch_filenames_valid` will return ``FALSE`` and
+ * :c:func:`notmuch_filenames_get` will return ``NULL``).
*
- * It is acceptable to pass NULL for 'filenames', in which case this
+ * It is acceptable to pass ``NULL`` for ``filenames``, in which case this
* function will do nothing.
*/
void
notmuch_filenames_move_to_next (notmuch_filenames_t *filenames);
/**
- * Destroy a notmuch_filenames_t object.
+ * Destroy a :c:type:`notmuch_filenames_t` object.
*
* It's not strictly necessary to call this function. All memory from
- * the notmuch_filenames_t object will be reclaimed when the
+ * the :c:type:`notmuch_filenames_t` object will be reclaimed when the
* containing directory object is destroyed.
*
- * It is acceptable to pass NULL for 'filenames', in which case this
+ * It is acceptable to pass ``NULL`` for ``filenames``, in which case this
* function will do nothing.
*/
void
@@ -2428,29 +2600,33 @@ notmuch_filenames_destroy (notmuch_filenames_t *filenames);
/**
- * set config 'key' to 'value'
+ * set config ``key`` to ``value``
+ *
+ * :return:
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_SUCCESS`
*
- * @since libnotmuch 4.4 (notmuch 0.23)
- * @retval #NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in
- * read-only mode so message cannot be modified.
- * @retval #NOTMUCH_STATUS_XAPIAN_EXCEPTION: an exception was thrown
- * accessing the database.
- * @retval #NOTMUCH_STATUS_SUCCESS
+ * - :c:enumerator:`NOTMUCH_STATUS_READ_ONLY_DATABASE`: Database was
+ * opened in read-only mode so message cannot be modified.
+ *
+ * - :c:enumerator:`NOTMUCH_STATUS_XAPIAN_EXCEPTION`: an exception
+ * was thrown accessing the database.
+ *
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_status_t
notmuch_database_set_config (notmuch_database_t *db, const char *key, const char *value);
/**
- * retrieve config item 'key', assign to 'value'
+ * retrieve config item ``key``, assign to ``value``
*
- * keys which have not been previously set with n_d_set_config will
- * return an empty string.
+ * keys which have not been previously set with
+ * :c:func:`notmuch_database_set_config` will return an empty string.
*
* return value is allocated by malloc and should be freed by the
* caller.
*
- * @since libnotmuch 4.4 (notmuch 0.23)
- *
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_status_t
notmuch_database_get_config (notmuch_database_t *db, const char *key, char **value);
@@ -2458,16 +2634,16 @@ notmuch_database_get_config (notmuch_database_t *db, const char *key, char **val
/**
* Create an iterator for all config items with keys matching a given prefix
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_status_t
notmuch_database_get_config_list (notmuch_database_t *db, const char *prefix,
notmuch_config_list_t **out);
/**
- * Is 'config_list' iterator valid (i.e. _key, _value, _move_to_next can be called).
+ * Is ``config_list`` iterator valid (i.e. _key, _value, _move_to_next can be called).
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_bool_t
notmuch_config_list_valid (notmuch_config_list_t *config_list);
@@ -2476,38 +2652,41 @@ notmuch_config_list_valid (notmuch_config_list_t *config_list);
* return key for current config pair
*
* return value is owned by the iterator, and will be destroyed by the
- * next call to notmuch_config_list_key or notmuch_config_list_destroy.
+ * next call to :c:func:`notmuch_config_list_key` or
+ * :c:func:`notmuch_config_list_destroy`.
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
const char *
notmuch_config_list_key (notmuch_config_list_t *config_list);
/**
- * return 'value' for current config pair
+ * return ``value`` for current config pair
*
* return value is owned by the iterator, and will be destroyed by the
- * next call to notmuch_config_list_value or notmuch config_list_destroy
+ * next call to :c:func:`notmuch_config_list_value` or
+ * :c:func:`notmuch_config_list_destroy`
*
- * @since libnotmuch 4.4 (notmuch 0.23)
- * @retval NULL for errors
+ * :return: ``NULL`` for errors
+ *
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
const char *
notmuch_config_list_value (notmuch_config_list_t *config_list);
/**
- * move 'config_list' iterator to the next pair
+ * move ``config_list`` iterator to the next pair
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
void
notmuch_config_list_move_to_next (notmuch_config_list_t *config_list);
/**
- * free any resources held by 'config_list'
+ * free any resources held by ``config_list``
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
void
notmuch_config_list_destroy (notmuch_config_list_t *config_list);
@@ -2538,14 +2717,14 @@ typedef enum {
* This value reflects all configuration information given at the time
* the database was opened.
*
- * @param[in] notmuch database
- * @param[in] key configuration key
+ * :param notmuch: database
+ * :param key: configuration key
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :return: ``NULL`` if ``key`` unknown or if no value is known for
+ * ``key``. Otherwise returns a string owned by notmuch which
+ * should not be modified nor freed by the caller.
*
- * @retval NULL if 'key' unknown or if no value is known for
- * 'key'. Otherwise returns a string owned by notmuch which should
- * not be modified nor freed by the caller.
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
const char *
notmuch_config_get (notmuch_database_t *notmuch, notmuch_config_key_t key);
@@ -2556,13 +2735,13 @@ notmuch_config_get (notmuch_database_t *notmuch, notmuch_config_key_t key);
* This value reflects all configuration information given at the time
* the database was opened.
*
- * @param[in,out] notmuch database open read/write
- * @param[in] key configuration key
- * @param[in] val configuration value
+ * :param notmuch: database open read/write
+ * :param key: configuration key
+ * :param val: configuration value
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :return: returns any return value for notmuch_database_set_config.
*
- * @retval returns any return value for notmuch_database_set_config.
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_status_t
notmuch_config_set (notmuch_database_t *notmuch, notmuch_config_key_t key, const char *val);
@@ -2573,12 +2752,12 @@ notmuch_config_set (notmuch_database_t *notmuch, notmuch_config_key_t key, const
* These values reflect all configuration information given at the
* time the database was opened.
*
- * @param[in] notmuch database
- * @param[in] key configuration key
+ * :param notmuch: database
+ * :param key: configuration key
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :return: ``NULL`` in case of error.
*
- * @retval NULL in case of error.
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_config_values_t *
notmuch_config_get_values (notmuch_database_t *notmuch, notmuch_config_key_t key);
@@ -2589,12 +2768,12 @@ notmuch_config_get_values (notmuch_database_t *notmuch, notmuch_config_key_t key
* These values reflect all configuration information given at the
* time the database was opened.
*
- * @param[in] notmuch database
- * @param[in] key configuration key
+ * :param notmuch: database
+ * :param key: configuration key
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :return: ``NULL`` in case of error.
*
- * @retval NULL in case of error.
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_config_values_t *
notmuch_config_get_values_string (notmuch_database_t *notmuch, const char *key);
@@ -2602,12 +2781,12 @@ notmuch_config_get_values_string (notmuch_database_t *notmuch, const char *key);
/**
* Is the given 'config_values' iterator pointing at a valid element.
*
- * @param[in] values iterator
- *
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :param values: iterator
*
- * @retval FALSE if passed a NULL pointer, or the iterator is exhausted.
+ * :return: ``FALSE`` if passed a ``NULL`` pointer, or the iterator is
+ * exhausted.
*
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_bool_t
notmuch_config_values_valid (notmuch_config_values_t *values);
@@ -2615,11 +2794,11 @@ notmuch_config_values_valid (notmuch_config_values_t *values);
/**
* Get the current value from the 'values' iterator
*
- * @param[in] values iterator
+ * :param values: iterator
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :return: a string with the same lifetime as the iterator
*
- * @retval a string with the same lifetime as the iterator
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
const char *
notmuch_config_values_get (notmuch_config_values_t *values);
@@ -2627,9 +2806,9 @@ notmuch_config_values_get (notmuch_config_values_t *values);
/**
* Move the 'values' iterator to the next element
*
- * @param[in,out] values iterator
+ * :param values: iterator
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*
*/
void
@@ -2639,10 +2818,9 @@ notmuch_config_values_move_to_next (notmuch_config_values_t *values);
/**
* reset the 'values' iterator to the first element
*
- * @param[in,out] values iterator. A NULL value is ignored.
- *
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :param values: iterator. A ``NULL`` value is ignored.
*
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
void
notmuch_config_values_start (notmuch_config_values_t *values);
@@ -2651,9 +2829,9 @@ notmuch_config_values_start (notmuch_config_values_t *values);
* Destroy a config values iterator, along with any associated
* resources.
*
- * @param[in,out] values iterator
+ * :param values: iterator
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
void
notmuch_config_values_destroy (notmuch_config_values_t *values);
@@ -2662,12 +2840,12 @@ notmuch_config_values_destroy (notmuch_config_values_t *values);
/**
* Returns an iterator for a (key, value) configuration pairs
*
- * @param[in] notmuch database
- * @param[in] prefix prefix for keys. Pass "" for all keys.
+ * :param notmuch: database
+ * :param prefix: prefix for keys. Pass "" for all keys.
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :return: ``NULL`` in case of error.
*
- * @retval NULL in case of error.
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_config_pairs_t *
notmuch_config_get_pairs (notmuch_database_t *notmuch,
@@ -2676,12 +2854,12 @@ notmuch_config_get_pairs (notmuch_database_t *notmuch,
/**
* Is the given 'config_pairs' iterator pointing at a valid element.
*
- * @param[in] pairs iterator
- *
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :param pairs: iterator
*
- * @retval FALSE if passed a NULL pointer, or the iterator is exhausted.
+ * :return: ``FALSE`` if passed a ``NULL`` pointer, or the iterator is
+ * exhausted.
*
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_bool_t
notmuch_config_pairs_valid (notmuch_config_pairs_t *pairs);
@@ -2689,10 +2867,9 @@ notmuch_config_pairs_valid (notmuch_config_pairs_t *pairs);
/**
* Move the 'config_pairs' iterator to the next element
*
- * @param[in,out] pairs iterator
- *
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :param pairs: iterator
*
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
void
notmuch_config_pairs_move_to_next (notmuch_config_pairs_t *pairs);
@@ -2700,11 +2877,11 @@ notmuch_config_pairs_move_to_next (notmuch_config_pairs_t *pairs);
/**
* Get the current key from the 'config_pairs' iterator
*
- * @param[in] pairs iterator
+ * :param pairs: iterator
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :return: a string with the same lifetime as the iterator
*
- * @retval a string with the same lifetime as the iterator
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
const char *
notmuch_config_pairs_key (notmuch_config_pairs_t *pairs);
@@ -2712,11 +2889,11 @@ notmuch_config_pairs_key (notmuch_config_pairs_t *pairs);
/**
* Get the current value from the 'config_pairs' iterator
*
- * @param[in] pairs iterator
+ * :param pairs: iterator
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :return: a string with the same lifetime as the iterator
*
- * @retval a string with the same lifetime as the iterator
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
const char *
notmuch_config_pairs_value (notmuch_config_pairs_t *pairs);
@@ -2725,9 +2902,9 @@ notmuch_config_pairs_value (notmuch_config_pairs_t *pairs);
* Destroy a config_pairs iterator, along with any associated
* resources.
*
- * @param[in,out] pairs iterator
+ * :param pairs: iterator
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
void
notmuch_config_pairs_destroy (notmuch_config_pairs_t *pairs);
@@ -2738,14 +2915,14 @@ notmuch_config_pairs_destroy (notmuch_config_pairs_t *pairs);
* This value reflects all configuration information given at the time
* the database was opened.
*
- * @param[in] notmuch database
- * @param[in] key configuration key
- * @param[out] val configuration value, converted to Boolean
+ * :param notmuch: database
+ * :param key: configuration key
+ * :param val: configuration value, converted to Boolean
*
- * @since libnotmuch 5.4 (notmuch 0.32)
+ * :return: :c:enumerator:`NOTMUCH_STATUS_ILLEGAL_ARGUMENT` if either key is unknown
+ * or the corresponding value does not convert to Boolean.
*
- * @retval #NOTMUCH_STATUS_ILLEGAL_ARGUMENT if either key is unknown
- * or the corresponding value does not convert to Boolean.
+ * :since: libnotmuch 5.4 (notmuch 0.32)
*/
notmuch_status_t
notmuch_config_get_bool (notmuch_database_t *notmuch,
@@ -2755,7 +2932,7 @@ notmuch_config_get_bool (notmuch_database_t *notmuch,
/**
* return the path of the config file loaded, if any
*
- * @retval NULL if no config file was loaded
+ * :return: ``NULL`` if no config file was loaded
*/
const char *
notmuch_config_path (notmuch_database_t *notmuch);
@@ -2765,13 +2942,14 @@ notmuch_config_path (notmuch_database_t *notmuch);
*
* This object will survive until the database itself is destroyed,
* but the caller may also release it earlier with
- * notmuch_indexopts_destroy.
+ * :c:func:`notmuch_indexopts_destroy`.
*
* This object represents a set of options on how a message can be
* added to the index. At the moment it is a featureless stub.
*
- * @since libnotmuch 5.1 (notmuch 0.26)
- * @retval NULL in case of error
+ * :return: ``NULL`` in case of error
+ *
+ * :since: libnotmuch 5.1 (notmuch 0.26)
*/
notmuch_indexopts_t *
notmuch_database_get_default_indexopts (notmuch_database_t *db);
@@ -2779,7 +2957,7 @@ notmuch_database_get_default_indexopts (notmuch_database_t *db);
/**
* Stating a policy about how to decrypt messages.
*
- * See index.decrypt in notmuch-config(1) for more details.
+ * See ``index.decrypt`` in :any:`notmuch-config(1)` for more details.
*/
typedef enum {
NOTMUCH_DECRYPT_FALSE,
@@ -2791,12 +2969,14 @@ typedef enum {
/**
* Specify whether to decrypt encrypted parts while indexing.
*
- * Be aware that the index is likely sufficient to reconstruct the
- * cleartext of the message itself, so please ensure that the notmuch
- * message index is adequately protected. DO NOT SET THIS FLAG TO TRUE
- * without considering the security of your index.
+ * .. warning::
+ *
+ * Be aware that the index is likely sufficient to reconstruct the
+ * cleartext of the message itself, so please ensure that the
+ * notmuch message index is adequately protected. DO NOT SET THIS
+ * FLAG TO ``TRUE`` without considering the security of your index.
*
- * @since libnotmuch 5.1 (notmuch 0.26)
+ * :since: libnotmuch 5.1 (notmuch 0.26)
*/
notmuch_status_t
notmuch_indexopts_set_decrypt_policy (notmuch_indexopts_t *indexopts,
@@ -2804,17 +2984,17 @@ notmuch_indexopts_set_decrypt_policy (notmuch_indexopts_t *indexopts,
/**
* Return whether to decrypt encrypted parts while indexing.
- * see notmuch_indexopts_set_decrypt_policy.
+ * see :c:func:`notmuch_indexopts_set_decrypt_policy`.
*
- * @since libnotmuch 5.1 (notmuch 0.26)
+ * :since: libnotmuch 5.1 (notmuch 0.26)
*/
notmuch_decryption_policy_t
notmuch_indexopts_get_decrypt_policy (const notmuch_indexopts_t *indexopts);
/**
- * Destroy a notmuch_indexopts_t object.
+ * Destroy a :c:type:`notmuch_indexopts_t` object.
*
- * @since libnotmuch 5.1 (notmuch 0.26)
+ * :since: libnotmuch 5.1 (notmuch 0.26)
*/
void
notmuch_indexopts_destroy (notmuch_indexopts_t *options);
@@ -2823,11 +3003,10 @@ notmuch_indexopts_destroy (notmuch_indexopts_t *options);
/**
* interrogate the library for compile time features
*
- * @since libnotmuch 4.4 (notmuch 0.23)
+ * :since: libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_bool_t
notmuch_built_with (const char *name);
-/**@}*/
#pragma GCC visibility pop
--
2.30.2
^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [RFC 1/5] doc: replace doxygen with hawkmoth sphinx extension for api docs
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
1 sibling, 1 reply; 17+ messages in thread
From: Tomi Ollila @ 2021-10-13 6:26 UTC (permalink / raw)
To: Jani Nikula, notmuch; +Cc: jani
Interesting stuff...
On Tue, Oct 12 2021, Jani Nikula wrote:
> 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.
// stuff deleted //
> +
> # -- Options for HTML output ----------------------------------------------
>
> # The theme to use for HTML and HTML Help pages. See the documentation for
> @@ -172,6 +178,13 @@ man_pages = [
> [notmuch_authors], 1),
> ]
>
> +if tags.has('WITH_API_DOCS'):
> + man_pages += [
> + ('man3/notmuch', 'notmuch',
> + u'notmuch library',
öld stuff...??? (the u'' i mean) :O
Tomi
> + [notmuch_authors], 3),
> + ]
> +
> # If true, show URL addresses after external links.
> #man_show_urls = False
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [RFC 1/5] doc: replace doxygen with hawkmoth sphinx extension for api docs
2021-10-13 6:26 ` Tomi Ollila
@ 2021-10-13 9:02 ` Jani Nikula
0 siblings, 0 replies; 17+ messages in thread
From: Jani Nikula @ 2021-10-13 9:02 UTC (permalink / raw)
To: Tomi Ollila, notmuch
On Wed, 13 Oct 2021, Tomi Ollila <tomi.ollila@iki.fi> wrote:
> Interesting stuff...
>
> On Tue, Oct 12 2021, Jani Nikula wrote:
>
>> 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.
>
> // stuff deleted //
>
>> +
>> # -- Options for HTML output ----------------------------------------------
>>
>> # The theme to use for HTML and HTML Help pages. See the documentation for
>> @@ -172,6 +178,13 @@ man_pages = [
>> [notmuch_authors], 1),
>> ]
>>
>> +if tags.has('WITH_API_DOCS'):
>> + man_pages += [
>> + ('man3/notmuch', 'notmuch',
>> + u'notmuch library',
>
> öld stuff...??? (the u'' i mean) :O
Yeah, it's still used throughout in man_pages, decided to follow suit
instead of making that cleanup now.
BR,
Jani.
>
> Tomi
>
>
>> + [notmuch_authors], 3),
>> + ]
>> +
>> # If true, show URL addresses after external links.
>> #man_show_urls = False
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [RFC 0/5] doc: api docs overhaul
2021-10-12 18:51 [RFC 0/5] doc: api docs overhaul Jani Nikula
` (4 preceding siblings ...)
2021-10-12 18:51 ` [RFC 5/5] lib: documentation comment overhaul for hawkmoth Jani Nikula
@ 2021-10-13 12:17 ` David Bremner
2021-10-13 13:41 ` Jani Nikula
5 siblings, 1 reply; 17+ messages in thread
From: David Bremner @ 2021-10-13 12:17 UTC (permalink / raw)
To: Jani Nikula, notmuch; +Cc: jani
Jani Nikula <jani@nikula.org> writes:
> The main downside is that Hawkmoth is not available via distro
> packaging, only PyPI.
I guess another issue is the new dependency on Clang +
bindings. Although maybe that's a fair trade for dropping doxygen.
What would be the plan for transition while distros package hawkmoth?
Embed it in notmuch? Ship the compiled docs?
d
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [RFC 2/5] lib: remove enum names from typedefs
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
0 siblings, 1 reply; 17+ messages in thread
From: David Bremner @ 2021-10-13 13:18 UTC (permalink / raw)
To: Jani Nikula, notmuch; +Cc: jani
Jani Nikula <jani@nikula.org> writes:
> 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.
> ---
I guess that change would be fine independent of the rest?
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [RFC 3/5] lib: remove commented out NOTMUCH_DEPRECATED()
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
0 siblings, 1 reply; 17+ messages in thread
From: David Bremner @ 2021-10-13 13:19 UTC (permalink / raw)
To: Jani Nikula, notmuch; +Cc: jani
Jani Nikula <jani@nikula.org> writes:
> 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?
Yes, those should be uncommented, I think.
d
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [RFC 1/5] doc: replace doxygen with hawkmoth sphinx extension for api docs
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 13:21 ` David Bremner
1 sibling, 0 replies; 17+ messages in thread
From: David Bremner @ 2021-10-13 13:21 UTC (permalink / raw)
To: Jani Nikula, notmuch; +Cc: jani
Jani Nikula <jani@nikula.org> writes:
>
> -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
> -
I guess it's an important point that missing hawkmoth only blocks
building the api docs, not all of the docs.
d
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [RFC 2/5] lib: remove enum names from typedefs
2021-10-13 13:18 ` David Bremner
@ 2021-10-13 13:28 ` Tomi Ollila
2021-10-13 14:04 ` Jani Nikula
0 siblings, 1 reply; 17+ messages in thread
From: Tomi Ollila @ 2021-10-13 13:28 UTC (permalink / raw)
To: David Bremner, Jani Nikula, notmuch; +Cc: jani
On Wed, Oct 13 2021, David Bremner wrote:
> Jani Nikula <jani@nikula.org> writes:
>
>> 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.
>> ---
> I guess that change would be fine independent of the rest?
I had the same thought.
Tomi
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [RFC 0/5] doc: api docs overhaul
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
0 siblings, 1 reply; 17+ messages in thread
From: Jani Nikula @ 2021-10-13 13:41 UTC (permalink / raw)
To: David Bremner, notmuch
On Wed, 13 Oct 2021, David Bremner <david@tethera.net> wrote:
> Jani Nikula <jani@nikula.org> writes:
>
>> The main downside is that Hawkmoth is not available via distro
>> packaging, only PyPI.
>
> I guess another issue is the new dependency on Clang +
> bindings. Although maybe that's a fair trade for dropping doxygen.
Doxygen already depends on libclang:
$ dpkg -s doxygen | grep "^Depends:"
Depends: libc6 (>= 2.29), libclang-cpp11 (>= 1:11.0.1), libclang1-11 (>=
1:5.0~svn298832-1~), libgcc-s1 (>= 3.0), libllvm11 (>=
1:9~svn298832-1~), libstdc++6 (>= 7), libxapian30 (>= 1.4.14~)
The difference is that the libclang python bindings depend on the dev
packages:
$ dpkg -s python3-clang-11 | grep "^Depends:"
Depends: python3, libclang-11-dev
$ dpkg -s libclang-11-dev | grep "^Depends:"
Depends: libstdc++-10-dev, libgcc-10-dev, libobjc-10-dev, libclang1-11
(= 1:11.0.1-2), libclang-common-11-dev (= 1:11.0.1-2)
I think you're probably in a better position to judge the relative sizes
of the dependency trees than me, but the libclang dependency is already
there with Doxygen. The Python parts are pretty small, it's the dev
packages vs. Doxygen that makes the difference.
> What would be the plan for transition while distros package hawkmoth?
> Embed it in notmuch? Ship the compiled docs?
I'm afraid I don't have an answer to that. What do projects do when they
depend on packages from PyPI? It's a kind of chicken and egg problem.
I saw that you made the Debian packaging request; many thanks! But is
that enough? What is your stance on imposing new dependencies on other
distros?
BR,
Jani.
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [RFC 0/5] doc: api docs overhaul
2021-10-13 13:41 ` Jani Nikula
@ 2021-10-13 13:59 ` David Bremner
0 siblings, 0 replies; 17+ messages in thread
From: David Bremner @ 2021-10-13 13:59 UTC (permalink / raw)
To: Jani Nikula, notmuch
Jani Nikula <jani@nikula.org> writes:
>
> I'm afraid I don't have an answer to that. What do projects do when they
> depend on packages from PyPI? It's a kind of chicken and egg problem.
I would say python projects would happily _only_ depend on pypi (witness
the requests to package notmuch for pypi) but we're not such a project.
>
> I saw that you made the Debian packaging request; many thanks! But is
> that enough?
No, it's actually relatively unlikely that someone will volunteer to
package it. I could do it myself, but I'd be happier if someone more up
on the latest python-in-debian practices would handle it.
> What is your stance on imposing new dependencies on other
> distros?
>
Well I just did it with sfsexp. My reasoning was that it was for an
optional (for now) new feature, so people were no worse off than
before. It's not quite the same thing here, since there is some API docs
now. I don't know how many people refer to them. A very rough estimate
from Debian [1] is that about 10% of the people who install notmuch also
install libnotmuch-dev, which contains the API docs. I guess most people
would be happy with a Web version of the API docs, which we don't do
now, but which would automagically happen if it was in the sphinx doctree.
[1]: https://qa.debian.org/popcon.php?package=notmuch
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [RFC 2/5] lib: remove enum names from typedefs
2021-10-13 13:28 ` Tomi Ollila
@ 2021-10-13 14:04 ` Jani Nikula
0 siblings, 0 replies; 17+ messages in thread
From: Jani Nikula @ 2021-10-13 14:04 UTC (permalink / raw)
To: Tomi Ollila, David Bremner, notmuch
On Wed, 13 Oct 2021, Tomi Ollila <tomi.ollila@iki.fi> wrote:
> On Wed, Oct 13 2021, David Bremner wrote:
>
>> Jani Nikula <jani@nikula.org> writes:
>>
>>> 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.
>>> ---
>> I guess that change would be fine independent of the rest?
>
> I had the same thought.
Added more typedef enums outside of notmuch.h, removed hawkmoth
references, and resent separately.
BR,
Jani.
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [RFC 3/5] lib: remove commented out NOTMUCH_DEPRECATED()
2021-10-13 13:19 ` David Bremner
@ 2021-10-13 14:04 ` Jani Nikula
0 siblings, 0 replies; 17+ messages in thread
From: Jani Nikula @ 2021-10-13 14:04 UTC (permalink / raw)
To: David Bremner, notmuch
On Wed, 13 Oct 2021, David Bremner <david@tethera.net> wrote:
> Jani Nikula <jani@nikula.org> writes:
>
>> 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?
>
> Yes, those should be uncommented, I think.
Thanks, sent separately. Though it does give deprecation warnings now.
BR,
Jani.
^ permalink raw reply [flat|nested] 17+ messages in thread
end of thread, other threads:[~2021-10-13 14:05 UTC | newest]
Thread overview: 17+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
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 ` [RFC 5/5] lib: documentation comment overhaul for hawkmoth Jani Nikula
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
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).