iOS开发----IOS项目自动生成技术文档
2014-02-09 11:14
363 查看
做项目一般都会要求写技术文档,特别是单干接项目的,客户多少都会要求除了提供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脚本安装
[plain] view
plaincopy
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh
安装过程中如果出错,检查一下Xcode所在的路径中是否存在空格,去掉再试之。
成功后在终端cd到项目文件夹里面,输入以下命令生成文档:
[plain] view
plaincopy
appledoc --output ../doc --project-name weibo --project-company "wxhl" --company-id "com.wxhl.weibo" .
--output ../doc 设置文档输出目录为上级目录下面的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中的Organizer - Documentation,会发现其中新增了帮助文档。
生成HTML
对于最新版本的appledoc来说,它默认时是生成docset文档并集成到xcode。当需要html文档时,可以加上“--no-create-docset”
[plain] view
plaincopy
appledoc --no-create-docset --output ../doc --project-name weibo --project-company "wxhl" --company-id "com.wxhl.weibo" .
当该命令完成后,可以看到在上级目录的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”。
点击中间的“Expert”切换Expert->Project页面,在其中
1) 将“OUTPUT_LANGUAGE”设为“Chinese”,使用简体中文。
2) 勾选“JAVADOC_AUTOBRIEF”,自动将注释的第1段识别为简要描述。
点击中间的“Run”切换Run页面,然后点击“Run doxygen”按钮生成文档。
当文档生成完毕后,使用浏览器打开docs/html/index.html——
生成PDF
doxygen默认会为生成pdf做好准备。切换到Wizard->Project,会发现它自动勾选了“LaTex”与“as intermediate format for hyperlinked 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;而含有中文时,不能顺利生成pdf文件。
对于latex排版,doxygen其实已经做了很多准备,比如——源文件是UTF-8编码,并默认使用了utf8 package。理论上是支持多国语言的。
可对于中文来说,还需要加载 CJKutf8 package,并配置好CJK环境。这才能顺利的使用中文。
用文本编辑器打开docxygen生成的latex目录中的refman.tex。找到“\begin{document}”这一行,将其修改为
然后再找到“\end{document}”这一行,将其修改为
保存并关闭refman.tex。
然后打开终端,使用cd命令进入latex目录,然后执行“make”命令。
执行完毕后后,该目录中会出现“refman.pdf”——
参考
http://www.cnblogs.com/zyl910/archive/2013/06/07/objcdoc.html http://blog.devtang.com/blog/2012/02/01/use-appledoc-to-generate-xcode-doc/
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脚本安装
[plain] view
plaincopy
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh
安装过程中如果出错,检查一下Xcode所在的路径中是否存在空格,去掉再试之。
成功后在终端cd到项目文件夹里面,输入以下命令生成文档:
[plain] view
plaincopy
appledoc --output ../doc --project-name weibo --project-company "wxhl" --company-id "com.wxhl.weibo" .
--output ../doc 设置文档输出目录为上级目录下面的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中的Organizer - Documentation,会发现其中新增了帮助文档。
生成HTML
对于最新版本的appledoc来说,它默认时是生成docset文档并集成到xcode。当需要html文档时,可以加上“--no-create-docset”
[plain] view
plaincopy
appledoc --no-create-docset --output ../doc --project-name weibo --project-company "wxhl" --company-id "com.wxhl.weibo" .
当该命令完成后,可以看到在上级目录的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”。
点击中间的“Expert”切换Expert->Project页面,在其中
1) 将“OUTPUT_LANGUAGE”设为“Chinese”,使用简体中文。
2) 勾选“JAVADOC_AUTOBRIEF”,自动将注释的第1段识别为简要描述。
点击中间的“Run”切换Run页面,然后点击“Run doxygen”按钮生成文档。
当文档生成完毕后,使用浏览器打开docs/html/index.html——
生成PDF
doxygen默认会为生成pdf做好准备。切换到Wizard->Project,会发现它自动勾选了“LaTex”与“as intermediate format for hyperlinked 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;而含有中文时,不能顺利生成pdf文件。
对于latex排版,doxygen其实已经做了很多准备,比如——源文件是UTF-8编码,并默认使用了utf8 package。理论上是支持多国语言的。
可对于中文来说,还需要加载 CJKutf8 package,并配置好CJK环境。这才能顺利的使用中文。
用文本编辑器打开docxygen生成的latex目录中的refman.tex。找到“\begin{document}”这一行,将其修改为
\usepackage{CJKutf8} \begin{document} \begin{CJK}{UTF8}{gbsn}
然后再找到“\end{document}”这一行,将其修改为
\end{CJK} \end{document}
保存并关闭refman.tex。
然后打开终端,使用cd命令进入latex目录,然后执行“make”命令。
执行完毕后后,该目录中会出现“refman.pdf”——
参考
http://www.cnblogs.com/zyl910/archive/2013/06/07/objcdoc.html http://blog.devtang.com/blog/2012/02/01/use-appledoc-to-generate-xcode-doc/
相关文章推荐
- iOS开发项目自动生成技术文档
- iOS开发----IOS项目自动生成技术文档
- iOS开发项目自动生成技术文档
- iOS开发----IOS项目自动生成技术文档
- IOS项目自动生成技术文档很方便实用
- IOS项目自动生成技术文档
- IOS项目自动生成技术文档
- iOS项目开发中常用到的自动布局技术----- Masonry
- 自动导出iOS项目技术文档
- DotNet 项目开发文档的自动生成和相关工具的使用
- 【2016.3.30项目技术记录】]VS2010自动生成MFC单文档框架程序的修改:去除属性框,在CViewTree类中添加鼠标单击响应
- 【ios开发技术】IOS项目工程自动打包并发布(用脚本实现打包)
- NLP+VS=>Image Caption︱自动生成图像标题技术论文+相关项目
- 使用AppleDoc自动生成项目文档(XCode8)
- iOS开发中,如何将第三方或者自己生成的静态库(SDK)引入到自己的项目中?
- javadoc自动生成开发文档
- 用Swashbuckle给ASP.NET Core的项目自动生成Swagger的API帮助文档
- iOS 开发 Pch 文件的正确使用1.存放一些全局的宏(整个项目中都用得上的宏) 2.用来包含一些全部的头文件(整个项目中都用得上的头文件) 3.能自动打开或者关闭日志输出功能
- Xcode4自动生成注释和开发文档
- 关闭 晓K的专栏 我的学习历程 目录视图摘要视图订阅 赠书 | 异步2周年,技术图书免费选 每周荐书:渗透测试、K8s、架构(评论送书) 项目管理+代码托管+文档协作,开发更