Xcode生成API开发文档（headerdoc, doxyge

主要参考：

iOS开发日记23-Xcode生成API文档(HeaderDoc)

苹果对HeaderDoc的说明文档

代办列表上记着的一件事，要去弄懂下Xcode上如何生成开发文档。开发文档的作用在于传播和传承，帮助其他工程师理解如何调用你的函数，也方便下个程序员接手你的工作，是合格的工程师都要去做的例行事项。当然写完代码，还要再写一个开放文档很是烦人；所以提倡代码文档化，代码写好了，文档有就有了。

原理

在写代码的时候，加上适当的注释；在利用一些工具的帮助，就可以生成完整的API文档；如果有代码改动，工程师也需要同时更新注释。代码文档化的好处就是，代码和文档可以保持同步更新，而不是放在两个地方需要分别更新。

这个是一个简单实例，注释必须按照格式进行编写。具体参考文章开头提到的苹果说明。

/**

生成一组排列好的按钮

@param titles 按钮的标题列表

*/

- (void)buildBtns:(NSArray*)titles;

生成文档的工具有三种：headerdoc, doxygen 和 appledoc。用法见文章开头的第一个参考资料。

我亲测了苹果官方工具headerdoc。

生成工具非常强大，生成的是HTML格式，甚至可以自定义生成的样式，也可以生成交叉索引。

有几个注意点

1，注释的格式不同，要挑选对于的生成工具。

2，官方的headerdoc已经不再建议使用（2016-05-05 Moved to Retired Documents Library.），原因是自从Xcode8以后使用 "Quick Help"就能看到注释信息非常方便，如下图。我认为生成出文档还是有作用的，可以传播给其他人看，而不是非得要下载你代码后才能看API文档信息。

Quick Help

3，以上3种工具都不适用于swift，因为它的注释格式不一样了。要用另外一种工具 https://github.com/realm/jazzy （我没有亲测）。

4，Xcode 8后，只要选中你要注释的类，函数，结构体名字，然后按下 option+command+/ 就能自动生成格式化注释白板。

欢迎大家找我交流