10bbfda8aSnia# Doxygen 20bbfda8aSnia 30bbfda8aSnia 40bbfda8aSnia## Overview 50bbfda8aSnia 60bbfda8aSniaSome code (hopefully more, over time) has inline documentation intended 70bbfda8aSniato be generated via http://www.stack.nl/~dimitri/doxygen/[Doxygen]. If 80bbfda8aSniaDoxygen is installed on your system, the standard CMake toolchain will 90bbfda8aSniafind it and provide build targets. If it's not... well, install it. 100bbfda8aSnia 110bbfda8aSniaIf it's available, a `make doxygen` target is created to generate the 120bbfda8aSniaHTML docs. They'll wind up in a directory under `build/` (or wherever 130bbfda8aSniayou're building it). See the output of running the target; it'll tell 140bbfda8aSniayou where the files are. 150bbfda8aSnia 160bbfda8aSniaCurrently a few large data structures have their existing documentation 170bbfda8aSniatransferred into doxygen format, and more added to flesh them out a 180bbfda8aSnialittle more. It's hoped that over time more of them will be, and further 190bbfda8aSniadocumentation of various functions etc. will be so moved and/or written. 200bbfda8aSnia 210bbfda8aSniaThe Doxygen manual at the link above is a useful reference to the various 220bbfda8aSniacommands available. 230bbfda8aSnia 240bbfda8aSnia 250bbfda8aSnia## Special notes 260bbfda8aSnia 270bbfda8aSniaWe make use of both ``/**``-style and ``///``-style comments, in various 280bbfda8aSniacombinations. Post-comments, particularly in ``///<``-style at EOL are 290bbfda8aSniaused mostly when they fit on the single line. If they start wrapping to 300bbfda8aSniamultiple lines, they usually get converted to pre-comments on prior 310bbfda8aSnialines. Exceptions may exist, but usually work poorly when confronted 320bbfda8aSniawith `make indent` and so are very rare. 330bbfda8aSnia 340bbfda8aSniaSome seemingly odd constructions get used, like a `/**` block comment 350bbfda8aSniaimmediately followed by a `///` line, or multiple `///` lines separated 360bbfda8aSniaby blanks. These might be mistakes, but are often ways of separating 370bbfda8aSniathings so doxygen gets the right idea. In particular, see places in the 380bbfda8aSnia`struct ScreenInfo` docs where we create groups for documentation 390bbfda8aSniapurposes, and then document a field; without that separator, doxygen 400bbfda8aSniadoesn't notice that we're moving from the `@{` that defines the group, to 410bbfda8aSniadocumenting the first field in it. See e.g. the `BorderTileC` field, at 420bbfda8aSniathe time of writing. 430bbfda8aSnia 440bbfda8aSniaThe rules for when doxygen auto-links things are a little unclear, and 450bbfda8aSniadon't seem entirely consistent. So for most intentional links to _e.g._ 460bbfda8aSniastructure members, they're fully specified even when they seem to work 470bbfda8aSniawithout being so. Escaping with `\` or `%` are done in various places on 480bbfda8aSniaan as-needed basis. 49