前言
本篇文章主要講解如何使用不同的工具來生成HTML注釋文檔 , 對于注釋的使用和說明你可以在注釋使用這篇文章得到了解.
概述
下面我會為大家講解如何使用 HeaderDoc 和 Doxygen 還有 Appledoc 工具生成HTML注釋文檔.
準(zhǔn)備
為了方便我們演示不同工具的使用 , 下面我為即將被生成的文檔創(chuàng)建一個(gè)目錄 , 并進(jìn)行分類 , 每個(gè)工具生成的文檔會放在各自對應(yīng)的文件夾中.
使用
HeaderDoc
HeaderDoc 是一個(gè)命令行工具 , 允許你從代碼中自動生成格式良好的HTML 文檔 . 當(dāng)然 , 注釋必須是用指定的格式提供的.
注釋的格式在注釋使用這篇文章中已經(jīng)做了較為詳細(xì)的講解 , 這里不再敘述 , 如果你需要完整的說明 請參見HeaderDoc 用戶指南.
其實(shí)使用HeaderDoc生成文檔的方式有很多種 , 這里我選擇為大家講解使用終端如何操作.
第一步 打開終端窗口:
第二步 輸入命令進(jìn)入工程根目錄 :
cd 你的工程根目錄路徑
第三步 使用headerdoc2html命令生成HTML文檔:
headerdoc2html的命令格式如下:
headerdoc2html -o OutputDirectory InputDirectory
其中OutputDirectory目錄是我們先前創(chuàng)建的目錄 , 而InputDirectory目錄是工程文件存在的目錄.
注意: 在-o后面有一個(gè)空格符號谭网。
我這里寫好后的命令是這樣的(這是我的路徑):
headerdoc2html -o /Users/LEE/Desktop/DocDemo/HeaderDoc /Users/LEE/Desktop/QQMusicPlayerDemo/QQMusicPlayerDemo
當(dāng)你點(diǎn)擊回車鍵后 , 窗口中會巴拉巴拉的顯示一堆命令 最后當(dāng)你看到...done后就代表執(zhí)行完畢了.
打開我們之前創(chuàng)建好的目錄 , 里面出現(xiàn)了一大堆文件夾 , 每個(gè)文件里對應(yīng)著我們工程中的每個(gè) .h 和 .m 文件 , 文件夾內(nèi)是這個(gè)文件的注釋文檔HTML文件.
現(xiàn)在都是零零散散的 , 不方便我們查看 , 最后一步 我們要生成一個(gè)匯總頁面 (類似目錄) , 來幫助我們訪問整個(gè)文檔的內(nèi)容.
命令格式如下:
gatherheaderdoc 文檔目錄
我這里寫好后的命令是這樣的(這是我的路徑):
gatherheaderdoc /Users/LEE/Desktop/DocDemo/HeaderDoc
完成后你大概會看到這樣的信息:
好了 現(xiàn)在我們應(yīng)該發(fā)現(xiàn)文檔目錄中多了一個(gè)名為 masterTOC.html 的文件:
(這些文件夾的名稱和你工程中.h .m的文件相關(guān))
這個(gè)就是我們最后一步生成的匯總頁 , 打開后可以看到我在注釋使用文章中做演示時(shí)所添加注釋的文件和方法.
我點(diǎn)擊進(jìn)入一個(gè) 看一看 , 怎么樣 ? 是不是非秤优酷!
現(xiàn)在 , 你已經(jīng)看到了結(jié)果了 , 隨便瀏覽文檔中的任何部分然后看看所有東西都是怎樣展現(xiàn)的 . HeaderDoc的用處遠(yuǎn)遠(yuǎn)不止這些 , 但是這卻是在大多數(shù)情況下你需要的東西 , 這里不再一一介紹了 , 更多的細(xì)節(jié)留給你去慢慢發(fā)掘.
Doxygen
Doxygen 是一個(gè)第三方應(yīng)用想要使用它之前必須下載 . 對所有的操作系統(tǒng)它都要對應(yīng)版本 , 所以當(dāng)你并不是只為iOS開發(fā)時(shí)也都可以使用 .
在查看它的細(xì)節(jié)之前 , 我想說Doxygen并不是一開始就是為了在Objective-C中生成注釋文檔而設(shè)計(jì)的 . 但是 , 它卻在針對 C 和 C++ 語言時(shí)可以完美的完成工作 , 你將會親眼目睹 , 它其實(shí)支持很多的語言 . 除開這些 , 它還包含非常多的注釋標(biāo)簽 , 如果你決定了使用 Doxygen 工具來生成注釋文檔 , 那么你可以使用任何標(biāo)簽來擁有更棒的兼容性.
- 鏈接 這里你可以找到關(guān)于代碼注釋的所有資源.
- 鏈接 這里你可以找到Doxygen支持的所有標(biāo)簽，點(diǎn)擊每一個(gè)標(biāo)簽將會得到它的用途描述信息.
- 最后揍魂，你可以訪問 鏈接 來下載應(yīng)用.
在下載前 , 讓我提醒你可以在 Doxygen 的網(wǎng)站上找到比我先前在注釋使用文章中提到的內(nèi)容多得多的東西 . 實(shí)際上 , 正如下面的截圖所示 , 在左側(cè)有一個(gè)菜單面板 , 你可以使用它來找到的 Doxygen 各個(gè)部分的內(nèi)容和數(shù)不盡的細(xì)節(jié)以及how-tos.
現(xiàn)在 , 訪問我剛才在上面給你的鏈接地址 , 然后滑到頁面的下方直到找到一個(gè)名叫A binary distribution for Mac OS X 10.5 and later 的區(qū)域 . 點(diǎn)擊 ftp或http鏈接來初始化包下載過程 . 依據(jù)你的網(wǎng)絡(luò)速度 , 下載過程可能會需要幾秒鐘來完成 , 文件大小大概為55Mb.
下載完成后 , 打開包 . 然后找到Doxygen應(yīng)用然后把它拖到你的Applications目錄下.
如果你不想把它添加到Applications目錄下也沒問題 , 可以把它拖到任何你想放的位置 . Doxygen 是一個(gè)完全self-contained的應(yīng)用 , 無論你把它放在哪里 , 移除它只需要?jiǎng)h除它的APP文件.
假設(shè)現(xiàn)在你已經(jīng)把它復(fù)制到了目錄下 , 點(diǎn)擊Lauchpad來輕松找到它 . 點(diǎn)擊它運(yùn)行.
注意: 如果得到一個(gè)提示信息說一個(gè)應(yīng)用程序不能被打開是因?yàn)樗鼇碜詻]有被認(rèn)證的開發(fā)者，按照下面的步驟來跳過它 : 在Finder里 , 打開Applications目錄 . 定位到Doxygen應(yīng)用 , 然后按下Ctrl鍵+點(diǎn)擊它 . 在菜單中選擇 Open 選項(xiàng) , 然后在新的視圖框中點(diǎn)擊Open 按鈕.
如果以前用過Doxygen，你肯定知道應(yīng)該怎么做。但是映之，這里我假設(shè)你是第一次使用這個(gè)應(yīng)用，所以讓我向你展示一些最重要的步驟.
下面是Doxygen第一次運(yùn)行時(shí)的初始窗口：
在我告訴你正確的需要使用的設(shè)置信息前 , 有必要說明Doxygen提供兩個(gè)使用模式 : Wizard模式由一個(gè)簡單且通用的方法組成 , 以及Expert模式 , 在這里很多的配置信息都可以被指定這樣你可以定制化每一個(gè)輸出文檔的細(xì)節(jié)部分.
我不會把重點(diǎn)放在Expert模式上 , 因?yàn)橐獞?yīng)用的配置條件高度依賴于每位開發(fā)者的個(gè)人需求 . 意味著我們將專注于 Wizard 模式 , 但是在此之前 , 我想還是有必要快速了解一下Expert模式 . 在主視圖區(qū)域里點(diǎn)擊 Expert按鈕 , 馬上就會在主面板上看到給了你很多的配置信息 . 你可以上下滑動查看所有的配置 , 但是遠(yuǎn)不止于此 . 在左邊 , 有一個(gè)小面板標(biāo)題為Topics , 點(diǎn)擊其他的topic就可以獲取它自己的配置 . 如果有時(shí)間 , 瀏覽它們所有 . 你將會找到想在你的應(yīng)用當(dāng)中使用的有用的選項(xiàng).
現(xiàn)在 , 我們把焦點(diǎn)放在Wizard模式 . 確保點(diǎn)擊到了正確的按鈕 , 這樣就可以跟上我將要描述的內(nèi)容 . 首先 , 在視圖頂部我們必須指定 Doxygen 從哪里運(yùn)行 . 點(diǎn)擊Select按鈕 , 然后在電腦里選擇Application目錄 , 或者任何其他你把Doxygen應(yīng)用拷貝進(jìn)去的那個(gè)目錄.
接下來 , 我們來指定工程名字 . 在Project Name輸入框里 , 輸入 DocDemo in Objective-C值 (或者任何你想用的值) . 如果你愿意 , 也可以把下面的輸入框值都填上 . 在那之下 , 我們必須指定指向工程的路徑 . 再一次 , 使用Select按鈕且定位到工程的根目錄中 . 選中 Scan recursively 會很不錯(cuò) , 因?yàn)镈oxygen就也可以掃描所有子目錄了.
最后 , 指定存儲生成的文檔的地方 . 如果你還記得的話 , 我們已經(jīng)為此在桌面的 DocDemo 目錄下新建了子目錄Doxygen . 因此 , 點(diǎn)擊 Destination Directory 旁邊的 Select 按鈕 , 然后選中它.
接下來 , 在左邊的 Topics 列表里 , 選擇Mode選項(xiàng) . 在新的配置里 , 選中All Entities 選項(xiàng):
接下來 , 還是在 Topics 列表里 , 選擇 Output 選項(xiàng) . 在這里你可以找到很多的導(dǎo)出選項(xiàng) . 自由選擇任何你想要的output種類 . 在這個(gè)例子里 , 我屏蔽了 LaTeX選項(xiàng) , 只讓HTML有效.
最后 , 在Diagrams選項(xiàng)里你可以保留默認(rèn)設(shè)置.
現(xiàn)在是時(shí)候輸出文檔了 . 請確認(rèn)在繼續(xù)之前一定要把先前的配置信息全部設(shè)置好 . 設(shè)置好了 ? 很好蜡坊，我們繼續(xù)吧 . 點(diǎn)擊Run按鈕 (在Wizard和Expert 按鈕旁邊) ，然后現(xiàn)在在主視圖區(qū)域你可以看到一個(gè)名叫Run doxygen的新按鈕 . 點(diǎn)擊它讓應(yīng)用幫你啟動創(chuàng)建HTML文件 . 在白色區(qū)域你將會看到一些output信息 , 如果事情出差錯(cuò)了 , 你也會在這里看到.
不管怎樣 , 只要它完成了 , 打開Finder然后定位到輸出目錄去查看導(dǎo)出文件 . 你會看到有一系列的文件被創(chuàng)建了 , 而你需要找到的就是 index.html 文件 . 雙擊在瀏覽器中打開它 . 其實(shí)如果你不是那么在意非要看到導(dǎo)出的文件 , 可以簡單在Doxygen視圖里點(diǎn)擊Show HTML output.
這是在打開index頁面時(shí)看到的第一個(gè)屏幕:
它只是包含了我們先前設(shè)置的工程名 , 創(chuàng)建時(shí)間 , 和在頂部的許多鏈接 . 使用這些鏈接去瀏覽一下相應(yīng)內(nèi)容 . 例如 , 如果點(diǎn)擊Classes鏈接 , 你就會得到一個(gè)包含了工程中的所有classes的列表 . 有趣的部分是在每個(gè)class旁邊都展示了它的簡短描述信息 (僅僅是那些我們寫了的).
下面是當(dāng)你點(diǎn)擊 LaunchViewController class時(shí)會看到的內(nèi)容：
可以看到 , 工程中的方法和一個(gè)公有屬性的詳細(xì)文檔可以在這里找到 . 另外一個(gè)有趣的地方是在Files菜單下面 , 在這里所有的被分析的文件都被列舉出來赎败，選中LaunchViewController.h文件 . 在哪里你可以找到文件的描述信息 , 以及我們聲明的所有東西: calss , protocol , 和struct.
使用More…鏈接來查看上面的所有內(nèi)容的詳細(xì)信息 . 還有一個(gè)鏈接名字為 "Go to the source code of this file." 如果點(diǎn)擊它 , 將會展現(xiàn)LaunchViewController.h頭文件里的代碼 . 注意不管在頭文件里的任何public的內(nèi)容 , 都可以在這里展示出來 . 但是不要指望可以看到任何實(shí)現(xiàn)代碼 , 那些是“專屬于你”的 .
好了 , 此刻我相信你已經(jīng)對所有以上內(nèi)容有了大概理解 . 定位到輸出的HTML頁面 , 回到Xcode中修改注釋文檔信息 , 然后重新導(dǎo)出所有內(nèi)容 . 還有 , 不要猶豫去設(shè)置高級配置信息然后查看將會發(fā)生什么 . 大體上 , 盡量多的體驗(yàn)更多內(nèi)容 , 然后更加熟悉Doxygen . 無論是小工程還是大工程 , 它都是一個(gè)很棒的工具.
Appledoc
appledoc 是一個(gè)可以幫你生成Objective-C代碼注釋的輔助工具 , appledoc所生成的注釋API文檔與蘋果類庫的API文檔保持一致 . 這可以讓Xcode能夠識別出我們自己的API文檔.
廢話不多說 , 直接進(jìn)入正題 , 首先我們要下載安裝appledoc , 它在GitHub上 , 接下來我們通過終端來下載安裝它.
下載 (大概40多MB)
git clone git://github.com/tomaz/appledoc.git
進(jìn)入appledoc目錄
cd ./appledoc
安裝 (可能會需要你輸入密碼)
sudo sh install-appledoc.sh
稍等片刻就安裝完成了 , 接下來我們驗(yàn)證一下是否安裝成功 , 命令如下:
appledoc --version
我當(dāng)前的版本是2.2.1 (以你實(shí)際的為準(zhǔn)) .
下載安裝好后 , 我們來講一下如何使用appledoc.
第一步 , 在終端中進(jìn)入工程根目錄:
cd 你的工程根目錄路徑
第二步 , 執(zhí)行appledoc的命令 格式如下:
appledoc --project-name QQMusicPlayerDemo --project-company LEE ./
- QQMusicPlayerDemo:項(xiàng)目名稱
- lee：公司名稱
根據(jù)你的實(shí)際情況去替換
還可以設(shè)置詳細(xì)一些:
appledoc --project-name QQMusicPlayerDemo --project-company LEE --company-id com.lee --output /Users/LEE/Desktop/QQMusicPlayerDemo /Users/LEE/Desktop/QQMusicPlayerDemo/QQMusicPlayerDemo
以上命令中分別需要提供5個(gè)參數(shù),分別是:
1:工程名稱
2:公司名稱
3:工程ID
4:生成結(jié)果輸出路徑
5:掃描哪個(gè)路徑下的類.
注意: 以上命令不要有換行 , 其中掃描路徑最好使用工程根目錄下的工程名那個(gè)路徑 , 不要直接使用工程根目錄 如果集成了 CocoaPods 那么生成時(shí)基本上都會報(bào)錯(cuò)
提示過了再錯(cuò)
"( *?ω?)?╰ひ╯ 那么我們又可以聊聊人生了
執(zhí)行之后你會看到工程的根目錄下會多出一個(gè)文件 , 該命令會根據(jù)指定的路徑將所有的的類遍歷一次 , 當(dāng)生成成功以后 , appledoc會新建一個(gè)文本文件來記錄生成情況 , 這個(gè)文件存放在上面命令中指定的--output路徑下(我命令里寫的是工程根目錄):
如果你還想了解更多appledoc的命令 可以執(zhí)行:
appledoc --help
生成的文檔會自動存放在Xcode默認(rèn)的文檔目錄里:
~/Library/Developer/Shared/Documentation/DocSets
第三步 , 集成到工程中
其實(shí)只要在終端執(zhí)行上面的一句命令 就可以完成文檔的生成 , 如果你想每次編譯工程時(shí)自動去生成相應(yīng)的文檔 那么這一步就可以幫到你.
在你的工程中創(chuàng)建新的 Target , 注意這里要選擇 Other 中的 Aggregate , 如圖所示:
在我們新創(chuàng)建的 Target 中的 Buid Phases 中添加 Run Script:
打開Run Script , Shell 下面的文檔區(qū)域添加這樣的模板:
#appledoc Xcode script
# Start constants
company="LEE";
companyID="com.lee";
companyURL="http://lee.com";
target="iphoneos";
#target="macosx";
outputPath="~/help";
# End constants
/usr/local/bin/appledoc \
--project-name "${PROJECT_NAME}" \
--project-company "${company}" \
--company-id "${companyID}" \
--docset-atom-filename "${company}.lee" \
--docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \
--docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \
--docset-fallback-url "${companyURL}/${company}" \
--output "${outputPath}" \
--publish-docset \
--docset-platform-family "${target}" \
--logformat xcode \
--keep-intermediate-files \
--no-repeat-first-par \
--no-warn-invalid-crossref \
--exit-threshold 2 \
"${PROJECT_DIR}"/"${PROJECT_NAME}"
Xcode 左上角選擇這個(gè) Target , 然后 Build 編譯.
這是我們的文檔文件就生成好了 , 打開之前在根目錄生成的 docset-installed.txt 文件
選中其中的路徑 然后前往該路徑.
這個(gè)就是我們生成的文檔
這里介紹2種查看方式 :
- 使用Xcode文檔接口查看工具
* 頂部工具欄中選擇 __Window -> Documentation and API Reference__ 或者使用快捷鍵 __Shift + command + 0__
* 左側(cè)找到我們的文檔 點(diǎn)擊它就可以查看了.
- 使用瀏覽器查看HTML頁面
* 找到文檔文件 -> 右鍵 顯示包內(nèi)容
* 按照這個(gè)路徑找到index.html (Documents文件夾就是整個(gè)HTML文檔的目錄)
怎么樣 ? 是不是瞬間感覺人生完整了. 有了appledoc 我們可以輕松生成出和蘋果官方一樣的文檔來.
語法
注釋塊中秕衙，每一行開頭的空格和"*"字符多數(shù)情況都會被appledoc忽略。
連續(xù)的兩行(即沒有間隔空行)的注釋僵刮，將被合并成一個(gè)段落据忘，并忽略換行，就像html搞糕。
- 注釋類型
/// 這是單行注釋勇吊。
/** 這也是單行注釋 */
/*! 同樣是單行注釋 */
/** 這也是單行注釋，
* 第二行會接上第一行窍仰。
*/
在注釋塊內(nèi)汉规，appledoc支持如下語法：Markdown、HTML驹吮、HeaderDoc Tags.
Markdown的語法在這里有介紹(中文翻譯) , 用Github和簡書的童鞋應(yīng)該很熟悉 . OSX上可以用Mou實(shí)時(shí)查看效果 , Chrome也有一個(gè)插件來實(shí)時(shí)查看效果 . 這個(gè)東西可以說一看就會 , 學(xué)習(xí)成本很低 . Markdown有很多方言 , 而且appledoc支持的也不算完整 . 所以用的時(shí)候可以試著在appledoc編譯一下看看效果 .
HTML這個(gè)就不用說了 , 支持Markdown肯定也支持HTML .. 如果想要把控住更多細(xì)節(jié) , 那就直接碼HTML吧.
HeaderDoc Tags這個(gè)東西是蘋果的HeaderDoc工具的語法针史。詳情可以見官網(wǎng)文檔。例如@param碟狞、@return啄枕、@warning這樣的東西，appledoc會進(jìn)行解釋族沃。當(dāng)然appledoc對這個(gè)東西的支持也不算完整 :?: 所以用的時(shí)候也要嘗試一下频祝。
- 用法示例
/** 第一行是類的簡介
在簡介的下面,就是類的詳細(xì)介紹了泌参。
沒有間隔換行會被消除，就像HTML那樣常空。
下面是常用的markdown語法
- - -
無序列表: (每行以 '*'沽一、'-'、'+' 開頭):
* this is the first line
* this is the second line
* this is the third line
有序列表: (每行以 1.2.3窟绷、a.b.c 開頭):
a. this is the first line
b. this is the secode line
多級列表:
* this is the first line
a. this is line a
b. this is line b
* this is the second line
1. this in line 1
2. this is line 2
標(biāo)題:
# This is an H1
## This is an H2
### This is an H3
#### This is an h4
##### This is an h5
###### This is an H6
鏈接:
普通URL直接寫上锯玛，appledoc會自動翻譯成鏈接: http://www.reibang.com/users/a6da0db100c8
[這個(gè)](http://www.reibang.com/users/a6da0db100c8) 鏈接會隱藏實(shí)際URL.
表格:
| header1 | header2 | header3 |
|---------|:-------:|--------:|
| normal | center | right |
| cell | cell | cell |
引用:
這里會引用到方法 `someMethod:`，這里會引用到類 `CustomColor`
這里會引用到一個(gè)代碼塊
void CMYK2RGB(float c, float m, float y, float k,
float *r, float *g, float *b) {
*r = (1 - c) * (1 - k);
*g = (1 - m) * (1 - k);
*b = (1 - y) * (1 - k);
}
@since iOS5.0
*/
@interface AppledocExample : NSObject
///這里是屬性的說明
@property (nonatomic, strong) NSString *name;
/**
@brief 這里是方法的簡介兼蜈。該Tag不能放到類注釋里攘残。
@exception UIColorException 這里是方法拋出異常的說明
@see someMethod:
@warning 這里是警告，會顯示成藍(lán)色的框框
@bug 這里是bug为狸，會顯示成黃色的框框
@param red 這里是參數(shù)說明1
@param green 這里是參數(shù)說明2
@param blue 這里是參數(shù)說明3
@return 這里是返回值說明
*/
- (UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue;
- (void)someMethod:(NSString *)str;
@end
編譯出的效果是這樣:
總結(jié)
上面所介紹的這三種工具都是非常不錯(cuò)的 , 你可以根據(jù)自己的喜歡去選擇 , 不過我個(gè)人還是比較推薦Appledoc的 , 它默認(rèn)生成的文檔風(fēng)格和蘋果的官方文檔是一致的 , 而doxygen需要另外配置 . appledoc就是用objective-c生成的 , 必要的時(shí)候調(diào)試和改動也比較方便 . 可以生成docset , 并且集成到xcode中 . 這一點(diǎn)是很贊的 , 相當(dāng)于在源碼中按住option再單擊就可以調(diào)出相應(yīng)方法的幫助 . 相對于headerdoc , 它沒有特殊的注釋要求 , 可以用/** / 的格式 , 也可以兼容/! */的格式的注釋 . 綜合來看 所以我比較推薦Appledoc .
我是LEE , 如果你還有更好的建議 歡迎給我留言 , 如果喜歡記得點(diǎn)贊喲 ! 么了個(gè)噠~
注: 本文中Doxygen部分參考自AppCoda.
