Set up Doxygen

.gitignore

@@ -2,5 +2,6 @@
 .venv
 coverage.txt
 docs/_build
+docs/_doxygen
 /*build*
 debug.log

docs/Doxyfile

@@ -0,0 +1,17 @@
+PROJECT_NAME = alia
+PROJECT_BRIEF = "a library for interactive applications"
+
+STRIP_FROM_PATH = ../src
+
+INPUT = ../src
+EXTRACT_ALL = YES
+RECURSIVE = YES
+OUTPUT_DIRECTORY = _doxygen
+
+GENERATE_XML = YES
+GENERATE_HTML = NO
+GENERATE_LATEX = NO
+XML_PROGRAMLISTING = NO
+CREATE_SUBDIRS = NO
+
+M_SHOW_UNDOCUMENTED = YES

docs/conf.py

@@ -1,3 +1,7 @@
+import sys
+import os
+import subprocess
+
 import sphinx_rtd_theme
 
 project = 'alia'
@@ -6,6 +10,16 @@
 
 extensions = ['breathe', 'sphinx_rtd_theme']
 
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', '_doxygen']
 
 html_theme = 'sphinx_rtd_theme'
+
+breathe_projects = { "alia": "_doxygen/xml" }
+breathe_default_project = "alia"
+
+def generate_doxygen_xml(app):
+    subprocess.check_call(['doxygen', 'Doxyfile'])
+
+def setup(app):
+    # Add hook for building doxygen xml when needed
+    app.connect("builder-inited", generate_doxygen_xml)

docs/index.rst

@@ -6,3 +6,6 @@ This is the reference documentation for alia...
 .. toctree::
    :maxdepth: 2
    :caption: Contents
+
+.. doxygenfunction:: alia::mask
+

docs/requirements.txt

@@ -1 +1,2 @@
+sphinx==3.3.1
 breathe

scripts/set-up-python.sh

@@ -5,4 +5,5 @@ set -x -e
 virtualenv --prompt="(alia) " "$@" .venv
 source .venv/bin/activate
 python --version
-pip install gcovr sphinx==3.3.1 breathe
+pip install gcovr
+pip install -r docs/requirements.txt

src/alia/common.hpp

@@ -21,6 +21,7 @@ typedef long long counter_type;
 // Inspired by Boost, inheriting from noncopyable disables copying for a type.
 // The namespace prevents unintended ADL if used by applications.
 namespace detail { namespace noncopyable_ {
+/// \internal
 struct noncopyable
 {
     noncopyable()

src/alia/signals/adaptors.hpp

@@ -327,10 +327,6 @@ simplify_id(Wrapped wrapped)
     return simplified_id_wrapper<Wrapped>(std::move(wrapped));
 }
 
-// mask(signal, availibility_flag) does the equivalent of bit masking on
-// individual signals. If :availibility_flag evaluates to true, the mask
-// evaluates to a signal equivalent to :signal. Otherwise, it evaluates to an
-// empty signal of the same type.
 template<class Primary, class Mask>
 struct masking_signal final
     : signal_wrapper<masking_signal<Primary, Mask>, Primary>
@@ -373,6 +369,14 @@ make_masking_signal(Signal signal, AvailabilityFlag availability_flag)
     return masking_signal<Signal, AvailabilityFlag>(
         std::move(signal), std::move(availability_flag));
 }
+
+/// Mask a signal.
+///
+/// This does the equivalent of bit-masking on an individual signal. If
+/// \p availibility_flag evaluates to true, the mask evaluates to a signal
+/// equivalent to \p signal. Otherwise, it evaluates to an empty signal of the
+/// same type.
+///
 template<class Signal, class AvailabilityFlag>
 auto
 mask(Signal signal, AvailabilityFlag availability_flag)