Difference between revisions of "Doxygen"

From The Battle for Wesnoth Wiki
(example)
(Updated to reflect a bit better our commenting style. Not sure everything else on this page is 100% accurate.)
 
(14 intermediate revisions by 4 users not shown)
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 by running the command
+
Developers can generate these pages locally:
 +
in the directory wesnoth/, run the command
 
'''doxygen Doxyfile'''
 
'''doxygen Doxyfile'''
 +
 
It runs for about 5 minutes, producing about 50 MB of html and graphics.
 
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
+
The startpage can then be found at wesnoth/doc/doxygen/html/index.html
  
To get meaningful documentation from the code, special comments are used:
+
To get meaningful documentation, special comments in the code are used,
 +
like " '''/// Calculate X''' " :
  
* In front of some item (class, function, struct, whatever),
+
* In front of some item (class, function, struct, whatever), as in
  as in "//! Show titlepage with logo"
+
  /// Show titlepage with logo
 +
TITLE_RESULT show_title(game_display& screen, config& tips_of_day, int* ntip);
 +
...
  
* just behind some item (variables, enums etc.),  
+
* just behind some item (variables, enums etc.), as in
  as in "enum TITLE_RESULT { TUTORIAL = 0,      //!< Start special campaign 'tutorial'"
+
  enum TITLE_RESULT { TUTORIAL = 0,      ///< Start special campaign 'tutorial'
 +
                    NEW_CAMPAIGN,      ///< Let user select a campaign to play
 +
...
  
For nice, short examples see titlescreen.cpp and titlescreen.cpp
+
For nice, short examples see titlescreen.hpp and titlescreen.cpp
 +
at http://devdocs.wesnoth.org/files.html
  
  
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
  
... More details ...
+
== 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
 +
** &nbsp;
 +
** @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: <br>
 +
/// to indicate the comment is a Doxygen comment<br>
 +
/** alternatively to start a Doxygen block comment which must end in */<br>
 +
@ to indicate Doxygen keywords<br>
 +
 
 +
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)
 +
{
 +
...
 +
}
 +
 
 +
[[Category:Development]]

Latest revision as of 02:07, 18 August 2010

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)
{
...
}
This page was last edited on 18 August 2010, at 02:07.