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.

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

Note: The Doxygen GUI wizard layout is nearly identical between platforms. Windows has been shown here for simplicity.

Doxygen's GUI wizard after opening the fs2open.Doxyfile

Doxygen's GUI wizard after compiling the documentation

To prepare a fresh batch of documentation, based on the current source code, first ensure that you have SVN checked out the latest version of the FS2_Open SCP.

• Open the Doxygen GUI wizard, called Doxywizard.
• Click File and then browse to the location of your SVN checked out copy of the FS2_Open SCP.
• 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

Doxygen's Documentation in HTML form

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