Difference between revisions of "Doxygen"

From The Battle for Wesnoth Wiki
m (recategorizing)
m (update the information about uploading)
Line 3: Line 3:
  
 
Wesnoth uses doxygen to generate documentation about its code as html-pages.
 
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.
+
These are uploaded daily (early in the morning (GMT)) to http://devdocs.wesnoth.org.
  
 
Developers can generate these pages locally:
 
Developers can generate these pages locally:

Revision as of 09:23, 25 April 2009

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 Doxygen comment
@ to indicate Doxygen keywords

Note quite some older code is commented in other ways (this needs to be converted to the new way).

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)
{
...
}