doxygen.adoc revision 0bbfda8a
1# Doxygen 2 3 4## Overview 5 6Some code (hopefully more, over time) has inline documentation intended 7to be generated via http://www.stack.nl/~dimitri/doxygen/[Doxygen]. If 8Doxygen is installed on your system, the standard CMake toolchain will 9find it and provide build targets. If it's not... well, install it. 10 11If it's available, a `make doxygen` target is created to generate the 12HTML docs. They'll wind up in a directory under `build/` (or wherever 13you're building it). See the output of running the target; it'll tell 14you where the files are. 15 16Currently a few large data structures have their existing documentation 17transferred into doxygen format, and more added to flesh them out a 18little more. It's hoped that over time more of them will be, and further 19documentation of various functions etc. will be so moved and/or written. 20 21The Doxygen manual at the link above is a useful reference to the various 22commands available. 23 24 25## Special notes 26 27We make use of both ``/**``-style and ``///``-style comments, in various 28combinations. Post-comments, particularly in ``///<``-style at EOL are 29used mostly when they fit on the single line. If they start wrapping to 30multiple lines, they usually get converted to pre-comments on prior 31lines. Exceptions may exist, but usually work poorly when confronted 32with `make indent` and so are very rare. 33 34Some seemingly odd constructions get used, like a `/**` block comment 35immediately followed by a `///` line, or multiple `///` lines separated 36by blanks. These might be mistakes, but are often ways of separating 37things so doxygen gets the right idea. In particular, see places in the 38`struct ScreenInfo` docs where we create groups for documentation 39purposes, and then document a field; without that separator, doxygen 40doesn't notice that we're moving from the `@{` that defines the group, to 41documenting the first field in it. See e.g. the `BorderTileC` field, at 42the time of writing. 43 44The rules for when doxygen auto-links things are a little unclear, and 45don't seem entirely consistent. So for most intentional links to _e.g._ 46structure members, they're fully specified even when they seem to work 47without being so. Escaping with `\` or `%` are done in various places on 48an as-needed basis. 49