Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Changes between Initial Version and Version 1 of code/tools/Doxygen


Ignore:
Timestamp:
Sep 21, 2008, 8:39:40 PM (16 years ago)
Author:
landauf
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • code/tools/Doxygen

    v1 v1  
     1= Doxygen =
     2[[TracNav(TracNav/TOC_Development)]]
     3[[TOC]]
     4
     5[http://www.doxygen.org Doxygen] is a programm that generates a developers manual out of special comments in .cc and .h files.
     6
     7The main Tags we use are described below:
     8
     9
     10
     11== Introductory Comment ==
     12Every file that contains source code must be documented with an introductory comment that provides information on the file name and its contents:
     13{{{
     14/**
     15@file
     16@brief
     17    A brief description.
     18
     19    More description... (new paragraph after @brief)
     20*/
     21}}}
     22Note: try not to fill in the filename. It is obvious and the comment compiler (Doxygen) will do it automatically and you don't have to adjust it when renaming the file.
     23
     24== Classes and Structs ==
     25In the header file, just above the class declaration, explain what the class does and where it is used. You could even add an example if it helps understanding the class.
     26{{{
     27/**
     28@brief
     29    A brief description.
     30    More brief description.
     31
     32    Details follow here.
     33    Maybe an example or something.
     34*/
     35class ClassName
     36{
     37    ...
     38}}}
     39
     40== Class Members ==
     41Add a brief description to every member of a class:
     42{{{
     43    private:
     44        int value_;           //!< A brief description
     45        int longerValueName_; //!< A brief description
     46}}}
     47The < after //! indicates that the member is located in front of the comment instead of after the comment.
     48
     49If you need a more detailed description, use:
     50{{{
     51    private:
     52        int value_; //!< A detailed description
     53                    //!< More detailed description
     54                    //!< ...
     55}}}
     56or
     57{{{
     58    private:
     59        int value_; /**<
     60                        A detailed description
     61                        More detailed description
     62                        ...
     63                    */
     64}}}
     65
     66== Functions ==
     67Doxygen documentation (javadoc like for C++) is placed in the source file, just above the function header. If the function is inline, place the comment there but keep it short. [[br]]
     68When writing documentation in the source file don't make it all jam-packed to enhance readability. Here is an example to demonstrate formatting:
     69{{{
     70/**
     71@brief
     72    A brief description.
     73    More brief description.
     74
     75    Details follow here.
     76    Maybe an example or something.
     77@param param1
     78    Parameter description for parameter named 'param1'
     79@param param2
     80    Parameter description for parameter named 'param2'
     81@return
     82    Describe what the function returns
     83@note
     84    Something important to remember.
     85@author
     86    The mighty whoever
     87*/
     88returntype functionname(type1 param1, type2 param2)
     89{
     90    ...
     91}}}
     92
     93== Inline Functions ==
     94Inline functions need documentation as well, but we don't want a messy headerfile. Keep the comments short and put all doxygen code on one line:
     95{{{
     96/** @brief A brief description. @param param1 description [...] @return description */
     97inline returntype functionname(type1 param1 [, ...]) { ... }
     98}}}
     99
     100== Full Example ==
     101MyClass.h file:
     102{{{
     103/**
     104@file
     105@brief
     106    A brief description of the file, the classes and macros; links to other files.
     107
     108    More description... (new paragraph after @brief)
     109    Maybe an example or something.
     110*/
     111
     112/**
     113@brief
     114    A brief description of the class
     115
     116    Details follow here.
     117    More details...
     118*/
     119class MyClass
     120{
     121    public:
     122        /** @brief A brief description of the inline function. @return description */
     123        inline int getValue() const { return this->value_; }
     124       
     125        void setValue(int value);
     126
     127    private:
     128        int value_; //!< A brief description of the value
     129};
     130}}}
     131
     132MyClass.cc:
     133{{{
     134/**
     135@brief
     136    A brief description of the function.
     137    More brief description.
     138
     139    Details follow here.
     140    Maybe an example or something.
     141
     142@param value
     143    Parameter description for parameter named 'value'
     144*/
     145void MyClass::setValue(int value)
     146{
     147    if (value > 0 && value < 10)
     148        this->value_ = value;
     149}
     150}}}
     151
     152== Also see ==
     153  * [http://www.stack.nl/~dimitri/doxygen/docblocks.html this] for more info on doxygen-tags
     154  * [http://www.stack.nl/~dimitri/doxygen/commands.html this] for all possible doxygen-tags