IOS技術分享| iOS快速生成開發文件（一）
阿新 • • 發佈：2022-05-24
前言
對於開發人員而言，文件的作用不言而喻。文件不僅可以提高軟體開發效率，還能便於以後的軟體開發、使用和維護。本文主要講述 Objective-C 快速生成開發文件工具 appledoc。
簡介
appledoc 是一個命令列工具，它可以幫助 Objective-C 開發者從特殊格式的原始碼註釋中生成類似 Apple 的原始碼文件。它的設計目的是在輸入時儘可能採 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 這裡是引數說明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 ./
文件效果