前言
对于开发人员而言，文档的作用不言而喻。文档不仅可以提高软件开发效率，还能便于以后的软件开发、使用和维护。本文主要讲述 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 ./
网友评论