為OpenCV編寫文檔

Doxygen概述

介紹

Doxygen是具有很多功能的文檔生成系統(tǒng)，如：

• 解析程序源，以產(chǎn)生實際和準確的文檔
• 檢查文檔是否有錯誤
• 插入圖像和公式
• 使用markdown語法和純HTML進行精確的文本格式化
• 生成許多??不同格式的文檔

OpenCV庫的現(xiàn)有文檔已經(jīng)轉換為doxygen格式。

安裝

請查看官方下載和安裝頁面。一些linux發(fā)行版也可以提供doxygen軟件包。

生成文檔

• 獲取OpenCV源（版本3.0及更高版本）
• 可選：獲取OpenCV_contrib源
• 在源文件夾附近創(chuàng)建構建目錄并進入它
• 運行cmake（假設你把源放到opencv文件夾）：

  cmake ../opencv

  或者如果你也得到contrib來源：

  cmake -DOPENCV_EXTRA_MODULES_PATH = .. / opencv_contrib / modules ../opencv

• 運行make：使doxygen
• 在您最喜歡的瀏覽器中打開doc / doxygen / html / index.html文件
• 測試你的Python代碼：

make check_pylint

快速開始

注意

這些說明特定于OpenCV庫文檔，其他項目可以使用不同的布局方案和文檔協(xié)議。

文檔位置

從許多不同的地方收集整個文件：

• 源代碼實體，如類，函數(shù)或枚舉，應在相應的頭文件中記錄，正確的實體定義。請參見下一節(jié)中的示例。
• 頁面是放置大片文字的好地方，圖像和代碼示例不直接與任何源代碼實體連接。頁面應位于單獨的文件中，并包含在幾個預定義的位置。本教程是此類頁面的示例。
• 圖像可以用來說明描述的東西。通常位于與頁面相同的位置，圖像可以插入文檔的任何位置。
• 代碼示例顯示了如何在實際應用中使用庫。每個樣本都是自包含的文件，代表一個簡單的應用程序。這些文件的一部分可以包含在文檔和教程中，以演示函數(shù)調(diào)用和對象協(xié)作。
• BibTeX引用用于創(chuàng)建一個常用的參考書目。作為圖書館功能的基礎的所有科學書籍，文章和訴訟應作為參考清單。

以下方案代表了opencv存儲庫的常見文檔：

<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
    └── ...

注意

自動代碼解析器在include文件夾及其子文件夾中查找所有頭文件（“.h，.hpp”，“.inl.hpp; .impl.hpp; _detail.hpp”除外）。一些模塊特定的指令（組定義）和文檔應該放在“include / opencv2 / <module-name> .hpp”文件中。

您可以將C ++模板實現(xiàn)和專業(yè)化放在doxygen忽略的文件（“.impl.hpp”）中。

在文件的src子文件夾不被解析，因為文檔主要是供圖書館用戶，而不是開發(fā)商。但是仍然可以通過自定義cmake腳本（doc / CMakeLists.txt）中的處理文件列表和其配置文件（doc / Doxyfile.in）中的doxygen選項來生成完整的文檔。

自3.0版以來，所有新模塊都放在opencv_contrib倉庫中，布局略有不同：

<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

要為函數(shù)，類和其他實體添加文檔，只需在其定義之前插入特殊注釋。喜歡這個：

