技术文档生成工具:appledoc
做项目一般都会要求写技术文档,特别是提供SDK或者基础组件的。如果手写这类技术文档的话,工作量比编写代码也少不了多少。比如 Java 语言本身就自带 javadoc 命令,可以从源码中抽取文档。本篇我们看一下OC中的一个类似工具:appledoc。
1.简介
基于命令行的操作、使用方便,默认生成的文档风格和苹果的官方文档是一致的,即docset,集成到xcode中就跟苹果的官方文档一模一样,在源码中按住option再单击就可以调出相应方法的帮助,当然也可以生成html文档。
总结一下,它具有下面这些特点:
- 它默认生成的文档风格和苹果的官方文档是一致的;
- appledoc 是用 objective-c 生成的,必要的时候调试和改动也比较方便;
- 可以生成 docset,并且集成到 Xcode 中,相当于在源码中按住 option 再单击就可以调出相应方法的帮助;
- appledoc 源码在 github 上;
- 没有特殊的注释要求,可以用
/\*\* \*/
的格式,也可以兼容/\*! \*/
的格式的注释,并且生成的注释有汇总页面。
2.安装
安装很简单,按照下面的指令执行即可:
git clone git://github.com/tomaz/appledoc.git cd appledoc sudo sh install-appledoc.sh
3.使用
使用 appledoc 时,只需要用如下命令即可:
/* --project-name 工程名字 --project-company 公司名字 --company-id 公司ID --output 生成结果路径 */ appledoc --no-create-docset --output ../doc --project-name GofKit --project-company "Gof" --company-id "com.gof" .
appledoc 会扫描当前路径下的所有文件,然后生成好文档放到 doc 目录下。
简写如下所示:
appledoc -o ./doc --project-name GofKit --project-company Gof .
编译出的Docset
默认会放在~/Library/Developer/Shared/Documentation/DocSets
路径下。 Docset
格式,实际上是一个bundle
,里面包含了一些xml
和html
。显示包内容后就可以查看和修改了。如果需要放到网站上,那单独将html
部分取出来就行。
4.参考资料
无善无恶心之体,
有善有恶意之动,
知善知恶是良知,
为善去恶是格物。