OC 自动生成文档工具：appledoc

参考1
参考2

环境：
XCode 11.1

appledoc git 地址

1. 安装

第一种方式： brew 安装

brew install appledoc

！！！注意 1：

我使用 brew 安装，执行2步骤之后生成的 apiDoc ，双击 index.html，只能看到工程的头文件，没有详细的注释。所以建议使用 git 安装。
参考

第二种方式：git clone

随意找一目录即可。
git clone git://github.com/tomaz/appledoc.git

cd ./appledoc

sudo sh install-appledoc.sh

2. 使用

使用脚本生成文档。
首先进入目标工程文件根目录。

a. 生成 appledoc 脚本文件：

touch appledoc

b. 编辑

vi appledoc

输入以下内容：

appledoc \
--output ./apiDoc \
-i *.m \
--project-name "工程名称" \
--project-company "公司名称" \
--no-create-docset \
--keep-undocumented-objects \
--keep-undocumented-members \
--no-warn-undocumented-object \
--no-warn-undocumented-member  \
./

上述脚本解释：

#!/bin/bash
appledoc \
#文档输出目录
--output ./apiDoc \                                       
#忽略.m文件，因.m中均为私有api和属性，开源的接口文档中理应忽略掉
-i *.m \                                                         
#工程的名字
--project-name "GSecretKey" \
#公司的名字
--project-company "com.Gome" \
#不生成docset，直接输出html
--no-create-docset \
#没有注释的文件也输出html  -->目的是看到所有的文件
--keep-undocumented-objects \
#没有注释的属性和方法也输出到html  -->目的是看到所有的属性和方法
--keep-undocumented-members \
#没有注释的文件不提示警告
--no-warn-undocumented-object \
#没有注释的属性和方法不提示警告
--no-warn-undocumented-member \
#需要输出的文件路径  -->这里推荐最好直接为当前工程路径平级输出，便于维护和使用
./

！！！注意 2：

之所以脚本加 --no-create-docset 参数，因为 XCode9.3 之后，没有 docsetutil，所以 docset 集成到 XCode 时出错
参考1
参考2

c. 运行脚本

sh appledoc

d. 查看

双击 index.html，即如下图所示：

！！！注意 3：

在我的电脑上，执行完脚本，发现工程文件夹下并没有生成 apiDoc 文件夹，此时在 Terminal 里执行 ls 命令，咦，这里不是有 apiDoc 吗？再执行 open apiDoc，打开文件夹即可。

3. XCode 集成

每次更新代码注释之后，都要运行一次脚本来更新文档。好像很麻烦的样子。
下面步骤可以将脚本放入 XCode 中，每次 Command + B 即可。

a. 添加 Target

名称就叫做 TestDoc（工程名 + Doc）

b. 添加脚本

脚本如上面 2.b

c. 编译

Command + B 编译即可。

当然，我依然会出现注意3中的情况，一样处理即可。

=================================================================
个人博客
Github
个人公众号：Flutter小同学

个人网站