Objective-C文档生成

很多开发者忽略了文档的重要性。

再次打开自己半年前开发的某个项目，会发现思路几乎已忘得一干二净－－当时自己做了什么？如何做的？为什么这么做？如果需要增添功能，没有文档的帮助，将会变得十分困难；零星的注释只能帮助代码片段的理解。因为项目已经生疏，需要将整个项目的代码从头到尾、一行一行重新吃透，唤醒大脑中该项目的记忆，才知道如何下手。如果有编写得当的文档，通过查阅文档能很快重新理解项目，也能很快找出与新增功能相关的部分。这将大大提高效率，同时节省了时间。

如果开发者参与团队开发，没有文档就是一场灾难了。当你向团队提交代码后，不得不向其他成员解释你写了什么？为什么这么写？当项目非常庞大时，开发者不可能完全理解其他成员的代码。以上这些都会对时间造成不必要的浪费。在团队开发中编写文档就像某种形式的沟通，同时能帮助其他成员理解自己的代码，毕竟每个人的代码风格都不同。让团队成员理解自己的代码是必不可少的任务。

3个主流的文档生成工具

HeaderDoc

Doxygen

appledoc

注意

1. 常见的tag有：@brief, @param, @return 完整列表
2. @character是所有tag的前缀。
3. 以上符号“@”可以替换为反斜线“\”（@brief变为\brief）。
4. “\”一般用于Doxygen。
5. “@”一般用于HeaderDoc。
6. 使用“@”可以同时适用Doxygen和HeaderDoc。
7. HeaderDoc只能识别/*! */格式的注释，而Doxygen能识别/*! */和/** */两种格式。
8. 对于方法（method），生成HTML文档时只会识别头部文件中的注释，其他地方的注释只会在Xcode help显示，并不会加入到生成的HTML文档中。
9. @field用于描述struct和霉女（Enum）中的单个变量，HeaderDoc能识别，而Doxygen不能。在struct中每个变量顶部用/*! */格式注释，两个工具都能识别。
10. Xcode支持对@param标签中的参数名进行检查，可在Build Settings中开启。

---

参考

以下是三个工具的介绍和使用教程：

Documenting Your Objective-C and Swift Code in Xcode with HeaderDoc and Doxygen

使用Objective-C的文档生成工具:appledoc

用 appledoc 生成文档