接触过 java 的童鞋们一定知道 javadoc 这种东西,写好代码、码上注释,然后用 javadoc 一跑,一包 html 的文档就生成好了,和 Sun(甲骨文)的官方文档一个调调。在用 eclipse 的时候,代码的自动提示就能显示注释了,html 文档用处不大(对我来说)。但是用 Xcode 开发如果没有文档,确实不太方便。这里就介绍一下 iOS 开发生成文档的方法吧。

竞品分析

Mac上还是有挺多文档生成的工具的,下面是比较主流的3个家伙的对比。

HeaderDoc

HeaderDoc是苹果官方的文档生成工具。支持JavaDoc风格的注释,支持一些比较常见的语言,例如Java、C/C++、ObjC、Python、Ruby等等。 官方的好处就是:安好Xcode就自带了,生成的文档风格和Apple官方保持一致,支持语言较多。缺点就是可调教的的地方较少,不生成聚合页,注释风格要求较严等。

总之,除了Apple外,其他人用的比较少。。
官方文档

Doxygen

Doxygen原本是为C++开发的文档生成工具,当然它是开源的,通过一票扩展也能支持各种主流非主流语言。除了能生成HTML外,还能生成pdf和\(\LaTeX\)格式。在appledoc出现之前,很多人就喜欢用这个来生成ObjC代码的文档。相比HeaderDoc来说,有很多可以调教的地方。苹果官方也曾为这个工具写过文档。一切看上去都很棒,不足的地方就是,它生成的文档风格和官方文档的风格差了很多(虽然说不算太难看,但是放到Xcode里看格格不入),配置复杂等。。
官方文档

appledoc

appledoc是最年轻的一个,并且只为Objective-C服务(很专一),能生成和Apple一个风格的文档,功能齐全,使用方便,还可以直接编译成docset安装进xcode。。看样子除了语言支持太少,其他的表现都不错,关键是最贴合Xcode。 虽然没有统计数据,但我相信ObjC这个用的人应该是最多的。
Github项目链接

安装

Github把工程clone下来,用Xcode打开,然后随便搞。。

之后重新编译一遍appledoc.xcodeproj

安装完成后,验证一下OK了没:

 

使用

进入code所在目录,跑一下下面的命令,默认会编译出docset并安装进Xcode。



如果想要详细的参数,可以查看帮助



如果想要集成进Xcode工程:
1.选中你的工程,点击Add Target按钮,选择 Other -> Aggregate模板新建.
2.点击Add Build Phase按钮,添加一个Run Script.
3.把下面的模板代码复制进去,把前几行参数改成你自己的.
4.在Xcode左上角选择这个新建的Target,然后点击build.
5.文档就会编译好并且自动安装进Xcode了(重启Xcode生效).

 

语法

appledoc官方原来是有一篇语法的,但是现在貌似维护中了。。所以这里尽量多介绍一下。


首先,文档中的注释只有符合规范,才能被appledoc认可。

凡是以 “///”、”/**”或”/*!”开头的注释块,都算所appledoc注释。下面是示例:

注释块中,每一行开头的空格和”*”字符多数情况都会被appledoc忽略。
连续的两行(即没有间隔空行)的注释,将被合并成一个段落,并忽略换行,就像html。


在注释块内,appledoc支持如下语法:Markdown、HTML、HeaderDoc Tags。

Markdown的语法在这里有介绍(中文翻译),用Github的童鞋应该很熟悉。OSX上可以用Mou实时查看效果,Chrome也有一个插件来实时查看效果。这个东西可以说一看就会,学习成本很低。Markdown有很多方言,而且appledoc支持的也不算完整。所以用的时候可以试着在appledoc编译一下看看效果。

HTML这个就不用说了,支持Markdown肯定也支持HTML。。如果想要把控住更多细节,那就直接码Html吧。

HeaderDoc Tags这个东西是苹果的HeaderDoc工具的语法。详情可以见官网文档。例如@param、@return、@warning这样的东西,appledoc会进行解释。当然appledoc对这个东西的支持也不算完整 :?: 所以用的时候也要尝试一下。

通常情况下,Xcode会给关键词高亮显示,就像下面这样:
appppp


下面是一些常用的语法示意:

编译出的效果是这样
app1
app2
app3
app4
app5

appledoc还有很多不太完善的地方,比如C方法和宏定义上面的注释就不被识别,URL链接有时会识别错误等。。这时候只能手动修改生成好的html了;或者比较勤快自己手动fork一个appledoc改一下。。

其他

编译出的Docset默认会放在/Users/ibireme/Library/Developer/Shared/Documentation/DocSets路径下。

Docset格式,实际上是一个bundle,里面包含了一些xml和html。显示包内容后就可以查看和修改了。如果需要放到网站上,那单独将html部分取出来就行。

Docset安装后,在Xcode中就可以实时查看某个方法的说明了,体验和官方文档保持一致。(有一点,category中的注释不会出现在xcode的快速帮助中,不知道新版xcode是否会有改进..)

除了Xcode外,Dash支持得也很棒。强烈推荐~

PS:实际我是想给我的工具包生成一下文档,这样用起来会方便些 (看起来会上流些):evil: 。想用些更标准的注释但又找不到appledoc的语法文档。。所以在这里记一个备份。