Appledoc

工具简介

Appledoc是一款开源工具，使用它可以根据指定路径下代码文件中的注释，为项目生成Apple风格的API文档。

工具教程

1.安装

appledoc可以通过Homebrew安装，终端执行命令brew install appledoc即可，不过这种方式不会一并安装文档模板（template），所以更推荐通过appledoc项目的源文件来安装：

# 1. clone appledoc文件
git clone git://github.com/tomaz/appledoc.git

# 2. 进入appledoc目录
cd ./appledoc

# 3. 运行appledoc安装脚本
sudo sh install-appledoc.sh

2.使用

代码注释

appledoc支持导出Markdown语法书写的注释，同时也支持导出Xcode通过Command + Option + /为方法添加的标准注释，附Xcode标准注释的关键字：

/**
 @brief     方法简要描述
 @param     方法参数说明
 @exception 方法会抛出异常
 @see       参看相关的 Method/Function/枚举
 @discussion    方法详细说明
 @warning   警告
 @bug       BUG
 @return    返回值
 */

导出文档

appledoc的命令格式为appledoc [OPTIONS] <paths to source dirs or files>，常用的appledoc命令如下：

appledoc -i *.m --keep-undocumented-objects --keep-undocumented-members -h --no-publish-docset --no-create-docset --no-install-docset -c "公司名称" -p "项目名称" -o "输出地址" "源文件目录"

命令的最后是需要导出文档的源文件目录，中间是命令参数，appledoc所支持的更多命令参数可通过appledoc --help进行查看。

命令成功执行后通常是在指定的输出地址下生成一个名为docset-installed.txt的文件（示例命令是直接在输出地址中生成html文档），里面记录了导出的文档的地址，导出的文档一般在~/Library/Developer/Shared/Documentation/DocSets/目录下，文档为.doset格式，可通过右键-显示包内容查看其内容。

Aggregate

可以通过为项目添加Aggregate Target，再为Aggregate添加Run Script，最后再编译Aggregate的方式来方便快速的为项目生成API文档。

添加Aggregate：Xcode中依次File -> New -> Target... -> Aggretgate进行添加；

添加Run Script：在添加的Aggregate的Build Phases中添加Run Script；

Run Script示例:

company="组织名称";  
companyID="组织ID";
outputPath="${PROJECT_DIR}";
filePath="${PROJECT_DIR}"

appledoc \
-i *.m \
--keep-undocumented-objects \
--keep-undocumented-members \
-h \
--no-publish-docset \
--no-create-docset \
--no-install-docset \
--company-id "${companyID}" \
-c "${company}" \
-p "${PROJECT_NAME}" \
-o "${outputPath}" \
--exit-threshold 2 \
"${filePath}"

3.注意

使用appledoc的注意事项：

• appledoc不会导出//注释的内容，需要导出的单行注释可以使用///；
• Xcode9.3之后不再支持集成自定义文档，使用appledoc集成文档时会报Error，但不影响文档的导出，详见Issue；