IOS項目自動生成技術文檔很方便實用

Xcode工具自己不具有這樣的功能，可是咱們經過一些插件和工具來達到這個目的。

生成註釋

生成文檔以前，咱們須要給代碼中的方法或者變量寫上註釋，而後再利用工具根據這些規範的註釋自動生成文檔。因此呢，註釋必定要規範統一，可是每次都要手動輸入規範化的註釋，着實也麻煩，這裏須要藉助Xcode的開源插件VVDocumenter，規範註釋生成器，很是方便！

多行註釋直接輸入三個斜線 "///" 會自動格式化，如上圖所示

單行註釋須要輸入三個斜線+空格 「/// 註釋」。輸入兩個「//」固然能夠正確的被xcode識別爲註釋，可是在下面生成文檔的時候不能被識別爲文檔註釋。

而後再配合 appledoc 、doxygen 或者 headdoc，就能夠生成技術文檔。

對於Objective-C來講，目前比較好用的是appledoc 和 doxygen。

工具對比

headerdoc
xcode 自帶的文檔生成工具、基於命令行的操做、使用方便。可是隻能生成以 /*! */ 的格式的註釋。還有一個缺點是每一個類文件對應一個註釋文件，沒有最後彙總導航的index文件。

docxygen
功能強大、三者中支持語言最多的、無headerdoc缺點、基於圖形化的操做界面，可是配置較多，能夠生成html文檔或pdf文檔。

appledoc
基於命令行的操做、使用方便、無headerdoc缺點、默認生成的文檔風格和蘋果的官方文檔是一致的，即docset，集成到xcode中就跟蘋果的官方文檔如出一轍，在源碼中按住option再單擊就能夠調出相應方法的幫助。固然也能夠生成html文檔。

工具使用

appledoc

從github下載源碼，在終端裏面cd源碼文件夾，而後執行shell腳本安裝

[plain] view plain copy 

1. git clone git://github.com/tomaz/appledoc.git  

2. cd appledoc  

3. sudo sh install-appledoc.sh  

安裝過程當中若是出錯，檢查一下Xcode所在的路徑中是否存在空格，去掉再試之。

成功後在終端cd到項目文件夾裏面，輸入如下命令生成文檔：

[plain] view plain copy 

1. appledoc --output ../doc --project-name weibo --project-company "wxhl" --company-id "com.wxhl.weibo" .  

--output ../doc  設置文檔輸出目錄爲上級目錄下面的doc
--project-name weibo  設置項目名爲「weibo」
--project-company "wxhl"  設置公司名爲「wxhl」
--company-id "com.wxhl.weibo"  設置公司id爲「com.wxhl.weibo」
.  當前目錄

當該命令完成後，能夠看到在上級目錄的doc文件夾裏面有一個docset-installed.txt的文件，這裏面描述了docset文檔所在的真正路徑，通常都是在～/Library/Developer/Shared/Documentation/DocSets/ 裏面，或者看看xcode中的Organizer - Documentation，會發現其中新增了幫助文檔。

生成HTML

對於最新版本的appledoc來講，它默認時是生成docset文檔並集成到xcode。當須要html文檔時，能夠加上「--no-create-docset」

[plain] view plain copy 

1. appledoc --no-create-docset --output ../doc --project-name weibo --project-company "wxhl" --company-id "com.wxhl.weibo" .  

當該命令完成後，能夠看到在上級目錄的doc文件夾裏面就 不是docset-installed.txt文件了，而是所有的html文檔，直接打開index就行。

doxygen

doxygen支持源碼編譯安裝與dmg安裝。去doxygen官網下載最新的dmg，doxygen有圖形界面，可經過Launchpad打開。

在step 1中選擇好項目的路徑。
step 2默認是Wizard->Project頁面，在其中
1) 在「Project name」中填寫項目名。
2) 勾選「Sacn recursively」，掃描全部的子文件夾。
3) 在「Destination directory」中填寫好文檔的輸出目錄。這裏我填的是「docs」。

點擊中間的「Expert」切換Expert->Project頁面，在其中
1) 將「OUTPUT_LANGUAGE」設爲「Chinese」，使用簡體中文。
2) 勾選「JAVADOC_AUTOBRIEF」，自動將註釋的第1段識別爲簡要描述。

點擊中間的「Run」切換Run頁面，而後點擊「Run doxygen」按鈕生成文檔。

當文檔生成完畢後，使用瀏覽器打開docs/html/index.html——

生成PDF

doxygen默認會爲生成pdf作好準備。切換到Wizard->Project，會發現它自動勾選了「LaTex」與「as intermediate format for hyperlinked PDF」。

doxygen自己並不能直接輸出pdf文件，而是生成了latex目錄，其中有一個 makefile 文件。若系統中裝好了pdflatex，可在latex目錄中運行「make」命令來生成pdf文件。
怎樣才能裝好pdflatex呢？mac平臺可安裝MacTeX。打開 http://www.tug.org/mactex/ ，下載  MacTeX.pkg (約2.1GB)。MacTeX.pkg下載好後，可雙擊運行，根據嚮導來安裝。

環境裝好以後，當在latex目錄中運行「make」命令來生成pdf文件時，你會發現——純英文文檔能順利生成pdf；而含有中文時，不能順利生成pdf文件。

對於latex排版，doxygen其實已經作了不少準備，好比——源文件是UTF-8編碼，並默認使用了utf8 package。理論上是支持多國語言的。
可對於中文來講，還須要加載 CJKutf8 package，並配置好CJK環境。這才能順利的使用中文。

用文本編輯器打開docxygen生成的latex目錄中的refman.tex。找到「\begin{document}」這一行，將其修改成

\usepackage{CJKutf8} 
\begin{document}
\begin{CJK}{UTF8}{gbsn}

而後再找到「\end{document}」這一行，將其修改成

\end{CJK} 
\end{document}

保存並關閉refman.tex。
而後打開終端，使用cd命令進入latex目錄，而後執行「make」命令。

執行完畢後後，該目錄中會出現「refman.pdf」——