DOxygen for C++使用说明——Markdown支持
自Doxygen 版本1.8.0，Markdown被引進。
接下來，我們將先簡單介紹標準的Markdown語法，讀者可以進入Markdown官網查詢更詳細的細節。然后討論一下Doxygen支持的Markdown擴展，最后討論一下Doxygen對Markdown標準的實現細節。
Standard Markdown
Paragraphs
實際上甚至在Doxygen支持Markdown之前，它處理段落的方式與Markdown如出一轍：為了生成一個段落，只需在兩個連續的行間加至少一個空行即可。
例如：
Headers
就像Markdown一樣，doxygen支持兩種形式的標題。Level 1或者2標題可以通過一下形式生成：
This is a level 1 header ========================This is a level 2 header ------------------------每個標題后緊跟著包含‘=’與’-‘的一行。‘=’或者’-‘的數量是不重要的，只要他們至少兩個即可。
你也可以在一行的開始使用’#’。‘#’的數量決定了標題的層次（最終支持6層).你可以通過任意數量(包含0）的’#’結束標題。
例如：
# This is a level 1 header### This is level 3 header #######Block quotes
我們可以通過在一行的開始鍵入1個或者多個’>’創建塊引用。
如下：
列表和代碼可以出現在塊引用中。塊引用也支持嵌套使用。
注意：Doxygen要求我們在最后一個’>’后空一格才能開始寫其他的字符。
例如：
第二行并不能被視作一個 block quote.
Lists
一些簡單的列表可以以-,+,*開頭。
- Item 1More text for this item.- Item 2+ nested list item.+ another nested item. - Item 3效果為：
Item 1
More text for this item.
Item 2
- nested list item.
- another nested item.
- Item 3
也有數字列表，如下：
1. First item. 2. Second item.Code Blocks
在兩個正常的段落中插入一段代碼，只需要將每行代碼開頭，留至少4個空格
This a normal paragraphThis is a code blockWe continue with a normal paragraph again.Doxygen將移出對代碼塊的強制識別。注意：我們也不能在段落中間開始代碼塊，即代碼塊與上一句之間必須空一行。
Horizontal Rulers
可以通過至少3個*,-, _產生水平參考線。
例如：
- - - *** ______效果為：
Emphasis
斜體，使用一個*或者_.
黑體，使用兩個*或者_.
例如：
效果:
single asterisks
single underscores
double asterisks
double underscores
code spans
為了揭示代碼的范圍，你需要使用(`)括起來。不像代碼塊，code spans可以出現在一個段落里。例如：
Use the `printf()` function.Links
Doxygen支持兩種形式的鏈接：inline and reference.
兩種形式的鏈接都以[鏈接文本]開始。
Inline Links
對于 inline link，文本后直接跟著一個URL。
例如：
另外，doxygen也提供了一個相似的方式去鏈接一個已經注釋過的實體。
[The link text](@ref MyClass)Reference Links
不同于Inline Links直接將URL放在內部，你也可以將定義一個link與將其指向一個文本分開。
例如：
以上”Optional title”也可以改為：
(Optional title)
‘Optional title’
一旦定義好, 鏈接看起來如下:
[link text][link name]如果link text 和 link name 是相同的, 也可以
[link name][]or even
[link name]注意:link name 匹配是不區分大小寫的。
例如:
Link definitions（即” “里的內容）將不會出現在結果中。
也支持內部鏈接，如下：
[myclass]: @ref MyClass "My class"Images
Markdown 關于images 的語法類似于links. 唯一的區別是在link text前加了一個!
例如：
  ![Caption text][img def] ![img def][img def]: /path/to/img.jpg "Optional Title"并且你也可以使用@ref to link to an image:
 ![img def][img def]: @ref image.png "Caption text"The caption text is optional.
Automatic Linking
為了支持URL or e-mail address的鏈接， Markdown 支持如下語法:
<http://www.example.com> <https://www.example.com> <ftp://www.example.com> <mailto:address@example.com> <address@example.com>注意 : doxygen在沒有尖括號時，也可以產生Links.
Markdown Extensions
Table of Contents
Doxygen可以使用 [TOC] 來添加章節目錄。
注意： [TOC] 等價于 \tableofcontents .
Tables
直接看例子：
First Header | Second Header ------------- | ------------- Content Cell | Content Cell Content Cell | Content Cell效果：
列對齊可以控制通過在分割線兩頭添加一個或兩個冒號。
例如：
效果：
Fenced Code Blocks
一個帶圍欄的code block不要求能識別代碼。它可以通過一對”fence lines”定義。一行中至少3個(~).開頭和結尾有相同數量的波浪線。
如下：
默認輸出和 normal code block相同。
對于Doxygen支持的語言，我們也可以通過標明后綴名來實現語法高亮。例如：對于python
~~~~~~~~~~~~~{.py} # A class class Dummy: pass ~~~~~~~~~~~~~效果：
對于C，有：
效果:
也可以通過至少3個引號(`)來表明代碼塊。
Header Id Attributes
標準的Markdown不支持標記標題，但是當你想要鏈接一個章節時，便會出現錯誤。
PHP Markdown額外支持標記標題，如下：
Header 1 {#labelid} ========## Header 2 ## {#labelid2}為了鏈接章節，只需要:
[Link text](#labelid)你也可以使用@ref
[Link text](@ref labelid)注意;以上僅支持Level1 to 4.
Doxygen specifics
Including Markdown files as pages
如果標題的標簽為index or mainpage， doxygen 將會把它放在首頁 (index.html).
Here is an example of a file README.md that will appear as the main page when processed by doxygen:
My Main Page {#mainpage} ============如果a page有一個標簽，你可以使用@ref來鏈接它。
當然了，如果不使用標簽來鏈接a markdown page，你也可以直接使用文件名，如下：
效果:
See the other page for more info.
總結
以上是生活随笔為你收集整理的DOxygen for C++使用说明——Markdown支持的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 【离散数学中的数据结构与算法】七 排列与
- 下一篇： Firefly III 搭建个人财务记账