Difference between revisions of "Doxygen"

From The Battle for Wesnoth Wiki
Line 12: Line 12:
 
The startpage can than be found at wesnoth/doc/doxygen/html/index.html
 
The startpage can than be found at wesnoth/doc/doxygen/html/index.html
  
To get meaningful documentation, special comments like "//! bla" in the code are used:
+
To get meaningful documentation, special comments in the code
 +
like "//! Calculate X" are used:
  
 
* In front of some item (class, function, struct, whatever), as in  
 
* In front of some item (class, function, struct, whatever), as in  
Line 27: Line 28:
  
  
Doxygen supports a lot of commands to customize and fine-tune
+
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
 
the resulting documentation, see http://www.stack.nl/~dimitri/doxygen/commands.html
  
Line 36: Line 37:
  
 
Doxygen keeps about every item a brief and a detailed description.
 
Doxygen keeps about every item a brief and a detailed description.
 +
 
* The brief description should be short, i.e. a single line.
 
* The brief description should be short, i.e. a single line.
 
With the option "JAVADOC_AUTOBRIEF", the first sentence of the comment
 
With the option "JAVADOC_AUTOBRIEF", the first sentence of the comment
 
up to the first dot or linebreak is taken as the brief description.
 
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.
 
* The detailed description can be as long as you want.
Line 47: Line 50:
 
** @file  - description for a file
 
** @file  - description for a file
 
** @todo  - Items for the todo-list
 
** @todo  - Items for the todo-list
 
+
*
 
** @param  - description for parameters for functions etc.
 
** @param  - description for parameters for functions etc.
 
** @return - general description of a return-value (e.g. "length of string")
 
** @return - general description of a return-value (e.g. "length of string")
 
** @retval - description for special return-values (e.g. "-1 : error")
 
** @retval - description for special return-values (e.g. "-1 : error")
 
An an example, see ''fade_logo'' in titlescreen.cpp
 
An an example, see ''fade_logo'' in titlescreen.cpp

Revision as of 12:00, 15 August 2007

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 (currently manually by Mark de Wever) 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 than be found at wesnoth/doc/doxygen/html/index.html

To get meaningful documentation, special comments in the code like "//! Calculate X" are used:

  • 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


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.

Doxygen keeps about every item 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 - Items for the 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