美文网首页
Xcode生成API开发文档(headerdoc, doxyge

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

作者: 终生程序员小松哥 | 来源:发表于2019-02-19 10:49 被阅读10次

主要参考:

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+/ 就能自动生成格式化注释白板。

欢迎大家找我交流

相关文章

网友评论

      本文标题:Xcode生成API开发文档(headerdoc, doxyge

      本文链接:https://www.haomeiwen.com/subject/izhxyqtx.html