Doxygen Documentation
This page provides background and instructions to setup the Doxygen documentation sytem. Doxygen is used to parse the source code for suitable comment blocks to automatically generate clean Freespace 2 Open documentation in a number of formats.
Doxygen uses a small text file, called a Doxyfile, as a script to analyse source code and produce the required output formats.
Doxygen's ease of regenerating documentation from source code allows the production of up to date documentation reflecting the latest source code changes at any time.
Contents
Getting Doxygen
From the Doxygen website, "Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D."
Doxygen is an open source application available for Windows, OS X and Linux.
Steps
- Download the appropriate Doxygen release for your computer.
- Follow the standard setup instructions.
- Open the Doxygen program.
Preparing your first set of Doxygen Documentation
To prepare a fresh batch of documentation, based on the current source code, first ensure that you have checked out the latest version of the FS2_Open source code.
- Open the Doxygen GUI wizard, called Doxywizard.
- Click File and then browse to the location of your checked out copy of the FS2_Open source code.
- Select in the top level folder fs2open.Doxyfile.
- This will populate the Doxywizard with the standard settings.
- On the Run tab, click on "Run Doxygen".
When this is completed, clicking on "Show HTML output" will open your web browser pointed at the documentation output.
Accessing the prepared Doxygen Documentation
The output from Doxygen can come in many formats, including:
- HTML output for using in a standard web browser
- PDF (including hyperlinks)
- Xcode documentation sets for inclusion in the IDE
- Man pages
At present, the default outputs are HTML output and PDF (if additional support is available on your computer).
Quick overview of the underlying documentation
A full featured article on writing fully featured documentation to take advantage of Doxygen will go up shortly. An example documentation block for the static_rand_range() function in staticrand.cpp follows:
/**
* @brief Return a random integer within a range. Note: min and max are inclusive
*
* @param num Seed input number
* @param min Minimum range integer to return
* @param max Maximum range integer to return
* @return Random integer within the range
*/
int static_rand_range(int num, int min, int max)
{
int rval = static_rand(num);
rval = (rval % (max - min + 1)) + min;
CLAMP(rval, min, max);
return rval;
}
This corresponds to the following HTML output
Notes on Doxygen Style
Although you can have a number of documentation style options for Doxygen, it is recommended that you stay consistent to existing doc comments. For example, if you come across a number of comment blocks in a file that use the /** style, then it's recommended that you use that style in that file instead of, say, /*!
When documenting a enumeration or a list of variables, it may be desired to document each value per line. To do this, use the //!< character string in place of the normal // comment string on the same line of the value your documenting, or on the line immediately below it.
Useful Plugins for Common Editors
This section provides info on some useful plugins for common text editors that will aide in the documentation effort, such as automation.
Notepad++
Notepad++ offers a plugin called DoxyIt that will set up a documentation block for functions and files fairly quickly, through the Alt+Ctrl+Shift+D shortcut. The main feature is that it will automatically template the @param's for all of the function arguments.
