OpenCV  4.0.0-alpha
Open Source Computer Vision
Writing documentation for OpenCV

Table of Contents

Doxygen overview

Intro

Doxygen is documentation generation system with a lot of great features, such as:

OpenCV library existing documentation has been converted to doxygen format.

Installation

Please, check official download and installation pages. Some linux distributions can also provide doxygen packages.

Generate documentation

Quick start

Note
These instructions are specific to OpenCV library documentation, other projects can use different layout scheme and documenting agreements.

Documentation locations

Whole documentation is gathered from many different places:

Following scheme represents common documentation places for opencv repository:

<opencv>
├── doc - doxygen config files, root page (root.markdown.in), BibTeX file (opencv.bib)
│   ├── tutorials - tutorials hierarchy (pages and images)
│   └── py_tutorials - python tutorials hierarchy (pages and images)
├── modules
│   └── <modulename>
│      ├── doc - documentation pages and images for module
│      └── include - code documentation in header files
└── samples - place for all code examples
├── cpp
│ └── tutorial_code - place for tutorial code examples
└── ...
Note
Automatic code parser looks for all header files (".h, .hpp" except for ".inl.hpp; .impl.hpp; _detail.hpp") in include folder and its subfolders. Some module-specific instructions (group definitions) and documentation should be put into "include/opencv2/<module-name>.hpp" file.
You can put C++ template implementation and specialization to separate files (".impl.hpp") ignored by doxygen.
Files in src subfolder are not parsed, because documentation is intended mostly for the library users, not developers. But it still is possible to generate full documentation by customizing processed files list in cmake script (doc/CMakeLists.txt) and doxygen options in its configuration file (doc/Doxyfile.in).

Since version 3.0 all new modules are placed into opencv_contrib repository, it has slightly different layout:

<opencv_contrib>
└── modules
└── <modulename>
├── doc - documentation pages and images, BibTeX file (<modulename>.bib)
├── include - code documentation in header files
├── samples - place for code examples for documentation and tutorials
└── tutorials - tutorial pages and images

Example

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:

Produced reference item looks like this:

doxygen-2.png
Reference link

The "More..." link brings you to the function documentation:

doxygen-1.png
Function documentation

Another example

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:

Produced documentation block looks like this:

doxygen-3.png
Enumeration documentation

More details

Command prefix

Doxygen commands starts with @ or \ sign:

@brief ...
or
\brief ...

Comment syntax

Doxygen comment can have different forms:

C-style:
/** ... */
or
/*! ... */

C++-style
//! ...
or
/// ...

Lines can start with '*':
/**
 * ...
 * ...
 */

Can be placed after documented entity:
//!< ...
/**< ... */

Paragraph end

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

Naming

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

Supported Markdown

Doxygen supports Markdown formatting with some extensions. Short syntax reference is described below, for details visit Markdown support.

lists

Bulleted:
- item1
- item2
Numbered:
1. item1
2. item2
or
-# item1
-# item2

emphasis

_italic_
__bold__
use html in complex cases:
<em>"path/to/file"</em>

links

explicit link:
[OpenCV main site](http://opencv.org)
automatic links:
<http://opencv.org>
or even:
http://opencv.org

images

![image caption](image path)

headers

Level1
======
Level2
------
### Level3
#### Level4

header id

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

page id

Each page should have additional Level1 header at the beginning with page title and identifier:

Writing documentation for OpenCV {#tutorial_documentation}
================================

tables

Example from doxygen documentation:

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

Commonly used commands

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.

Basic commands

Code inclusion commands

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
Note
Currently most of such partial inclusions are made with dontinclude command for compatibility with the old rST documentation. But newly created samples should be included with the snippet command, since this method is less affected by the changes in processed file.

Toggle buttons inclusion commands

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:

Buttons Example

As you can see, the buttons are added automatically under the previous heading.

Grouping commands

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".

Note
Doxygen groups are called "modules" and are shown on "Modules" page.
/**
@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
/**
@}
*/

Publication reference

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}
}
Note
Try not to add publication duplicates because it can confuse documentation readers and writers later.

Then make reference with cite command:

@cite Bradski98
Note
To get BibTeX record for the publications one can use Google Scholar. Once the publication have been found - follow its "Cite" link and then choose "BibTeX" option:
scholarship_cite_dialog.png

Step-by-step

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.

Document the function

  1. Add empty doxygen comment preceding function definition.
  2. Add brief command with short description of function meaning at the beginning.
  3. Add detailed description of the function.
  4. Optional: insert formulas, images and blocks of example code to illustrate complex cases
  5. Optional: describe each parameter using the param command.
  6. Optional: describe return value of the function using the returns command.
  7. Optional: add "See also" section with links to similar functions or classes
  8. Optional: add bibliographic reference if any.
  9. Test your code. (Python: "make check_pylint")
  10. Generate doxygen documentation and verify results.

Write the tutorial

  1. Formulate the idea to be illustrated in the tutorial.
  2. 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).

  3. 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:

    • To save simple graph-like images use lossless ".png" format.
    • For photo-like images - lossy ".jpg" format.
    • Numbers will be inserted as plain text, possibly formatted as table.
    • Video should be uploaded on YouTube.
  4. Create new tutorial page (".markdown"-file) in corresponding location (see here), and place all image files near it (or in "images" subdirectory). Also put your example application file and make sure it is compiled together with the OpenCV library when -DBUILD_EXAMPLES=ON option is enabled on cmake step.
  5. Modify your new page:
    • Add page title and identifier, usually prefixed with "tutorial_" (see here). You can add a link to the previous and next tutorial using the identifier
      @prev_tutorial{identifier}
      @next_tutorial{identifier}
      Warning
      Do not write the hashtag (#), example:
      Incorrect:
      @prev_tutorial{#tutorial_documentation} 
      Correct:
      @prev_tutorial{tutorial_documentation} 
    • Add brief description of your idea and tutorial goals.
    • Describe your program and/or its interesting pieces.
    • 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}
    • Add bibliographic references if any (see here).
  6. Add newly created tutorial to the corresponding table of contents. Just find "table_of_content_*.markdown" file with the needed table and place new record in it similar to existing ones.
    -   @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.
  7. Generate doxygen documentation and verify results.

References