Doxygen Documentation - Revision history

Echelon9: Reflect source code hosting via Git

2015-05-03T04:07:50Z

Reflect source code hosting via Git

← Older revision		Revision as of 04:07, 3 May 2015
Line 24:		Line 24:
	[[Image:Run tab.png‎\|right\|thumb\|150px\|''Doxygen's GUI wizard after compiling the documentation'']]		[[Image:Run tab.png‎\|right\|thumb\|150px\|''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~~.		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.		* 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~~.		* 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.		* Select in the top level folder fs2open.Doxyfile.
	* This will populate the Doxywizard with the standard settings.		* This will populate the Doxywizard with the standard settings.

Z64555: Added section on Style consistance, Added section for useful plugins

2013-12-13T18:54:35Z

Added section on Style consistance, Added section for useful plugins

← Older revision		Revision as of 18:54, 13 December 2013
Line 71:		Line 71:

	[[Category:Source Code Project]]		[[Category:Source Code Project]]


			==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 [http://sourceforge.net/projects/doxyit/ 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.

Echelon9: Update web links to the doxygen.org vhost

2011-02-26T23:23:42Z

Update web links to the doxygen.org vhost

← Older revision		Revision as of 23:23, 26 February 2011
Line 8:		Line 8:

	==Getting Doxygen==		==Getting Doxygen==
	From [http://www.~~stack.nl/~dimitri/~~doxygen~~/index~~.~~html~~ 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."		From [http://www.doxygen.org 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.		Doxygen is an open source application available for Windows, OS X and Linux.
Line 14:		Line 14:
	'''Steps'''		'''Steps'''

	* Download [http://www.~~stack~~.~~nl/~dimitri/doxygen~~/download.html#latestsrc the appropriate Doxygen release] for your computer.		* Download [http://www.doxygen.org/download.html#latestsrc the appropriate Doxygen release] for your computer.
	* Follow the standard setup instructions.		* Follow the standard setup instructions.
	* Open the Doxygen program.		* Open the Doxygen program.

Echelon9: Created page with "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 gen…"

2011-02-26T01:17:17Z

Created page with "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 gen…"

New page

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.

[[Image:Doxygen.png‎|right|110px]]

==Getting Doxygen==
From [http://www.stack.nl/~dimitri/doxygen/index.html 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 [http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc 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.}}
[[Image:Wizard tab.png‎|right|thumb|150px|''Doxygen's GUI wizard after opening the fs2open.Doxyfile'']]
[[Image:Run tab.png‎|right|thumb|150px|''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==
[[Image:Browser view.png‎|right|thumb|150px|''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

[[Image:Static rand range.png‎|''Documentation for the static_rand_range() function in HTML output'']]

[[Category:Source Code Project]]