Doxygen
From Wesnoth
Doxygen is a documentation system for C++, C, Java, Python and other language, see http://www.stack.nl/~dimitri/doxygen/index.html.
Wesnoth uses doxygen to generate documentation about its code as html-pages. These are uploaded daily (early in the morning (GMT)) to http://devdocs.wesnoth.org.
Developers can generate these pages locally: in the directory wesnoth/, run the command doxygen Doxyfile
It runs for about 5 minutes, producing about 50 MB of html and graphics. The startpage can then be found at wesnoth/doc/doxygen/html/index.html
To get meaningful documentation, special comments in the code are used, like " /// Calculate X " :
- In front of some item (class, function, struct, whatever), as in
/// Show titlepage with logo TITLE_RESULT show_title(game_display& screen, config& tips_of_day, int* ntip); ...
- just behind some item (variables, enums etc.), as in
enum TITLE_RESULT { TUTORIAL = 0, ///< Start special campaign 'tutorial'
NEW_CAMPAIGN, ///< Let user select a campaign to play
...
For nice, short examples see titlescreen.hpp and titlescreen.cpp at http://devdocs.wesnoth.org/files.html
Doxygen is quite flexible, and supports a lot of commands to customize and fine-tune
the resulting documentation, see http://www.stack.nl/~dimitri/doxygen/commands.html
More details
Doxygen needs some config-files (Doxyfile, doc/doxygen/*.html ...). For wesnoth, these have already been set up.
About every item, doxygen keeps a brief and a detailed description.
- The brief description should be short, i.e. a single line.
With the option "JAVADOC_AUTOBRIEF", the first sentence of the comment up to the first dot or linebreak is taken as the brief description. Otherwise, a blank line is used to separate brief and detailed description.
- The detailed description can be as long as you want.
It should be at least 2 lines, so doxygen does not get confused, e.g. thinking it found a second brief description for the same item :-)
- Doxygen recognizes a lot of special keywords, the most important:
- @file - description for a file
- @todo - mark items for a special todo-list
- @param - description for parameters for functions etc.
- @return - general description of a return-value (e.g. "length of string")
- @retval - description for special return-values (e.g. "-1 : error")
An an example, see fade_logo in titlescreen.cpp
How to document
Doxygen offers quite some options to document items the preferred way in
Wesnoth is:
/// to indicate the comment is a Doxygen comment
/** alternatively to start a Doxygen block comment which must end in */
@ to indicate Doxygen keywords
The following sections describe the preferred way to document certain items
functions
In the .hpp there will be a brief 1 line description
In the .cpp there will be a brief description (same as in the header) and a longer description. The following parameters can be used
- @param - description for a parameter
- @param[in] - description for a parameter if used as input parameter (only makes sense if @param[out] is also used)
- @param[out] - description for a parameter if used as output parameter
- @return - general description of a return-value (e.g. "length of string")
- @retval - description for special return-values (e.g. "-1 : error")
example .hpp
/// lets you visit a bar int foo(void* bar, int foobar);
example .cpp
/** lets you visit a bar
*
* foo is an action which lets you visit various bars in the
* galaxy, which can be rather nice.
*
* @param[in] foo points to the current bar object
* @param[out] foo points to the new bar object
* @param foobaar does nothing but was nice to allow a second parameter
*
* @return the number of bars visited
* @retval -1 no bars visited, something bad happened
* @retval 42 you feel rather enlightened and know the ultimate answer, if you only could remember the question
*/
int foo(void* bar, int foobar)
{
...
}