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