1 Writing documentation for OpenCV {#tutorial_documentation}
2 ================================
4 @prev_tutorial{tutorial_display_image}
5 @next_tutorial{tutorial_transition_guide}
10 Doxygen overview {#tutorial_documentation_overview}
13 Intro {#tutorial_documentation_intro}
16 [Doxygen] is documentation generation system with a lot of great features, such as:
17 - parse program sources to produce actual and accurate documentation
18 - check documentation for errors
19 - insert images and formulas
20 - use markdown syntax and plain HTML for precise text formatting
21 - generate documentation in many different formats
23 OpenCV library existing documentation has been converted to doxygen format.
25 Installation {#tutorial_documentation_install}
28 Please, check official [download][Doxygen download] and [installation][Doxygen installation] pages.
29 Some linux distributions can also provide doxygen packages.
31 Generate documentation {#tutorial_documentation_generate}
32 ----------------------
34 - Get the OpenCV sources (version 3.0 and later)
35 - _Optional:_ get the OpenCV_contrib sources
36 - Create build directory near the sources folder(s) and go into it
37 - Run cmake (assuming you put sources to _opencv_ folder):
39 cmake -DBUILD_DOCS=ON ../opencv
41 Or if you get contrib sources too:
43 cmake -DBUILD_DOCS=ON -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ../opencv
49 - Open <i>doc/doxygen/html/index.html</i> file in your favorite browser
50 - Test your Python code:
55 Quick start {#tutorial_documentation_quick_start}
58 @note These instructions are specific to OpenCV library documentation, other projects can use
59 different layout scheme and documenting agreements.
61 Documentation locations {#tutorial_documentation_quick_start_1}
62 -----------------------
64 Whole documentation is gathered from many different places:
66 - __source code__ entities, like classes, functions or enumerations, should be documented in
67 corresponding header files, right prior entity definition. See examples in next sections.
69 - __pages__ are good place to put big pieces of text with images and code examples not directly
70 connected with any source code entity. Pages should be located in separate files and
71 contained in several predefined places. This tutorial is example of such page.
73 - __images__ can be used to illustrate described things. Usually located at the same places as pages,
74 images can be inserted to any place of the documentation.
76 - __code examples__ show how to use the library in real applications. Each sample is
77 self-contained file which represents one simple application. Parts of these files can be
78 included into documentation and tutorials to demonstrate function calls and objects collaboration.
80 - __BibTeX references__ are used to create one common bibliography. All science books, articles and
81 proceedings served as basis for library functionality should be put in this reference list.
83 Following scheme represents common documentation places for _opencv_ repository:
86 ├── doc - doxygen config files, root page (root.markdown.in), BibTeX file (opencv.bib)
87 │ ├── tutorials - tutorials hierarchy (pages and images)
88 │ └── py_tutorials - python tutorials hierarchy (pages and images)
91 │ ├── doc - documentation pages and images for module
92 │ └── include - code documentation in header files
93 └── samples - place for all code examples
95 │ └── tutorial_code - place for tutorial code examples
99 @note Automatic code parser looks for all header files (<i>".h, .hpp"</i> except for <i>".inl.hpp;
100 .impl.hpp; _detail.hpp"</i>) in _include_ folder and its subfolders. Some module-specific
101 instructions (group definitions) and documentation should be put into
102 <i>"include/opencv2/<module-name>.hpp"</i> file.
104 @note You can put C++ template implementation and specialization to separate files
105 (<i>".impl.hpp"</i>) ignored by doxygen.
107 @note Files in _src_ subfolder are not parsed, because documentation is intended mostly for the
108 library users, not developers. But it still is possible to generate full documentation by
109 customizing processed files list in cmake script (<i>doc/CMakeLists.txt</i>) and doxygen options in
110 its configuration file (<i>doc/Doxyfile.in</i>).
112 Since version 3.0 all new modules are placed into _opencv_contrib_ repository, it has slightly
118 ├── doc - documentation pages and images, BibTeX file (<modulename>.bib)
119 ├── include - code documentation in header files
120 ├── samples - place for code examples for documentation and tutorials
121 └── tutorials - tutorial pages and images
124 Example {#tutorial_documentation_quick_start_2}
127 To add documentation for functions, classes and other entities, just insert special comment prior
128 its definition. Like this:
131 /** @brief Calculates the exponent of every array element.
133 The function exp calculates the exponent of every element of the input array:
134 \f[ \texttt{dst} [I] = e^{ src(I) } \f]
136 The maximum relative error is about 7e-6 for single-precision input and less than 1e-10 for
137 double-precision input. Currently, the function converts denormalized values to zeros on output.
138 Special values (NaN, Inf) are not handled.
140 @param src input array.
141 @param dst output array of the same size and type as src.
143 @sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude
145 CV_EXPORTS_W void exp(InputArray src, OutputArray dst);
150 - special C-comment syntax denotes it is doxygen comment
151 @verbatim /** ... */ @endverbatim
153 - command `brief` denotes following paragraph is a brief description
154 @verbatim @brief @endverbatim
156 - empty line denotes paragraph end
158 - TeX formula between `f[` and `f]` commands
159 @verbatim \f[ ... \f] @endverbatim
161 - command `param` denotes following word is name of the parameter and following text is
162 description of the parameter; all parameters are placed in a list
163 @verbatim @param @endverbatim
165 - command `sa` starts "See also" paragraph containing references to some classes, methods, pages or URLs.
166 @verbatim @sa @endverbatim
168 Produced reference item looks like this:
169 ![Reference link](doxygen-2.png)
171 The "More..." link brings you to the function documentation:
172 ![Function documentation](doxygen-1.png)
175 Another example {#tutorial_documentation_quick_start_3}
178 Different comment syntax can be used for one-line short comments:
184 LINE_4 = 4, //!< 4-connected line
185 LINE_8 = 8, //!< 8-connected line
186 LINE_AA = 16 //!< antialiased line
192 - special C++-comment syntax denotes it is doxygen comment
193 @verbatim //! @endverbatim
195 - additional symbol `<` denotes this comment is located _after_ documented entity
196 @verbatim //!< @endverbatim
198 Produced documentation block looks like this:
199 ![Enumeration documentation](doxygen-3.png)
201 More details {#tutorial_documentation_quick_start_4}
206 Doxygen commands starts with `@` or `\` sign:
215 Doxygen comment can have different forms:
227 Lines can start with '*':
233 Can be placed after documented entity:
240 To end paragraph, insert empty line or any command starting new paragraph:
242 @brief brief description paragraph
247 @note new note paragraph
248 note paragraph continues
256 Pages, anchors, groups and other named entities should have unique name inside the whole project.
257 It is a good idea to prefix such identifiers with module name:
259 @page core_explanation_1 Usage explanation
260 @defgroup imgproc_transform Image transformations
261 @anchor mymodule_interesting_note
264 Supported Markdown {#tutorial_documentation_quick_start_md}
267 Doxygen supports Markdown formatting with some extensions. Short syntax reference is described
268 below, for details visit [Markdown support].
270 ### lists {#tutorial_documentation_md_list}
284 ### emphasis {#tutorial_documentation_md_emph}
289 use html in complex cases:
290 <em>"path/to/file"</em>
293 ### links {#tutorial_documentation_md_links}
297 [OpenCV main site](http://opencv.org)
304 ### images {#tutorial_documentation_md_image}
307 ![image caption](image path)
310 ### headers {#tutorial_documentation_md_head}
321 ### header id {#tutorial_documentation_md_headid}
323 You can assign a unique identifier to any header to reference it from other places.
325 Header {#some_unique_identifier}
328 See @ref some_unique_identifier for details
331 ### page id {#tutorial_documentation_md_page}
333 Each page should have additional Level1 header at the beginning with page title and identifier:
335 Writing documentation for OpenCV {#tutorial_documentation}
336 ================================
339 ### tables {#tutorial_documentation_md_table}
341 Example from doxygen documentation:
343 First Header | Second Header
344 ------------- | -------------
345 Content Cell | Content Cell
346 Content Cell | Content Cell
349 Commonly used commands {#tutorial_documentation_quick_start_5}
350 ----------------------
352 Most often used doxygen commands are described here with short examples. For the full list of
353 available commands and detailed description, please visit [Command reference].
355 ### Basic commands {#tutorial_documentation_commands_basic}
357 - __brief__ - paragraph with brief entity description
359 - __param__ - description of function argument.
361 Multiple adjacent statements are merged into one list. If argument with this name is not found
362 in actual function signature - doxygen warning will be produced. Function can have either _no_
363 documented parameters, either _all_ should be documented.
365 - __sa__ - "See also" paragraph, contains references to classes, functions, pages or URLs
367 - __note__ - visually highlighted "Note" paragraph. Multiple adjacent statements are merged into
370 - __return, returns__ - describes returned value of a function
372 - __overload__ - adds fixed text to the function description: <em>"This is an overloaded member
373 function, provided for convenience. It differs from the above function only in what argument(s)
376 - __anchor__ - places invisible named anchor, which can be referenced by `ref` command. It can be
379 - __ref__ - explicit reference to a named section, page or anchor.
381 If such entity can not be found - doxygen warning will be generated. This command has an
382 optional argument - link text.
384 Doxygen also generates some links automatically: if text contains word which can be found in
385 documented entities - reference will be generated. This functionality can be disabled by prefixing
386 the word with `%` symbol.
388 Explicit reference: @ref MyClass
389 Explicit named reference: @ref example_page "Example page"
390 Implicit reference: cv::abc::MyClass1 or just MyClass1
391 Disable implicit reference: %MyClass1
396 Inline formulas are bounded with `f$` command:
401 Block formulas - with `f[` and `f]` commands:
406 ### Code inclusion commands {#tutorial_documentation_commands_include}
408 To mark some text as a code in documentation, _code_ and _endcode_ commands are used.
411 float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
412 borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
416 Syntax will be highlighted according to the currently parsed file type (C++ for <em>.hpp</em>, C for <em>.h</em>) or
417 you can manually specify it in curly braces:
423 To include whole example file into documentation, _include_ and _includelineno_ commands are used.
424 The file is searched in common samples locations, so you can specify just its name or short part of
425 the path. The _includelineno_ version also shows line numbers but prevents copy-pasting since
426 the line numbers are included.
429 @include samples/cpp/test.cpp
432 If you want to include some parts of existing example file - use _snippet_ command.
434 First, mark the needed parts of the file with special doxygen comments:
441 Then include this snippet into documentation:
443 @snippet samples/cpp/test.cpp var_init
446 @note Currently most of such partial inclusions are made with _dontinclude_ command for
447 compatibility with the old rST documentation. But newly created samples should be included with the
448 _snippet_ command, since this method is less affected by the changes in processed file.
450 ### Toggle buttons inclusion commands {#tutorial_documentation_toggle_buttons_commands_include}
452 Toggle buttons are used to display the selected configuration (e.g. programming language, OS, IDE).
454 To use the buttons in documentation, _add_toggle_ and _end_toggle_ commands are used.
456 The command _add_toggle_ can be
457 - general: _add_toggle{Button Name}_
458 - for C++: _add_toggle_cpp_
459 - for Java: _add_toggle_java_
460 - for Python: _add_toggle_python_
464 @add_toggle{Button Name}
466 text / code / doxygen commands
471 For example using toggle buttons with text and [code](@ref tutorial_documentation_commands_include) snippets:
480 @snippet samples/cpp/tutorial_code/introduction/documentation/documentation.cpp hello_world
487 @snippet samples/java/tutorial_code/introduction/documentation/Documentation.java hello_world
493 Text for Python button
494 @snippet samples/python/tutorial_code/introduction/documentation/documentation.py hello_world
500 Result looks like this:
507 @snippet samples/cpp/tutorial_code/introduction/documentation/documentation.cpp hello_world
514 @snippet samples/java/tutorial_code/introduction/documentation/Documentation.java hello_world
520 Text for Python button
521 @snippet samples/python/tutorial_code/introduction/documentation/documentation.py hello_world
525 As you can see, the buttons are added automatically under the previous heading.
527 ### Grouping commands {#tutorial_documentation_commands_group}
529 All code entities should be put into named groups representing OpenCV modules and their internal
530 structure, thus each module should be associated with a group with the same name. Good place to
531 define groups and subgroups is the main header file for this module:
532 <em>"<module>/include/opencv2/<module>.hpp"</em>.
534 @note Doxygen groups are called "modules" and are shown on "Modules" page.
538 @defgroup mymodule My great module
541 @defgroup mymodule_basic Basic operations
543 @defgroup mymodule_experimental Experimental operations
549 To put classes and functions into specific group, just add `ingroup` command to its documentation,
550 or wrap the whole code block with `addtogroup` command:
553 /** @brief Example function
558 @addtogroup mymodule_experimental
561 ... several functions, classes or enumerations here
567 ### Publication reference {#tutorial_documentation_commands_cite}
569 Use _cite_ command to insert reference to related publications listed in @ref citelist page.
571 First, add publication BibTeX record into <i>"<opencv>/doc/opencv.bib"</i> or
572 <i>"<opencv_contrib>/modules/<module>/doc/<module>.bib"</i> file:
575 author = {Bradski, Gary R},
576 title = {Computer vision face tracking for use in a perceptual user interface},
578 publisher = {Citeseer}
582 @note Try not to add publication duplicates because it can confuse documentation readers and writers later.
584 Then make reference with _cite_ command:
589 @note To get BibTeX record for the publications one can use [Google Scholar]. Once the publication
590 have been found - follow its "Cite" link and then choose "BibTeX" option:
591 ![](scholarship_cite_dialog.png)
593 Step-by-step {#tutorial_documentation_steps}
596 Steps described in this section can be used as checklist during documentation writing. It is not
597 necessary to do things in the same order, but some steps really depend on previous. And of course
598 these steps are just basic guidelines, there is always a place for creativity.
600 Document the function {#tutorial_documentation_steps_fun}
601 ---------------------
603 1. Add empty doxygen comment preceding function definition.
604 2. Add _brief_ command with short description of function meaning at the beginning.
605 3. Add detailed description of the function.
606 4. _Optional_: insert formulas, images and blocks of example code to illustrate complex cases
607 5. _Optional_: describe each parameter using the _param_ command.
608 6. _Optional_: describe return value of the function using the _returns_ command.
609 7. _Optional_: add "See also" section with links to similar functions or classes
610 8. _Optional_: add bibliographic reference if any.
611 9. Test your code. (Python: "make check_pylint")
612 10. Generate doxygen documentation and verify results.
614 Write the tutorial {#tutorial_documentation_steps_tutorial}
617 1. Formulate the idea to be illustrated in the tutorial.
619 2. Make the example application, simple enough to be understood by a beginning developer. Be
620 laconic and write descriptive comments, don't try to avoid every possible runtime error or to make
621 universal utility. Your goal is to illustrate the idea. And it should fit one source file!
623 If you want to insert code blocks from this file into your tutorial, mark them with special doxygen comments (see [here](@ref tutorial_documentation_commands_include)).
625 If you want to write the tutorial in more than one programming language, use the toggle buttons for alternative comments and code (see [here](@ref tutorial_documentation_toggle_buttons_commands_include)).
627 3. Collect results of the application work. It can be "before/after" images or some numbers
628 representing performance or even a video.
630 Save it in appropriate format for later use in the tutorial:
631 - To save simple graph-like images use lossless ".png" format.
632 - For photo-like images - lossy ".jpg" format.
633 - Numbers will be inserted as plain text, possibly formatted as table.
634 - Video should be uploaded on YouTube.
636 4. Create new tutorial page (<em>".markdown"</em>-file) in corresponding location (see
637 [here](@ref tutorial_documentation_quick_start_1)), and place all image files near it (or in "images"
638 subdirectory). Also put your example application file and make sure it is compiled together with the
639 OpenCV library when `-DBUILD_EXAMPLES=ON` option is enabled on cmake step.
641 5. Modify your new page:
642 - Add page title and identifier, usually prefixed with <em>"tutorial_"</em> (see [here](@ref tutorial_documentation_md_page)).
643 You can add a link to the previous and next tutorial using the identifier
645 @prev_tutorial{identifier}
646 @next_tutorial{identifier}
648 @warning Do **not** write the **hashtag (#)**, example: \n Incorrect: @verbatim @prev_tutorial{#tutorial_documentation} @endverbatim Correct: @verbatim @prev_tutorial{tutorial_documentation} @endverbatim
649 - Add brief description of your idea and tutorial goals.
650 - Describe your program and/or its interesting pieces.
651 - Describe your results, insert previously added images or other results.
653 To add a youtube video, e.g. www.youtube.com/watch?v= **ViPN810E0SU**, use _youtube_{**Video ID**}:
655 @youtube{ViPN810E0SU}
658 - Add bibliographic references if any (see [here](@ref tutorial_documentation_commands_cite)).
660 6. Add newly created tutorial to the corresponding table of contents. Just find
661 <em>"table_of_content_*.markdown"</em> file with the needed table and place new record in it
662 similar to existing ones.
664 - @subpage tutorial_windows_visual_studio_image_watch
666 _Languages:_ C++, Java, Python
668 _Compatibility:_ \>= OpenCV 2.4
670 _Author:_ Wolf Kienzle
672 You will learn how to visualize OpenCV matrices and images within Visual Studio 2012.
674 As you can see it is just a list item with special _subpage_ command which marks your page as a
675 child and places it into the existing pages hierarchy. Add compatibility information,
676 authors list and short description. Also note the list item indent, empty lines between
677 paragraphs and special _italic_ markers.
679 7. Generate doxygen documentation and verify results.
681 References {#tutorial_documentation_refs}
683 - [Doxygen] - main Doxygen page
684 - [Documenting basics] - how to include documentation in code
685 - [Markdown support] - supported syntax and extensions
686 - [Formulas support] - how to include formulas
687 - [Supported formula commands] - HTML formulas use MathJax script for rendering
688 - [Command reference] - supported commands and their parameters
690 <!-- invisible references list -->
691 [Doxygen]: http://www.doxygen.nl
692 [Doxygen download]: http://doxygen.nl/download.html
693 [Doxygen installation]: http://doxygen.nl/manual/install.html
694 [Documenting basics]: http://www.doxygen.nl/manual/docblocks.html
695 [Markdown support]: http://www.doxygen.nl/manual/markdown.html
696 [Formulas support]: http://www.doxygen.nl/manual/formulas.html
697 [Supported formula commands]: http://docs.mathjax.org/en/latest/input/tex/macros/index.html
698 [Command reference]: http://www.doxygen.nl/manual/commands.html
699 [Google Scholar]: http://scholar.google.ru/