### 前言

對於開發人員而言，文件的作用不言而喻。文件不僅可以提高軟體開發效率，還能便於以後的軟體開發、使用和維護。本文主要講述 Objective-C 快速生成開發文件工具 appledoc。

### 簡介

appledoc 是一個命令列工具，它可以幫助 Objective-C 開發者從特殊格式的原始碼註釋中生成類似 Apple 的原始碼文件。它的設計目的是在輸入時儘可能採 HTML 格式文件，以及完全索引和可瀏覽的 Xcode 文件集。

![appledoc](https://img-blog.csdnimg.cn/1be296facaef4aba9ccd8b04411c4569.png)

### 支援的註釋

```
`/// 這是單行註釋。`

`/** 這也是單行註釋 */`

`/*! 同樣是單行註釋 */`

`/** 這也是單行註釋，`

`*  第二行會接上第一行。`

`*/`

`/** 第一行是類的簡介`

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

`沒有間隔換行會被消除，就像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   這裡是引數說明1`

`@param green 這裡是引數說明2`

`@param blue   這裡是引數說明3`

`@return  這裡是返回值說明`

`*/`

`- (UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue;`

`- (void)someMethod:(NSString *)str;`

`@end`
```

### 安裝 appledoc 環境

#### 方式一：

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

```
// 下載程式碼
git clone git://github.com/tomaz/appledoc.git

// 進入目錄
cd ./appledoc

//執行安裝指令碼
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
```

### 生成文件

建立一個 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檔案，引數使用“=”等號寫法)
$ 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 目錄，執行
```
$ appledoc --project-name ARtcKit_4.2.2.7 --project-company anyrtc ./
```

**文件效果**

![appledoc](https://img-blog.csdnimg.cn/97944dfc21314004a776938f06a7c4b7.png)

![在這裡插入圖片描述](https://img-blog.csdnimg.cn/724946952b6d4a01a748c7badf18992a.jpeg#pic_center)

IOS技術分享| iOS快速生成開發文件（一）

相關文章