ITK/Doxygen Documentation: Difference between revisions
Arnaudgelas (talk | contribs) |
(→Documenting modules: This has been done!) |
||
| (14 intermediate revisions by 2 users not shown) | |||
| Line 4: | Line 4: | ||
* '''doxygen''' (see http://www.stack.nl/~dimitri/doxygen/index.html) | * '''doxygen''' (see http://www.stack.nl/~dimitri/doxygen/index.html) | ||
* '''latex''' for formulas (see http://www.latex-project.org/) | * '''latex''' for formulas (see http://www.latex-project.org/) | ||
Preferable: | |||
* '''dot''' from GraphViz for generating inheritance and dependency graph (see http://www.graphviz.org/). | |||
== Generating the Doxygen documentation == | == Generating the Doxygen documentation == | ||
* In CMake '''BUILD_DOCUMENTATION''' must be turned '''ON''' !! | * In CMake '''BUILD_DOCUMENTATION''' must be turned '''ON''' !! | ||
* Build the project as you would normally do, it will build both the ITK libraries/binaries and the doxygen documentation | * Build the project as you would normally do, it will build both the ITK libraries/binaries and the doxygen documentation | ||
Doxygen will then generate the documentation for enabled modules. So if you want to generate the complete doxygen documentation you would need to turn ON ITK_BUILD_ALL_MODULES. | |||
== | == Documenting == | ||
=== classes === | |||
== | |||
Here is a simple and minimal example: | Here is a simple and minimal example: | ||
| Line 53: | Line 46: | ||
/** you can directly write the documentation for PixelType */ | /** you can directly write the documentation for PixelType */ | ||
typedef PixelType T1; | typedef PixelType T1; | ||
} | }; | ||
</source> | </source> | ||
== | List of most common doxygen commands: | ||
* '''\class''' see [http://www.stack.nl/~dimitri/doxygen/commands.html#cmdclass command documentation] | |||
* '''\brief''' see [http://www.stack.nl/~dimitri/doxygen/commands.html#cmdbrief command documentation] | |||
* '''\tparam''' see [http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtparam command documentation] | |||
* '''\sa''' see [http://www.stack.nl/~dimitri/doxygen/commands.html#cmdsa command documentation] | |||
=== Methods / Functions === | |||
<source lang="cpp"> | |||
/** \brief You can write here a short description of Method1 | |||
You can there write a more detailed documentation for Method1. | |||
\param[in] iP1 you can write documentation for the first parameter which is an input parameter | |||
\param[in] iValue you can write documentation for the second parameter which is an input parameter | |||
\param[out] oValue you can write documentation for the third parameter which is an output parameter | |||
\param[in,out] ioP2 you can write documentation for the fourth parameter which is an input/output parameter | |||
\return description here about the return value | |||
*/ | |||
int Method1( PixelType iP1, unsigned int iValue, unsigned int& oValue, PixelType& ioP2 ) const | |||
</source> | |||
List of most common doxygen commands: | |||
* '''\param''' see [http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam command documentation] | |||
* '''\return''' see [http://www.stack.nl/~dimitri/doxygen/commands.html#cmdreturn command documentation] | |||
== Creating links to wiki examples == | |||
== Maintaining the documentation == | == Maintaining the documentation == | ||
== Suppressing and preventing Doxygen warnings == | == Suppressing and preventing Doxygen warnings == | ||
Latest revision as of 03:03, 11 February 2012
Dependencies
Generating a complete doxygen documentation requires (apart from cmake and ITK source code)
- doxygen (see http://www.stack.nl/~dimitri/doxygen/index.html)
- latex for formulas (see http://www.latex-project.org/)
Preferable:
- dot from GraphViz for generating inheritance and dependency graph (see http://www.graphviz.org/).
Generating the Doxygen documentation
- In CMake BUILD_DOCUMENTATION must be turned ON !!
- Build the project as you would normally do, it will build both the ITK libraries/binaries and the doxygen documentation
Doxygen will then generate the documentation for enabled modules. So if you want to generate the complete doxygen documentation you would need to turn ON ITK_BUILD_ALL_MODULES.
Documenting
classes
Here is a simple and minimal example:
<source lang="cpp"> /** \class MyAwesomeClass \brief Short Description of MyAwesomeClass
Here you can start writing a more detailed documentation for MyAwesomeClass.
To document each template parameters: \tparam T1 documentation for the first type \tparam T2 documentation for the second type \tparam VDimension documentation about the third template parameter which seems to be related to the Dimension
You can make implicit references to any other ITK class, by just writing their names, e.g. Image, ImageRegion...
Or you can create make a dedicated section "see also": \sa Image \sa ImageRegion
- /
template< class T1, typename T2, unsigned int VDimension > class MyAwesomeClass { public:
/** you can directly write the documentation for PixelType */ typedef PixelType T1;
}; </source>
List of most common doxygen commands:
- \class see command documentation
- \brief see command documentation
- \tparam see command documentation
- \sa see command documentation
Methods / Functions
<source lang="cpp"> /** \brief You can write here a short description of Method1
You can there write a more detailed documentation for Method1. \param[in] iP1 you can write documentation for the first parameter which is an input parameter \param[in] iValue you can write documentation for the second parameter which is an input parameter \param[out] oValue you can write documentation for the third parameter which is an output parameter \param[in,out] ioP2 you can write documentation for the fourth parameter which is an input/output parameter \return description here about the return value
- /
int Method1( PixelType iP1, unsigned int iValue, unsigned int& oValue, PixelType& ioP2 ) const </source>
List of most common doxygen commands:
- \param see command documentation
- \return see command documentation
