IOS技术分享| iOS快速生成开发文档

Posted 2022-05-25 anyRTC

前言

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

文档效果