appledoc自动输出开发文档教程

一、工具安装

打开终端，使用命令安装appledoc，推荐用以下方法安装。不推荐用brew安装，用brew安装会有两个问题：1.不会自动安装html模版，生成的html没有样式；2. 分类代码不输出文档。

git clone git://github.com/tomaz/appledoc.git
cd ./appledoc
sudo sh install-appledoc.sh

安装过程的可能出现以下报错：

解决方法：在Xcode的设置中，选择一个Command Line Tools

二、脚本编写

我们在工程目录下创建一个shell脚本，脚本内容如下，保存为updateDoc.sh。相比其他网上的教程，以下脚本解决了两个问题：

1. 有一些属性和方法很简单，通过方法名就能看懂是做什么用的，所以没有注释，这部分代码默认是不输出文档，我们添加--keep-undocumented-objects --keep-undocumented-members，可以让所有的方法和属性都输出到文档中。

2. 忽略.m文件，因为.m文件中大部分是具体的实现过程，很多私有方法和变量，所以要忽略。

#!/bin/bash
appledoc \
--output ./Doc \
-i *.m \
--project-name "IGUIKit" \
--project-company "Tencent" \
--no-create-docset \
--keep-undocumented-objects \
--keep-undocumented-members \
--no-warn-undocumented-object \
--no-warn-undocumented-member \
./IGUIKit

解释一下参数目的：

三、执行脚本

 ./updateDoc.sh

 如果不能执行，记得改一下脚本文件属性，使它能够被执行

chmod +x updateDoc.sh  #使脚本具有执行权限

执行完成，我们可以在Doc目录生成了html文件，点击index.html即可查看文档

 

四、注释规范

1. 注释类和方法

文档效果：

2. 注释属性

文档效果：

3.注释枚举

枚举使用单行注释就可以，使用/** * xxx */是为了好看，生成的文档带一个原点，文档效果：

枚举类型的属性

文档效果：

五、文档更新

每当代码更新了，注释变更了，就应该跑一下updateDoc.sh脚本，更新文档。

最后感谢大家的阅读，欢迎指出问题和提出建议。