/** @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);

在這里你可以看到：

• 特殊的C-comment語法表示它是doxygen注釋
  

/ ** ... * / 

• 命令brief表示以下段落是簡要說明
  

@brief 

• 空行表示段落結束
• TeX公式f[與f]命令之間

  \ f [... \ f] 

• 命令param表示以下單詞是參數(shù)的名稱，下面的文本是參數(shù)的描述; 所有參數(shù)都放在列表中

  @param 

• 命令sa啟動“另請參見”段落，其中包含對某些類，方法，頁面或URL的引用。

  @sa 

生成的參考項目如下所示：

“更多...”鏈接將帶您進入功能文檔：

功能文檔

另一個例子

不同的注釋語法可用于單行簡短注釋：

//! type of line
enum LineTypes {
    FILLED  = -1,
    LINE_4  = 4, //!< 4-connected line
    LINE_8  = 8, //!< 8-connected line
    LINE_AA = 16 //!< antialiased line
};

這里：

• 特殊的C ++ - 注釋語法表示它是doxygen注釋

  //！

• 其他符號<表示此評論位于后記錄實體

  // <！

生成的文檔塊如下所示：

Enumeration documentation

更多細節(jié)

命令前綴

Doxygen命令以@或\符號開始：

@brief ...
or
\brief ...

評論語法

Doxygen評論可以有不同的形式：

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

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

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

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

段落結束

要結束段落，請插入空行或任何命令開始新段落：

@brief brief description paragraph
brief continues

new paragraph

@note new note paragraph
note paragraph continues

another paragraph
paragraph continues

命名

頁面，錨點，組和其他命名實體在整個項目中應該有唯一的名稱。將此標識符與模塊名稱進行前綴是一個好主意：

@page core_explanation_1 Usage explanation
@defgroup imgproc_transform Image transformations
@anchor mymodule_interesting_note

支持Markdown

Doxygen支持使用一些擴展名的Markdown格式。下面介紹簡短的語法參考，詳細信息請訪問Markdown支持。

名單

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)

headers

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

標題ID

您可以為任何標題分配唯一的標識符，以便從其他地方引用它。

Header {#some_unique_identifier}
------
...
See @ref some_unique_identifier for details

頁面ID

每個頁面應該在頁面標題和標識符的開頭有額外的Level1標題：

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

表

來自doxygen文檔的示例：

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

常用的命令

最常用的doxygen命令在這里用簡短的例子進行描述。有關可用命令和詳細描述的完整列表，請訪問命令參考。

基本命令

• 簡短的段落，簡要的實體描述
• 參數(shù) - 函數(shù)參數(shù)的描述。多個相鄰語句合并成一個列表。如果在實際功能簽名中找不到帶有該名稱的參數(shù)，則會產(chǎn)生doxygen警告。功能可以沒有文件參數(shù)，都應該記錄。
• sa - “另請參見”段落，包含對類，函數(shù)，頁面或URL的引用
• 注意 - 視覺突出顯示“注”段。多個相鄰語句合并成一個塊。
• return，returns - 描述函數(shù)的返回值
• 過載 - 將固定文本添加到函數(shù)描述中：“為了方便起見，這是一個重載的成員函數(shù)，它與上述函數(shù)的區(qū)別僅在于它接受的參數(shù)。
• 錨 - 不可見的命名錨，可以通過ref命令引用。它只能在頁面中使用。
• 引用 - 引用指定的部分，頁面或錨點。如果無法找到此類實體 - 將會生成doxygen警告。此命令具有可選參數(shù) - 鏈接文本。Doxygen還自動生成一些鏈接：如果文本包含可以在文檔實體中找到的單詞 - 將會生成引用。可以通過使用%符號對該字進行前綴來禁用此功能。

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 - 公式
  

內(nèi)聯(lián)公式有f$命令：

\f$ ... \f$

塊公式 - 與f[和f]命令：

\f[ ... \f]

代碼包含命令

要將文本標記為文檔中的代碼，使用代碼和結尾碼命令。

@code
float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
                          borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
@endcode

語法將根據(jù)當前解析的文件類型（C ++為.hpp，C為.h）突出顯示，也可以手動指定大括號：

@code{.xml}

要將整個示例文件包含在文檔中，請使用include和includelineno命令。該文件在通用樣本位置進行搜索，因此您可以僅指定其名稱或路徑的一小部分。該includelineno版本也顯示行數(shù)，但阻止的復制粘貼，因為行號都包括在內(nèi)。

@include samples / cpp / test.cpp

如果要包含現(xiàn)有示例文件的一些部分 - 請使用snippet命令。

首先，使用特殊的doxygen注釋標記文件的必需部分：

//！[var_init]
int a = 0;
//！[var_init]

然后將此片段包含在文檔中：

@snippet samples / cpp / test.cpp var_init

注意

目前大多數(shù)這種部分包含是通過dontinclude命令來與舊的rST文檔兼容的。但是，新創(chuàng)建的示例應包含在snippet命令中，因為此方法受處理文件中更改的影響較小。

切換按鈕包含命令

切換按鈕用于顯示所選配置（例如編程語言，操作系統(tǒng)，IDE）。

要使用文檔中的按鈕，使用add_toggle和end_toggle命令。

命令add_toggle可以

• 一般：add_toggle {按鈕名}
• 對于C ++：add_toggle_cpp
• 對于Java：add_toggle_java
• 對于Python：add_toggle_python

例：

@add_toggle{Button Name}

  text / code / doxygen commands

@end_toggle

例如使用帶有文字和代碼段的切換按鈕：

### 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

結果如下所示：

按鈕示例

C ++

C ++文本按鈕

std :: cout << “Hello World！” ;

Java

文本為Java按鈕

        System.out.println（“Hello World！”）;

Python

Python的文本按鈕

print('Hello world!')

您可以看到，按鈕將在上一個標題下自動添加。

分組命令

所有代碼實體都應該被放入代表OpenCV模塊的命名組及其內(nèi)部結構中，因此每個模塊都應該與一個具有相同名稱的組相關聯(lián)。定義組和子組的好地方是此模塊的主要頭文件：“<module> / include / opencv2 / <module> .hpp”。

注意

Doxygen組稱為“模塊”，并顯示在“模塊”頁面上。

/**
@defgroup mymodule My great module
    optional description
@{
    @defgroup mymodule_basic Basic operations
        optional description
    @defgroup mymodule_experimental Experimental operations
        optional description
@}
*/

