《iOS项目自动生成技术文档》由会员分享，可在线阅读，更多相关《iOS项目自动生成技术文档（13页珍藏版）》请在金锄头文库上搜索。
1、iOS 项目自动生成技术文档做项目一般都会要求写技术文档，特别是单干接项目的，客户多少都会要求除了提供 code之外，还得提供技术文档，而如果我们手写这类的文档，那工作量不比写 code 少。一般的开发工具都会提供类似集成的功能，比如 Java 语言本身就自带 javadoc 命令，可以从源码中抽取文档，几个配置，几条命令就搞定了。Xcode 工具本身不具备这样的功能，但是我们通过一些插件和工具来达到这个目的。生成注释生成文档之前，我们需要给代码中的方法或者变量写上注释，然后再利用工具根据这些规范的注释自动生成文档。所以呢，注释一定要规范统一，但是每次都要手动输入规范化的注释，着实也麻烦，这里
2、需要借助 Xcode 的开源插件 VVDocumenter，规范注释生成器，非常方便！多行注释直接输入三个斜线 / 会自动格式化，如上图所示单行注释需要输入三个斜线+空格 “/ 注释”。输入两个“/”当然可以正确的被 xcode 识别为注释，但是在下面生成文档的时候不能被识别为文档注释。然后再配合 appledoc 、doxygen 或者 headdoc，就可以生成技术文档。对于 Objective-C 来说，目前比较好用的是 appledoc 和 doxygen。工具对比headerdocxcode 自带的文档生成工具、基于命令行的操作、使用方便。但是只能生成以 /*! */ 的格式的注释。
3、还有一个缺点是每个类文件对应一个注释文件，没有最后汇总导航的 index 文件。docxygen功能强大、三者中支持语言最多的、无 headerdoc 缺点、基于图形化的操作界面，但是配置较多，可以生成 html 文档或 pdf 文档。appledoc基于命令行的操作、使用方便、无 headerdoc 缺点、默认生成的文档风格和苹果的官方文档是一致的，即 docset，集成到 xcode 中就跟苹果的官方文档一模一样，在源码中按住option 再单击就可以调出相应方法的帮助。当然也可以生成 html 文档。工具使用appledoc从 github 下载源码，在终端里面 cd 源码文件夹，然后执
4、行 shell 脚本安装plain view plaincopy1. git clone git:/ 2. cd appledoc 3. sudo sh install-appledoc.sh 安装过程中如果出错，检查一下 Xcode 所在的路径中是否存在空格，去掉再试之。成功后在终端 cd 到项目文件夹里面，输入以下命令生成文档：plain view plaincopy1. appledoc -output ./doc -project-name weibo -project-company wxhl -company-id com.wxhl.weibo . -output ./doc 设置
5、文档输出目录为上级目录下面的 doc-project-name weibo 设置项目名为“weibo”-project-company wxhl 设置公司名为“wxhl”-company-id com.wxhl.weibo 设置公司 id 为“com.wxhl.weibo”. 当前目录当该命令完成后，可以看到在上级目录的 doc 文件夹里面有一个 docset-installed.txt 的文件，这里面描述了 docset 文档所在的真正路径，一般都是在/Library/Developer/Shared/Documentation/DocSets/ 里面，或者看看 xcode 中的Organi
6、zer - Documentation，会发现其中新增了帮助文档。生成 HTML对于最新版本的 appledoc 来说，它默认时是生成 docset 文档并集成到 xcode。当需要html 文档时，可以加上“-no-create-docset”plain view plaincopy1. appledoc -no-create-docset -output ./doc -project-name weibo -project-company wxhl -company-id com.wxhl.weibo . 当该命令完成后，可以看到在上级目录的 doc 文件夹里面就 不是 docset-in
7、stalled.txt 文件了，而是全部的 html 文档，直接打开 index 就行。doxygendoxygen 支持源码编译安装与 dmg 安装。去 doxygen 官网下载最新的 dmg，doxygen 有图形界面，可通过 Launchpad 打开。在 step 1 中选择好项目的路径。step 2 默认是 Wizard-Project 页面，在其中1) 在“Project name”中填写项目名。2) 勾选“Sacn recursively”，扫描所有的子文件夹。3) 在“Destination directory”中填写好文档的输出目录。这里我填的是 “docs”。点击中间的“Ex
8、pert”切换 Expert-Project 页面，在其中1) 将“OUTPUT_LANGUAGE”设为“Chinese”，使用简体中文。2) 勾选“JAVADOC_AUTOBRIEF”，自动将注释的第 1 段识别为简要描述。点击中间的“Run” 切换 Run 页面，然后点击“Run doxygen”按钮生成文档。当文档生成完毕后，使用浏览器打开 docs/html/index.html生成 PDFdoxygen 默认会为生成 pdf 做好准备。切换到 Wizard-Project，会发现它自动勾选了“LaTex”与“as intermediate format for hyperlinked
9、 PDF”。doxygen 本身并不能直接输出 pdf 文件，而是生成了 latex 目录，其中有一个 makefile 文件。若系统中装好了 pdflatex，可在 latex 目录中运行“make”命令来生成 pdf 文件。怎样才能装好 pdflatex 呢？mac 平台可安装 MacTeX。打开http:/www.tug.org/mactex/ ，下载 MacTeX.pkg (约 2.1GB)。MacTeX.pkg 下载好后，可双击运行，根据向导来安装。环境装好之后，当在 latex 目录中运行“make” 命令来生成 pdf 文件时，你会发现 纯英文文档能顺利生成 pdf；而含有中文时
10、，不能顺利生成 pdf 文件。对于 latex 排版，doxygen 其实已经做了很多准备，比如 源文件是 UTF-8 编码，并默认使用了 utf8 package。理论上是支持多国语言的。可对于中文来说，还需要加载 CJKutf8 package，并配置好 CJK 环境。这才能顺利的使用中文。用文本编辑器打开 docxygen 生成的 latex 目录中的 refman.tex。找到“begindocument”这一行，将其修改为usepackageCJKutf8 begindocumentbeginCJKUTF8gbsn然后再找到“enddocument” 这一行，将其修改为endCJK enddocument保存并关闭 refman.tex。然后打开终端，使用 cd 命令进入 latex 目录，然后执行“make”命令。执行完毕后后，该目录中会出现“refman.pdf”
