iOS开发项目自动生成技术文档

来源：互联网发布：信盈达培训好不好知乎编辑：程序博客网时间：2024/05/17 01:42

转载自：http://www.iphonetrain.com/index.php?tp=blog_info&id=67

做项目一般都会要求写技术文档，特别是单干接项目的，客户多少都会要求除了提供code之外，还得提供技术文档，而如果我们手写这类的文档，那工作量不比写code少。一般的开发工具都会提供类似集成的功能，比如Java语言本身就自带javadoc命令，可以从源码中抽取文档，几个配置，几条命令就搞定了。

　　Xcode工具本身不具备这样的功能，但是我们通过一些插件和工具来达到这个目的。

　　生成注释

　　生成文档之前，我们需要给代码中的方法或者变量写上注释，然后再利用工具根据这些规范的注释自动生成文档。所以呢，注释一定要规范统一，但是每次都要手动输入规范化的注释，着实也麻烦，这里需要借助Xcode的开源插件VVDocumenter，规范注释生成器，非常方便!

　　多行注释直接输入三个斜线 "///" 会自动格式化，如上图所示

　　单行注释需要输入三个斜线+空格“///注释”。输入两个“//”当然可以正确的被xcode识别为注释，但是在下面生成文档的时候不能被识别为文档注释。

　　然后再配合 appledoc 、doxygen 或者headdoc，就可以生成技术文档。

　　对于Objective-C来说，目前比较好用的是appledoc 和doxygen。

　　工具对比

　　headerdoc

　　xcode 自带的文档生成工具、基于命令行的操作、使用方便。但是只能生成以 /*!*/的格式的注释。还有一个缺点是每个类文件对应一个注释文件，没有最后汇总导航的index文件。

　　docxygen

　　功能强大、三者中支持语言最多的、无headerdoc缺点、基于图形化的操作界面，但是配置较多，可以生成html文档或pdf文档。

　　appledoc

　　基于命令行的操作、使用方便、无headerdoc缺点、默认生成的文档风格和苹果的官方文档是一致的，即docset，集成到xcode中就跟苹果的官方文档一模一样，在源码中按住option再单击就可以调出相应方法的帮助。当然也可以生成html文档。

　　工具使用

　　appledoc

　　从github下载源码，在终端里面cd源码文件夹，然后执行shell脚本安装

　　安装过程中如果出错，检查一下Xcode所在的路径中是否存在空格，去掉再试之。

　　成功后在终端cd到项目文件夹里面，输入以下命令生成文档：

　　--output../doc 设置文档输出目录为上级目录下面的doc

　　--project-name weibo设置项目名为“weibo”

　　--project-company "wxhl" 设置公司名为“wxhl”

　　--company-id "com.wxhl.weibo" 设置公司id为“com.wxhl.weibo”

(

appledoc --output ../doc --project-name aaa --project-company bbb ./

)

　　. 当前目录

　　当该命令完成后，可以看到在上级目录的doc文件夹里面有一个docset-installed.txt的文件，这里面描述了docset文档所在的真正路径，一般都是在～/Library/Developer/Shared/Documentation/DocSets/里面，或者看看xcode中的Organizer- Documentation，会发现其中新增了帮助文档。

　　生成HTML

　　对于最新版本的appledoc来说，它默认时是生成docset文档并集成到xcode。当需要html文档时，可以加上“--no-create-docset”

当该命令完成后，可以看到在上级目录的doc文件夹里面就不是docset-installed.txt文件了，而是全部的html文档，直接打开index就行。

doxygen

doxygen支持源码编译安装与dmg安装。去doxygen官网下载最新的dmg，doxygen有图形界面，可通过Launchpad打开。

在step 1中选择好项目的路径。
step 2默认是Wizard->Project页面，在其中
1) 在“Project name”中填写项目名。
2) 勾选“Sacn recursively”，扫描所有的子文件夹。
3) 在“Destination directory”中填写好文档的输出目录。这里我填的是“docs”。