# 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.