# Doxygen
## Overview
Some code (hopefully more, over time) has inline documentation intended to be generated via Doxygen. If Doxygen is installed on your system, the standard CMake toolchain will find it and provide build targets. If it’s not… well, install it.
If it’s available, a make doxygen
target is created to generate the
HTML docs. They’ll wind up in a directory under build/
(or wherever
you’re building it). See the output of running the target; it’ll tell
you where the files are.
Currently a few large data structures have their existing documentation transferred into doxygen format, and more added to flesh them out a little more. It’s hoped that over time more of them will be, and further documentation of various functions etc. will be so moved and/or written.
The Doxygen manual at the link above is a useful reference to the various commands available.
## Special notes
We make use of both ``/**``-style and ``///``-style comments, in various
combinations. Post-comments, particularly in ``///<``-style at EOL are
used mostly when they fit on the single line. If they start wrapping to
multiple lines, they usually get converted to pre-comments on prior
lines. Exceptions may exist, but usually work poorly when confronted
with make indent
and so are very rare.
Some seemingly odd constructions get used, like a /**
block comment
immediately followed by a ///
line, or multiple ///
lines separated
by blanks. These might be mistakes, but are often ways of separating
things so doxygen gets the right idea. In particular, see places in the
struct ScreenInfo
docs where we create groups for documentation
purposes, and then document a field; without that separator, doxygen
doesn’t notice that we’re moving from the @{
that defines the group, to
documenting the first field in it. See e.g. the BorderTileC
field, at
the time of writing.
The rules for when doxygen auto-links things are a little unclear, and
don’t seem entirely consistent. So for most intentional links to e.g.
structure members, they’re fully specified even when they seem to work
without being so. Escaping with \
or %
are done in various places on
an as-needed basis.