1Writing documentation for OpenCV {#tutorial_documentation} 2================================ 3 4@tableofcontents 5 6Doxygen overview {#tutorial_documentation_overview} 7================ 8 9Intro {#tutorial_documentation_intro} 10----- 11 12[Doxygen] is documentation generation system with a lot of great features, such as: 13- parse program sources to produce actual and accurate documentation 14- check documentation for errors 15- insert images and formulas 16- use markdown syntax and plain HTML for precise text formatting 17- generate documentation in many different formats 18 19OpenCV library existing documentation has been converted to doxygen format. 20 21Installation {#tutorial_documentation_install} 22------------ 23 24Please, check official [download][Doxygen download] and [installation][Doxygen installation] pages. 25Some linux distributions can also provide doxygen packages. 26 27Generate documentation {#tutorial_documentation_generate} 28---------------------- 29 30- Get the OpenCV sources (version 3.0 and later) 31- _Optional:_ get the OpenCV_contrib sources 32- Create build directory near the sources folder(s) and go into it 33- Run cmake (assuming you put sources to _opencv_ folder): 34 @code{.sh} 35 cmake ../opencv 36 @endcode 37 Or if you get contrib sources too: 38 @code{.sh} 39 cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ../opencv 40 @endcode 41- Run make: 42 @code{.sh} 43 make doxygen 44 @endcode 45- Open <i>doc/doxygen/html/index.html</i> file in your favorite browser 46 47Quick start {#tutorial_documentation_quick_start} 48=========== 49 50@note These instructions are specific to OpenCV library documentation, other projects can use 51different layout scheme and documenting agreements. 52 53Documentation locations {#tutorial_documentation_quick_start_1} 54----------------------- 55 56Whole documentation is gathered from many different places: 57 58- __source code__ entities, like classes, functions or enumerations, should be documented in 59 corresponding header files, right prior entity definition. See examples in next sections. 60 61- __pages__ are good place to put big pieces of text with images and code examples not directly 62 connected with any source code entity. Pages should be located in separate files and 63 contained in several predefined places. This tutorial is example of such page. 64 65- __images__ can be used to illustrate described things. Usually located at the same places as pages, 66 images can be inserted to any place of the documentation. 67 68- __code examples__ show how to use the library in real applications. Each sample is 69 self-contained file which represents one simple application. Parts of these files can be 70 included into documentation and tutorials to demonstrate function calls and objects collaboration. 71 72- __BibTeX references__ are used to create one common bibliography. All science books, articles and 73 proceedings served as basis for library functionality should be put in this reference list. 74 75Following scheme represents common documentation places for _opencv_ repository: 76~~~ 77<opencv> 78├── doc - doxygen config files, root page (root.markdown.in), BibTeX file (opencv.bib) 79│ ├── tutorials - tutorials hierarchy (pages and images) 80│ └── py_tutorials - python tutorials hierarchy (pages and images) 81├── modules 82│ └── <modulename> 83│ ├── doc - documentation pages and images for module 84│ └── include - code documentation in header files 85└── samples - place for all code examples 86 ├── cpp 87 │ └── tutorial_code - place for tutorial code examples 88 └── ... 89~~~ 90 91@note Automatic code parser looks for all header files (<i>".h, .hpp"</i> except for <i>".inl.hpp; 92.impl.hpp; _detail.hpp"</i>) in _include_ folder and its subfolders. Some module-specific 93instructions (group definitions) and documentation should be put into 94<i>"include/opencv2/<module-name>.hpp"</i> file. 95 96@note You can put C++ template implementation and specialization to separate files 97(<i>".impl.hpp"</i>) ignored by doxygen. 98 99@note Files in _src_ subfolder are not parsed, because documentation is intended mostly for the 100library users, not developers. But it still is possible to generate full documentation by 101customizing processed files list in cmake script (<i>doc/CMakeLists.txt</i>) and doxygen options in 102its configuration file (<i>doc/Doxyfile.in</i>). 103 104Since version 3.0 all new modules are placed into _opencv_contrib_ repository, it has slightly 105different layout: 106~~~ 107<opencv_contrib> 108└── modules 109 └── <modulename> 110 ├── doc - documentation pages and images, BibTeX file (<modulename>.bib) 111 ├── include - code documentation in header files 112 ├── samples - place for code examples for documentation and tutorials 113 └── tutorials - tutorial pages and images 114~~~ 115 116Example {#tutorial_documentation_quick_start_2} 117------- 118 119To add documentation for functions, classes and other entities, just insert special comment prior 120its definition. Like this: 121 122@verbatim 123/** @brief Calculates the exponent of every array element. 124 125The function exp calculates the exponent of every element of the input array: 126\f[ \texttt{dst} [I] = e^{ src(I) } \f] 127 128The maximum relative error is about 7e-6 for single-precision input and less than 1e-10 for 129double-precision input. Currently, the function converts denormalized values to zeros on output. 130Special values (NaN, Inf) are not handled. 131 132@param src input array. 133@param dst output array of the same size and type as src. 134 135@sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude 136*/ 137CV_EXPORTS_W void exp(InputArray src, OutputArray dst); 138@endverbatim 139 140Here you can see: 141 142- special C-comment syntax denotes it is doxygen comment 143 @verbatim /** ... */ @endverbatim 144 145- command `brief` denotes following paragraph is a brief description 146 @verbatim @brief @endverbatim 147 148- empty line denotes paragraph end 149 150- TeX formula between `f[` and `f]` commands 151 @verbatim \f[ ... \f] @endverbatim 152 153- command `param` denotes following word is name of the parameter and following text is 154 description of the parameter; all parameters are placed in a list 155 @verbatim @param @endverbatim 156 157- command `sa` starts "See also" paragraph containing references to some classes, methods, pages or URLs. 158 @verbatim @sa @endverbatim 159 160Produced reference item looks like this: 161![Reference link](doxygen-2.png) 162 163The "More..." link brings you to the function documentation: 164![Function documentation](doxygen-1.png) 165 166 167Another example {#tutorial_documentation_quick_start_3} 168--------------- 169 170Different comment syntax can be used for one-line short comments: 171 172@verbatim 173//! type of line 174enum LineTypes { 175 FILLED = -1, 176 LINE_4 = 4, //!< 4-connected line 177 LINE_8 = 8, //!< 8-connected line 178 LINE_AA = 16 //!< antialiased line 179}; 180@endverbatim 181 182Here: 183 184- special C++-comment syntax denotes it is doxygen comment 185 @verbatim //! @endverbatim 186 187- additional symbol `<` denotes this comment is located _after_ documented entity 188 @verbatim //!< @endverbatim 189 190Produced documentation block looks like this: 191![Enumeration documentation](doxygen-3.png) 192 193More details {#tutorial_documentation_quick_start_4} 194------------ 195 196### Command prefix 197 198Doxygen commands starts with `@` or `\` sign: 199@verbatim 200@brief ... 201or 202\brief ... 203@endverbatim 204 205### Comment syntax 206 207Doxygen comment can have different forms: 208@verbatim 209C-style: 210/** ... */ 211or 212/*! ... */ 213 214C++-style 215//! ... 216or 217/// ... 218 219Lines can start with '*': 220/** 221 * ... 222 * ... 223 */ 224 225Can be placed after documented entity: 226//!< ... 227/**< ... */ 228@endverbatim 229 230### Paragraph end 231 232To end paragraph, insert empty line or any command starting new paragraph: 233@verbatim 234@brief brief description paragraph 235brief continues 236 237new paragraph 238 239@note new note paragraph 240note paragraph continues 241 242another paragraph 243paragraph continues 244@endverbatim 245 246### Naming 247 248Pages, anchors, groups and other named entities should have unique name inside the whole project. 249It is a good idea to prefix such identifiers with module name: 250@verbatim 251@page core_explanation_1 Usage explanation 252@defgroup imgproc_transform Image transformations 253@anchor mymodule_interesting_note 254@endverbatim 255 256Supported Markdown {#tutorial_documentation_quick_start_md} 257------------------ 258 259Doxygen supports Markdown formatting with some extensions. Short syntax reference is described 260below, for details visit [Markdown support]. 261 262### lists {#tutorial_documentation_md_list} 263 264@verbatim 265Bulleted: 266- item1 267- item2 268Numbered: 2691. item1 2702. item2 271or 272-# item1 273-# item2 274@endverbatim 275 276### emphasis {#tutorial_documentation_md_emph} 277 278@verbatim 279_italic_ 280__bold__ 281use html in complex cases: 282<em>"path/to/file"</em> 283@endverbatim 284 285### links {#tutorial_documentation_md_links} 286 287@verbatim 288explicit link: 289[OpenCV main site](http://opencv.org) 290automatic links: 291<http://opencv.org> 292or even: 293http://opencv.org 294@endverbatim 295 296### images {#tutorial_documentation_md_image} 297 298@verbatim 299![image caption](image path) 300@endverbatim 301 302### headers {#tutorial_documentation_md_head} 303 304@verbatim 305Level1 306====== 307Level2 308------ 309### Level3 310#### Level4 311@endverbatim 312 313### header id {#tutorial_documentation_md_headid} 314 315You can assign a unique identifier to any header to reference it from other places. 316@verbatim 317Header {#some_unique_identifier} 318------ 319... 320See @ref some_unique_identifier for details 321@endverbatim 322 323### page id {#tutorial_documentation_md_page} 324 325Each page should have additional Level1 header at the beginning with page title and identifier: 326@verbatim 327Writing documentation for OpenCV {#tutorial_documentation} 328================================ 329@endverbatim 330 331### tables {#tutorial_documentation_md_table} 332 333Example from doxygen documentation: 334@verbatim 335First Header | Second Header 336------------- | ------------- 337Content Cell | Content Cell 338Content Cell | Content Cell 339@endverbatim 340 341Commonly used commands {#tutorial_documentation_quick_start_5} 342---------------------- 343 344Most often used doxygen commands are described here with short examples. For the full list of 345available commands and detailed description, please visit [Command reference]. 346 347### Basic commands {#tutorial_documentation_commands_basic} 348 349- __brief__ - paragraph with brief entity description 350 351- __param__ - description of function argument. 352 353 Multiple adjacent statements are merged into one list. If argument with this name is not found 354 in actual function signature - doxygen warning will be produced. Function can have either _no_ 355 documented parameters, either _all_ should be documented. 356 357- __sa__ - "See also" paragraph, contains references to classes, functions, pages or URLs 358 359- __note__ - visually highlighted "Note" paragraph. Multiple adjacent statements are merged into 360 one block. 361 362- __return, returns__ - describes returned value of a function 363 364- __overload__ - adds fixed text to the function description: <em>"This is an overloaded member 365 function, provided for convenience. It differs from the above function only in what argument(s) 366 it accepts."</em> 367 368- __anchor__ - places invisible named anchor, which can be referenced by `ref` command. It can be 369 used in pages only. 370 371- __ref__ - explicit reference to a named section, page or anchor. 372 373 If such entity can not be found - doxygen warning will be generated. This command has an 374 optional argument - link text. 375 376 Doxygen also generates some links automatically: if text contains word which can be found in 377 documented entities - reference will be generated. This functionality can be disabled by prefixing 378 the word with `%` symbol. 379 @verbatim 380Explicit reference: @ref MyClass 381Explicit named reference: @ref example_page "Example page" 382Implicit reference: cv::abc::MyClass1 or just MyClass1 383Disable implicit reference: %MyClass1 384 @endverbatim 385 386- __f__ - formula 387 388 Inline formulas are bounded with `f$` command: 389 @verbatim 390\f$ ... \f$ 391 @endverbatim 392 393 Block formulas - with `f[` and `f]` commands: 394 @verbatim 395\f[ ... \f] 396 @endverbatim 397 398### Code inclusion commands {#tutorial_documentation_commands_include} 399 400To mark some text as a code in documentation, _code_ and _endcode_ commands are used. 401@verbatim 402@code 403float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101), 404 borderInterpolate(-5, img.cols, cv::BORDER_WRAP)); 405@endcode 406@endverbatim 407 408Syntax will be highlighted according to the currently parsed file type (C++ for <em>.hpp</em>, C for <em>.h</em>) or 409you can manually specify it in curly braces: 410 411@verbatim 412@code{.xml} 413@endverbatim 414 415To include whole example file into documentation, _include_ and _includelineno_ commands are used. 416The file is searched in common samples locations, so you can specify just its name or short part of 417the path. The _includelineno_ version also shows line numbers but prevents copy-pasting since 418the line numbers are included. 419 420@verbatim 421@include samples/cpp/test.cpp 422@endverbatim 423 424If you want to include some parts of existing example file - use _snippet_ command. 425 426First, mark the needed parts of the file with special doxygen comments: 427@verbatim 428//! [var_init] 429int a = 0; 430//! [var_init] 431@endverbatim 432 433Then include this snippet into documentation: 434@verbatim 435@snippet samples/cpp/test.cpp var_init 436@endverbatim 437 438@note Currently most of such partial inclusions are made with _dontinclude_ command for 439compatibility with the old rST documentation. But newly created samples should be included with the 440_snippet_ command, since this method is less affected by the changes in processed file. 441 442### Grouping commands {#tutorial_documentation_commands_group} 443 444All code entities should be put into named groups representing OpenCV modules and their internal 445structure, thus each module should be associated with a group with the same name. Good place to 446define groups and subgroups is the main header file for this module: 447<em>"<module>/include/opencv2/<module>.hpp"</em>. 448 449@note Doxygen groups are called "modules" and are shown on "Modules" page. 450 451@verbatim 452/** 453@defgroup mymodule My great module 454 optional description 455@{ 456 @defgroup mymodule_basic Basic operations 457 optional description 458 @defgroup mymodule_experimental Experimental operations 459 optional description 460@} 461*/ 462@endverbatim 463 464To put classes and functions into specific group, just add `ingroup` command to its documentation, 465or wrap the whole code block with `addtogroup` command: 466 467@verbatim 468/** @brief Example function 469 @ingroup mymodule 470*/ 471or 472/** 473@addtogroup mymodule_experimental 474@{ 475*/ 476... several functions, classes or enumerations here 477/** 478@} 479*/ 480@endverbatim 481 482### Publication reference {#tutorial_documentation_commands_cite} 483 484Use _cite_ command to insert reference to related publications listed in @ref citelist page. 485 486First, add publication BibTeX record into <i>"<opencv>/doc/opencv.bib"</i> or 487<i>"<opencv_contrib>/modules/<module>/doc/<module>.bib"</i> file: 488@verbatim 489@ARTICLE{Bradski98, 490 author = {Bradski, Gary R}, 491 title = {Computer vision face tracking for use in a perceptual user interface}, 492 year = {1998}, 493 publisher = {Citeseer} 494} 495@endverbatim 496 497@note Try not to add publication duplicates because it can confuse documentation readers and writers later. 498 499Then make reference with _cite_ command: 500@verbatim 501@cite Bradski98 502@endverbatim 503 504@note To get BibTeX record for the publications one can use [Google Scholar]. Once the publication 505have been found - follow its "Cite" link and then choose "BibTeX" option: 506![](scholarship_cite_dialog.png) 507 508Step-by-step {#tutorial_documentation_steps} 509============ 510 511Steps described in this section can be used as checklist during documentation writing. It is not 512necessary to do things in the same order, but some steps really depend on previous. And of course 513these steps are just basic guidelines, there is always a place for creativity. 514 515Document the function {#tutorial_documentation_steps_fun} 516--------------------- 517 5181. Add empty doxygen comment preceding function definition. 5192. Add _brief_ command with short description of function meaning at the beginning. 5203. Add detailed description of the function. 5214. _Optional_: insert formulas, images and blocks of example code to illustrate complex cases 5225. _Optional_: describe each parameter using the _param_ command. 5236. _Optional_: describe return value of the function using the _returns_ command. 5247. _Optional_: add "See also" section with links to similar functions or classes 5258. _Optional_: add bibliographic reference if any. 5269. Generate doxygen documentation and verify results. 527 528Write the tutorial {#tutorial_documentation_steps_tutorial} 529------------------ 530 5311. Formulate the idea to be illustrated in the tutorial. 532 5332. Make the example application, simple enough to be understood by a beginning developer. Be 534 laconic and write descriptive comments, don't try to avoid every possible runtime error or to make 535 universal utility. Your goal is to illustrate the idea. And it should fit one source file! 536 537 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)). 538 5393. Collect results of the application work. It can be "before/after" images or some numbers 540 representing performance or even a video. 541 542 Save it in appropriate format for later use in the tutorial: 543 - To save simple graph-like images use lossless ".png" format. 544 - For photo-like images - lossy ".jpg" format. 545 - Numbers will be inserted as plain text, possibly formatted as table. 546 - Video should be uploaded on YouTube. 547 5484. Create new tutorial page (<em>".markdown"</em>-file) in corresponding location (see 549 [here](@ref tutorial_documentation_quick_start_1)), and place all image files near it (or in "images" 550 subdirectory). Also put your example application file and make sure it is compiled together with the 551 OpenCV library when `-DBUILD_EXAMPLES=ON` option is enabled on cmake step. 552 5535. Modify your new page: 554 - Add page title and identifier, usually prefixed with <em>"tutorial_"</em> (see [here](@ref tutorial_documentation_md_page)). 555 - Add brief description of your idea and tutorial goals. 556 - Describe your program and/or its interesting pieces. 557 - Describe your results, insert previously added images or other results. 558 559 To add a video use _htmlonly_, _endhtmlonly_ commands with raw html block inside: 560 @verbatim 561@htmlonly 562<div align="center"> 563<iframe 564 title="my title" width="560" height="349" 565 src="http://www.youtube.com/embed/ViPN810E0SU?rel=0&loop=1" 566 frameborder="0" allowfullscreen align="middle"> 567</iframe> 568</div> 569@endhtmlonly 570 @endverbatim 571 - Add bibliographic references if any (see [here](@ref tutorial_documentation_commands_cite)). 572 5736. Add newly created tutorial to the corresponding table of contents. Just find 574 <em>"table_of_content_*.markdown"</em> file with the needed table and place new record in it 575 similar to existing ones. 576 @verbatim 577- @subpage tutorial_windows_visual_studio_image_watch 578 579 _Compatibility:_ \>= OpenCV 2.4 580 581 _Author:_ Wolf Kienzle 582 583 You will learn how to visualize OpenCV matrices and images within Visual Studio 2012. 584 @endverbatim 585 As you can see it is just a list item with special _subpage_ command which marks your page as a 586 child and places it into the existing pages hierarchy. Add compatibility information, 587 authors list and short description. Also note the list item indent, empty lines between 588 paragraphs and special _italic_ markers. 589 5907. Generate doxygen documentation and verify results. 591 592References {#tutorial_documentation_refs} 593========== 594- [Doxygen] - main Doxygen page 595- [Documenting basics] - how to include documentation in code 596- [Markdown support] - supported syntax and extensions 597- [Formulas support] - how to include formulas 598- [Supported formula commands] - HTML formulas use MathJax script for rendering 599- [Command reference] - supported commands and their parameters 600 601<!-- invisible references list --> 602[Doxygen]: http://www.stack.nl/~dimitri/doxygen/index.html) 603[Doxygen download]: http://www.stack.nl/~dimitri/doxygen/download.html 604[Doxygen installation]: http://www.stack.nl/~dimitri/doxygen/manual/install.html 605[Documenting basics]: http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html 606[Markdown support]: http://www.stack.nl/~dimitri/doxygen/manual/markdown.html 607[Formulas support]: http://www.stack.nl/~dimitri/doxygen/manual/formulas.html 608[Supported formula commands]: http://docs.mathjax.org/en/latest/tex.html#supported-latex-commands 609[Command reference]: http://www.stack.nl/~dimitri/doxygen/manual/commands.html 610[Google Scholar]: http://scholar.google.ru/ 611