技术文档生成工具: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,里面包含了一些xmlhtml。显示包内容后就可以查看和修改了。如果需要放到网站上,那单独将html部分取出来就行。 

4.参考资料 

如何将自己项目的代码文档导出为苹果样式

 

posted @ 2017-04-18 15:45  LeeGof  阅读(821)  评论(0编辑  收藏  举报