Difference between revisions of "Doxygen"

From The Battle for Wesnoth Wiki
Line 5: Line 5:
 
These are uploaded (currently manually by Mark de Wever) to http://devdocs.wesnoth.org.
 
These are uploaded (currently manually by Mark de Wever) 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 than 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 like "//! bla" in the code 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 37: Line 39:
 
* The detailed description can be as long as you want.
 
* The detailed description can be as long as you want.
 
It should be at least 2 lines, so doxygen does not get confused,
 
It should be at least 2 lines, so doxygen does not get confused,
thinking it found a second brief description :-)
+
e.g. thinking it found a second brief description for the same item :-)
 
   
 
   
 
* Doxygen recognizes a lot of special keywords, the most important:
 
* Doxygen recognizes a lot of special keywords, the most important:
** @file
+
** @file  - description for a file
** @param
+
** @param - description for parameters for functions etc.
** @return
+
** @return - general description of a return-value (e.g. "length of string")
** @retval
+
** @retval - description for special return-values (e.g. "-1 : error")
** @todo
+
** @todo   - Items for the todo-list

Revision as of 10:54, 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 like "//! bla" in the code 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, 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
    • @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")
    • @todo - Items for the todo-list