要將類和函數(shù)放入特定的組中，只需ingroup在其文檔中添加命令，或者使用addtogroup命令包裝整個代碼塊：

/** @brief Example function
    @ingroup mymodule
*/
or
/**
@addtogroup mymodule_experimental
@{
*/
... several functions, classes or enumerations here
/**
@}
*/

出版參考

使用cite命令插入“ 參考書目”頁面中列出的相關出版物的引用。

首先，將出版物BibTeX記錄添加到“<opencv> /doc/opencv.bib”或“<opencv_contrib> / modules / <module> / doc / <module> .bib”文件中：

@ARTICLE{Bradski98,
    author = {Bradski, Gary R},
    title = {Computer vision face tracking for use in a perceptual user interface},
    year = {1998},
    publisher = {Citeseer}
}

注意

嘗試不添加發(fā)布重復，因為它可能會混淆文檔閱讀器和作者。

然后參考cite命令：

@cite Bradski98

注意

要獲得出版物的BibTeX記錄，可以使用Google學術搜索。一旦找到出版物 - 按照“引用”鏈接，然后選擇“BibTeX”選項：

Step-by-step

本文中描述的步驟可在文檔編寫過程中用作檢查表。沒有必要按照同樣的順序做事情，但有些步驟真的取決于以前的事情。當然，這些步驟只是基本的指導方針，總是有創(chuàng)意的地方。

記錄功能

1. 在函數(shù)定義之前添加空doxygen注釋。
2. 在開始時添加簡短的功能意義簡短的命令。
3. 添加功能的詳細說明。
4. 可選：插入示例代碼的公式，圖像和塊，以說明復雜的情況
5. 可選：使用param命令描述每個參數(shù)。
6. 可選：使用returns命令描述函數(shù)的返回值。
7. 可選：添加“參見”部分，其中包含類似功能或類的鏈接
8. 可選：添加書目參考文獻。
9. 測試你的代碼 （Python：“make check_pylint”）
10. 生成doxygen文檔并驗證結果。

寫教程

1. 制定教程中說明的想法。
2. 使示例應用程序，簡單到足以被開發(fā)人員理解。做一個簡明扼要的并且寫描述性的注釋，不要試圖避免每一個可能的運行時錯誤或使通用效用。你的目標是說明這個想法。它應該適合一個源文件！如果要將此文件中的代碼塊插入到教程中，請使用特殊的doxygen注釋來標記它們（請參閱此處）。如果要用多種編程語言編寫教程，請使用切換按鈕進行備用注釋和代碼（參見此處）。
3. 收集應用工作的結果。它可以是“之前/之后”圖像或一些表示性能的數(shù)字，甚至視頻。保存適當?shù)母袷焦┮院笤诮坛讨惺褂茫簽榱吮４婧唵蔚膱D形圖像，使用無損“.png”格式。照片般的圖像 - lossy“.jpg”格式。數(shù)字將作為純文本插入，可能格式化為表格。視頻應該在YouTube上上傳。
4. 在相應位置創(chuàng)建新的教程頁面（“.markdown” -file）（請參閱此處），并將所有圖像文件放在其附近（或“images”子目錄中）。還要放置您的示例應用程序文件，并確保-DBUILD_EXAMPLES=ON在cmake步驟上啟用選項時與OpenCV庫一起編譯。
5. 修改您的新頁面：

@prev_tutorial{identifier}
@next_tutorial{identifier}

警告

不要不寫主題標簽（＃） ，例如：
不正確的：

@prev_tutorial {} #tutorial_documentation 

      正確：

@prev_tutorial {} tutorial_documentation 

• 添加簡要描述您的想法和教程目標。
• 描述你的節(jié)目和/或其有趣的作品。
• 描述您的結果，插入以前添加的圖像或其他結果。要添加YouTube視頻，例如www.youtube.com/watch?v= ViPN810E0SU，請使用youtube { Video ID }：

@youtube {} ViPN810E0SU

添加書目參考文獻（參見這里）。

    6. 將新創(chuàng)建的教程添加到相應的目錄中。只需找到“table_of_content _ *。markdown”文件，并附上所需的表格，并將其中的新記錄與現(xiàn)有記錄類似。

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

正如你可以看到的，它只是一個列表項，其中有一個特殊的subpage命令，它將你的頁面標記為一個小孩，并把它放到現(xiàn)有的頁面層次結構中。添加兼容性信息，作者列表和簡短描述。還要注意列表項縮進，段落之間的空行和特殊的斜體標記。

     7. 生成doxygen文檔并驗證結果。

參考

• Doxygen - 主要Doxygen頁面
• 記錄基礎知識 - 如何在代碼中包含文檔
• Markdown支持 - 支持的語法和擴展
• 公式支持 - 如何包含公式
• 支持的公式命令 - HTML公式使用MathJax腳本進行渲染
• 命令參考 - 支持的命令及其參數(shù)