iOS快速生成開發(fā)文檔

前言

對于開發(fā)人員而言，文檔的作用不言而喻。文檔不僅可以提高軟件開發(fā)效率瓣铣，還能便于以后的軟件開發(fā)飞蹂、使用和維護。本文主要講述 Objective-C 快速生成開發(fā)文檔工具 appledoc锈嫩。

簡介

appledoc 是一個命令行工具，它可以幫助 Objective-C 開發(fā)者從特殊格式的源代碼注釋中生成類似 Apple 的源代碼文檔。它的設(shè)計目的是在輸入時盡可能采 HTML 格式文檔呜象，以及完全索引和可瀏覽的 Xcode 文檔集膳凝。

支持的注釋

`/// 這是單行注釋。`
`/** 這也是單行注釋 */`
`/*! 同樣是單行注釋 */`
`/** 這也是單行注釋恭陡，`
`*  第二行會接上第一行蹬音。`
`*/`
`/** 第一行是類的簡介`

`在簡介的下面,就是類的詳細介紹了。`

`沒有間隔換行會被消除休玩，就像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`

`標題:`

`# 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://    blog.ibireme.com](http://    blog.ibireme.com)`

`[這個]([http://example.net/](http://example.net/)) 鏈接會隱藏實際URL.`

`表格:`

`| header1 | header2 | header3 |`

`|---------|:-------:|--------:|`

`| normal  |  center |  right  |`

`| cell    | cell    | cell    |`

`引用:`

`這里會引用到方法 `someMethod:`呐矾，這里會引用到類 `YYColor``

`這里會引用到一個代碼塊`

`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 YYColor`

`@see someMethod:`

`@warning 這里是警告蜒犯，會顯示成藍色的框框`

`@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`

安裝 appledoc 環(huán)境

方式一：

打開終端，輸入以下命令：

// 下載代碼
git clone git://github.com/tomaz/appledoc.git

// 進入目錄
cd ./appledoc

//執(zhí)行安裝腳本
sudo sh install-appledoc.sh

// 檢驗是否安裝成功
appledoc --version

安裝第3步報錯

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance

解決：

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer/

方式二：

前提安裝了 Homebrew（在此不作贅述）

brew install appledoc

生成文檔

創(chuàng)建一個 app 工程罚随，拖入.h文件

TARGETS -> Build Phases -> Run Script 中添加腳本

/usr/local/bin/appledoc \
--project-name "${PROJECT_NAME}" \
--project-company "${company}" \
--company-id "${companyID}" \
--docset-atom-filename "${company}.atom" \
--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}/${docFilePath}"

指令用法

##### 參考指令寫法1(不生成docset文件)
$ appledoc --no-create-docset --output ./doc --project-name "工程名" --company-id "bundle id" --project-company "公司名" ./
##### 參考指令寫法2(不生成docset文件晨炕，參數(shù)使用“=”等號寫法)
$ appledoc --no-create-docset --output="./doc" --project-name="工程名" --company-id="bundle id" --project-company="公司名" ./
##### 參考指令寫法3(生成docset文件并指定生成路徑)
$ appledoc --output ./doc --project-name "工程名" --company-id "bundle id" --project-company "公司名" ./ --docset-install-path ./doc
##### 以上都是掃描指定目錄下的文件，如果想掃描當前目錄所有文件毫炉，只需要將指定目錄換成"."即可
$ appledoc --no-create-docset --output="./doc" --project-name="工程名" --company-id="bundle id" --project-company="公司名" .

例如：終端進入 app 目錄瓮栗，執(zhí)行

$ appledoc --project-name ARtcKit_4.2.2.7 --project-company anyrtc ./