文档章节

IOS项目自动生成技术文档很方便实用

田广ly
 田广ly
发布于 2016/03/18 12:56
字数 1379
阅读 168
收藏 3

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 plain copy 在CODE上查看代码片派生到我的代码片

  1. git clone git://github.com/tomaz/appledoc.git  

  2. cd appledoc  

  3. sudo sh install-appledoc.sh  

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

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

[plain] view plain copy 在CODE上查看代码片派生到我的代码片

  1. 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 plain copy 在CODE上查看代码片派生到我的代码片

  1. 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://blog.csdn.net/jaywon/article/details/18448641

共有 人打赏支持
田广ly
粉丝 1
博文 5
码字总数 1358
作品 0
海淀
iOS工程师
私信 提问
xmake v1.0.3 发布,轻量级跨平台自动构建工具

简介 XMake是一个跨平台自动构建工具,支持在各种主流平台上构建项目,类似cmake、automake、premake,但是更加的方便易用,工程描述语法更简洁直观,支持平台更多,并且集创建、配置、编译、...

ruki
2015/12/02
1K
10
xmake v1.0.4 发布,轻量级跨平台自动构建工具

xmake现在已经被homebrew收录,macosx/linux上可以通过homebrew/linuxbrew进行快速安装。。 v1.0.4更新: 增加对windows汇编器的支持 增强add_files接口,支持直接添加*.o/obj/a/lib文件,并且...

ruki
2016/01/12
3.1K
11
iOS开发者必备:九大设计类工具

“工欲善其事,必先利其器”,对于iOS开发者和设计师来说,若在开发和设计的过程中有“利器”在手,那或许将会起到事半功倍的效果。现在,就让我们盘点下,当下最为流行和实用的iOS设计类开发...

沉淀岁月
2013/09/12
269
0
GitHub 上排名前 100 的 Objective-C 项目简介

主要对当前 GitHub 排名前 100 的项目做一个简单的简介, 方便初学者快速了解到当前 Objective-C 在 GitHub 的情况. 若有任何疑问可通过微博@李锦发联系我 项目名称 项目信息 1. AFNetworkin...

oschina
2015/04/11
33.2K
28
(转)直接拿来用!最火的iOS开源项目(二)

“每一次的改变总意味着新的开始。”这句话用在iOS上可谓是再合适不过的了。GitHub上的iOS开源项目数不胜数,iOS每一次的改变,总会引发iOS开源项目的演变,从iOS 1.x到如今的iOS 7,有的项目...

孙启超
2013/06/21
0
1

没有更多内容

加载失败,请刷新页面

加载更多

[springBoot系列]--springBoot注解大全

一、注解(annotations)列表 @SpringBootApplication:包含了@ComponentScan、@Configuration和@EnableAutoConfiguration注解。其中@ComponentScan让spring Boot扫描到Configuration类并把它加......

Jack088
2分钟前
0
0
tomcat编译超过64k大小的jsp文件报错原因

  今天遇到一个问题,首先是在tomcat中间件上跑的web项目,一个jsp文件,因为代码行数实在是太多了,更新了几个版本之后编译报错了,页面打开都是报500的错误,500的报错,知道http协议返回...

SEOwhywhy
23分钟前
1
0
flutter http 请求客户端

1、pubspec文件管理Flutter应用程序的assets(资源,如图片、package等)。 在pubspec.yaml中,通过网址“https://pub.dartlang.org/packages/http#-installing-tab-”确认版本号后,将http(0...

渣渣曦
24分钟前
0
0
Django基本命令及moduls举例

一、Django基本命令 1.创建项目 django-admin.py startproject mysite 创建后的项目结构:- mysite - mysite #对整个程序进行配置 - init #导入包专用- settings ...

枫叶云
39分钟前
7
0
zabbix安装

rpm -ivh http://repo.webtatic.com/yum/el6/latest.rpm 安装jdk rpm -ivh (自行在网上下载rpm包) 安装php并修改相应参数 yum -y install php56w php56w-gd php56w-mysqlnd php56w-bcmath......

muoushi
40分钟前
4
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部