OpenCV
3.4.2
Open Source Computer Vision
|
Doxygen is documentation generation system with a lot of great features, such as:
OpenCV library existing documentation has been converted to doxygen format.
Please, check official download and installation pages. Some linux distributions can also provide doxygen packages.
Whole documentation is gathered from many different places:
Following scheme represents common documentation places for opencv repository:
Since version 3.0 all new modules are placed into opencv_contrib repository, it has slightly different layout:
To add documentation for functions, classes and other entities, just insert special comment prior its definition. Like this:
/** @brief Calculates the exponent of every array element. The function exp calculates the exponent of every element of the input array: \f[ \texttt{dst} [I] = e^{ src(I) } \f] The maximum relative error is about 7e-6 for single-precision input and less than 1e-10 for double-precision input. Currently, the function converts denormalized values to zeros on output. Special values (NaN, Inf) are not handled. @param src input array. @param dst output array of the same size and type as src. @sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude */ CV_EXPORTS_W void exp(InputArray src, OutputArray dst);
Here you can see:
/** ... */
brief
denotes following paragraph is a brief description @brief
f[
and f]
commands \f[ ... \f]
param
denotes following word is name of the parameter and following text is description of the parameter; all parameters are placed in a list @param
sa
starts "See also" paragraph containing references to some classes, methods, pages or URLs. @sa
Produced reference item looks like this:
The "More..." link brings you to the function documentation:
Different comment syntax can be used for one-line short comments:
//! type of line enum LineTypes { FILLED = -1, LINE_4 = 4, //!< 4-connected line LINE_8 = 8, //!< 8-connected line LINE_AA = 16 //!< antialiased line };
Here:
//!
<
denotes this comment is located after documented entity //!<
Produced documentation block looks like this:
Doxygen commands starts with @
or \
sign:
@brief ... or \brief ...
Doxygen comment can have different forms:
C-style: /** ... */ or /*! ... */ C++-style //! ... or /// ... Lines can start with '*': /** * ... * ... */ Can be placed after documented entity: //!< ... /**< ... */
To end paragraph, insert empty line or any command starting new paragraph:
@brief brief description paragraph brief continues new paragraph @note new note paragraph note paragraph continues another paragraph paragraph continues
Pages, anchors, groups and other named entities should have unique name inside the whole project. It is a good idea to prefix such identifiers with module name:
@page core_explanation_1 Usage explanation @defgroup imgproc_transform Image transformations @anchor mymodule_interesting_note
Doxygen supports Markdown formatting with some extensions. Short syntax reference is described below, for details visit Markdown support.
Bulleted: - item1 - item2 Numbered: 1. item1 2. item2 or -# item1 -# item2
_italic_ __bold__ use html in complex cases: <em>"path/to/file"</em>
explicit link: [OpenCV main site](http://opencv.org) automatic links: <http://opencv.org> or even: http://opencv.org
![image caption](image path)
Level1 ====== Level2 ------ ### Level3 #### Level4
You can assign a unique identifier to any header to reference it from other places.
Header {#some_unique_identifier} ------ ... See @ref some_unique_identifier for details
Each page should have additional Level1 header at the beginning with page title and identifier:
Writing documentation for OpenCV {#tutorial_documentation} ================================
Example from doxygen documentation:
First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell
Most often used doxygen commands are described here with short examples. For the full list of available commands and detailed description, please visit Command reference.
param - description of function argument.
Multiple adjacent statements are merged into one list. If argument with this name is not found in actual function signature - doxygen warning will be produced. Function can have either no documented parameters, either all should be documented.
ref
command. It can be used in pages only.ref - explicit reference to a named section, page or anchor.
If such entity can not be found - doxygen warning will be generated. This command has an optional argument - link text.
Doxygen also generates some links automatically: if text contains word which can be found in documented entities - reference will be generated. This functionality can be disabled by prefixing the word with %
symbol.
Explicit reference: @ref MyClass Explicit named reference: @ref example_page "Example page" Implicit reference: cv::abc::MyClass1 or just MyClass1 Disable implicit reference: %MyClass1
f - formula
Inline formulas are bounded with f$
command:
\f$ ... \f$
Block formulas - with f[
and f]
commands:
\f[ ... \f]
To mark some text as a code in documentation, code and endcode commands are used.
@code float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101), borderInterpolate(-5, img.cols, cv::BORDER_WRAP)); @endcode
Syntax will be highlighted according to the currently parsed file type (C++ for .hpp, C for .h) or you can manually specify it in curly braces:
@code{.xml}
To include whole example file into documentation, include and includelineno commands are used. The file is searched in common samples locations, so you can specify just its name or short part of the path. The includelineno version also shows line numbers but prevents copy-pasting since the line numbers are included.
@include samples/cpp/test.cpp
If you want to include some parts of existing example file - use snippet command.
First, mark the needed parts of the file with special doxygen comments:
//! [var_init] int a = 0; //! [var_init]
Then include this snippet into documentation:
@snippet samples/cpp/test.cpp var_init
Toggle buttons are used to display the selected configuration (e.g. programming language, OS, IDE).
To use the buttons in documentation, add_toggle and end_toggle commands are used.
The command add_toggle can be
Example:
@add_toggle{Button Name} text / code / doxygen commands @end_toggle
For example using toggle buttons with text and code snippets:
### Buttons Example @add_toggle_cpp Text for C++ button @snippet samples/cpp/tutorial_code/introduction/documentation/documentation.cpp hello_world @end_toggle @add_toggle_java Text for Java button @snippet samples/java/tutorial_code/introduction/documentation/Documentation.java hello_world @end_toggle @add_toggle_python Text for Python button @snippet samples/python/tutorial_code/introduction/documentation/documentation.py hello_world @end_toggle
Result looks like this:
As you can see, the buttons are added automatically under the previous heading.
All code entities should be put into named groups representing OpenCV modules and their internal structure, thus each module should be associated with a group with the same name. Good place to define groups and subgroups is the main header file for this module: "<module>/include/opencv2/<module>.hpp".
/** @defgroup mymodule My great module optional description @{ @defgroup mymodule_basic Basic operations optional description @defgroup mymodule_experimental Experimental operations optional description @} */
To put classes and functions into specific group, just add ingroup
command to its documentation, or wrap the whole code block with addtogroup
command:
/** @brief Example function @ingroup mymodule */ or /** @addtogroup mymodule_experimental @{ */ ... several functions, classes or enumerations here /** @} */
Use cite command to insert reference to related publications listed in Bibliography page.
First, add publication BibTeX record into "<opencv>/doc/opencv.bib" or "<opencv_contrib>/modules/<module>/doc/<module>.bib" file:
@ARTICLE{Bradski98, author = {Bradski, Gary R}, title = {Computer vision face tracking for use in a perceptual user interface}, year = {1998}, publisher = {Citeseer} }
Then make reference with cite command:
@cite Bradski98
Steps described in this section can be used as checklist during documentation writing. It is not necessary to do things in the same order, but some steps really depend on previous. And of course these steps are just basic guidelines, there is always a place for creativity.
Make the example application, simple enough to be understood by a beginning developer. Be laconic and write descriptive comments, don't try to avoid every possible runtime error or to make universal utility. Your goal is to illustrate the idea. And it should fit one source file!
If you want to insert code blocks from this file into your tutorial, mark them with special doxygen comments (see here).
If you want to write the tutorial in more than one programming language, use the toggle buttons for alternative comments and code (see here).
Collect results of the application work. It can be "before/after" images or some numbers representing performance or even a video.
Save it in appropriate format for later use in the tutorial:
-DBUILD_EXAMPLES=ON
option is enabled on cmake step.@prev_tutorial{identifier} @next_tutorial{identifier}
@prev_tutorial{#tutorial_documentation}Correct:
@prev_tutorial{tutorial_documentation}
Describe your results, insert previously added images or other results.
To add a youtube video, e.g. www.youtube.com/watch?v= ViPN810E0SU, use youtube{Video ID}:
@youtube{ViPN810E0SU}
- @subpage tutorial_windows_visual_studio_image_watch _Languages:_ C++, Java, Python _Compatibility:_ \>= OpenCV 2.4 _Author:_ Wolf Kienzle You will learn how to visualize OpenCV matrices and images within Visual Studio 2012.As you can see it is just a list item with special subpage command which marks your page as a child and places it into the existing pages hierarchy. Add compatibility information, authors list and short description. Also note the list item indent, empty lines between paragraphs and special italic markers.