 |
OpenCV 4.12.0
開源計算機視覺
|
載入中...
搜尋中...
無匹配項
|
OpenCV 4.12.0
開源計算機視覺
|
| 原始作者 | 馬克西姆·沙布寧 |
| 相容性 | OpenCV >= 3.0 |
Doxygen 是一個文件生成系統，具有許多強大的功能，例如
OpenCV 庫的現有文件已轉換為 Doxygen 格式。
請查閱官方下載和安裝頁面。一些 Linux 發行版也可能提供 Doxygen 軟體包。
整個文件從許多不同的地方收集：
以下方案表示 opencv 倉庫的常見文件位置：
自 3.0 版本起，所有新模組都放置在 opencv_contrib 倉庫中，其佈局略有不同：
要為函式、類和其他實體新增文件，只需在其定義之前插入特殊註釋，如下所示：
/** @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);
您可以看到：
/** ... */
brief 表示接下來的段落是簡要描述@brief
f[ 和 f] 命令之間的 TeX 公式\f[ ... \f]
param 表示接下來的詞是引數名稱，其後的文字是引數描述；所有引數都放在一個列表中@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
};
在這裡
//!
< 表示此註釋位於被文件化實體之後//!<
生成的文件塊如下所示： 
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
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](https://opencv.tw) automatic links: <https://opencv.tw> or even: https://opencv.tw
Level1 ====== Level2 ------ ### Level3 #### Level4
您可以為任何標題分配一個唯一識別符號，以便從其他地方引用它。
Header {#some_unique_identifier}
------
...
See @ref some_unique_identifier for details
每個頁面開頭都應有一個額外的 Level1 標題，包含頁面標題和識別符號
Writing documentation for OpenCV {#tutorial_documentation}
================================
Doxygen 文件中的示例
First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell
這裡描述了最常用的 Doxygen 命令，並附有簡短示例。有關可用命令的完整列表和詳細描述，請訪問 命令參考。
param - 函式引數的描述。
多個相鄰語句合併為一個列表。如果在實際函式簽名中未找到具有此名稱的引數，Doxygen 將生成警告。函式可以 沒有 文件化的引數，也可以 所有 引數都應被文件化。
ref 命令引用。它只能在頁面中使用。ref - 對命名部分、頁面或錨點的顯式引用。
如果找不到此類實體，Doxygen 將生成警告。此命令有一個可選引數 - 連結文字。
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 - 公式
內聯公式由 f$ 命令限定
\f$ ... \f$
塊級公式由 f[ 和 f] 命令限定
\f[ ... \f]
要在文件中將某些文字標記為程式碼，使用 code 和 endcode 命令。
@code
float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
@endcode
語法將根據當前解析的檔案型別（.hpp 為 C++，.h 為 C）進行高亮顯示，或者您可以在大括號中手動指定它
@code{.xml}
要將整個示例檔案包含到文件中，使用 include 和 includelineno 命令。檔案會在常見的示例位置中搜索，因此您只需指定其名稱或路徑的簡短部分。includelineno 版本還會顯示行號，但由於包含行號，因此會阻止複製貼上。
@include samples/cpp/test.cpp
如果要包含現有示例檔案的某些部分，請使用 snippet 命令。
首先，使用特殊的 Doxygen 註釋標記檔案中的所需部分
//! [var_init] int a = 0; //! [var_init]
然後將此片段包含到文件中
@snippet samples/cpp/test.cpp var_init
切換按鈕用於顯示選定的配置（例如，程式語言、作業系統、IDE）。
要在文件中使用這些按鈕，需要使用 add_toggle 和 end_toggle 命令。
add_toggle 命令可以是：
示例
@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
結果如下所示：
如您所見，按鈕會自動新增到上一個標題下方。
所有程式碼實體都應放入代表 OpenCV 模組及其內部結構的命名組中，因此每個模組都應與一個同名組相關聯。定義組和子組的好地方是該模組的主標頭檔案："<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
@}
*/
要將類和函式放入特定組中，只需在其文件中新增 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}
}
然後使用 cite 命令進行引用
@cite Bradski98
本節中描述的步驟可在編寫文件時用作檢查清單。並非所有步驟都必須按相同順序進行，但有些步驟確實依賴於之前的步驟。當然，這些步驟只是基本指南，總有發揮創造力的空間。
編寫示例應用程式，應足夠簡單以便初級開發人員理解。言簡意賅，編寫描述性註釋，不要試圖避免所有可能的執行時錯誤或製作通用工具。您的目標是闡明想法。而且它應該適合一個原始檔！
如果您想將此檔案中的程式碼塊插入到教程中，請使用特殊的 Doxygen 註釋標記它們（參見此處）。
如果您想用多種程式語言編寫教程，請使用切換按鈕來實現替代註釋和程式碼（參見此處）。
收集應用程式執行結果。可以是“前後”對比圖片、表示效能的數字，甚至是影片。
以適當的格式儲存，以便稍後在教程中使用：
-DBUILD_EXAMPLES=ON 選項時，它能與 OpenCV 庫一起編譯。@prev_tutorial{identifier}
@next_tutorial{identifier} @prev_tutorial{#tutorial_documentation} 正確@prev_tutorial{tutorial_documentation} 描述您的結果，插入之前新增的圖片或其他結果。
要新增 YouTube 影片，例如 www.youtube.com/watch?v= ViPN810E0SU，請使用 youtube{影片 ID}
@youtube{ViPN810E0SU}將新建立的教程新增到相應的目錄中。只需找到包含所需表格的 "table_of_content_*.markdown" 檔案，並以與現有記錄類似的方式在其中新增新記錄。
它只是一個列表項，帶有特殊的 subpage 命令，該命令將您的頁面標記為子頁面並將其放入現有頁面層次結構中。另請注意列表項縮排、段落之間的空行和特殊的 斜體 標記。
1.12.0 為 OpenCV 生成。