Doxygen

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 by running 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 from the code, special comments 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 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 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.

• The detailed description can be as long as you want.

It should be at least 2 lines, so doxygen does not get confused, thinking it found a second brief description :-)

• Doxygen recognizes a lot of special keywords, the most important:
  • @file
  • @param
  • @return
  • @retval
  • @todo