写项目时通常会遇到要求写开发文档的需求,但是就源代码来说,文档最好和源码在一起,这样更新起来更加方便和顺手。Objective-C 有一些文档管理工具,doxygen, headdoc 和 appledoc 。它们分别的官方网址如下:
- docxygen http://www.stack.nl/~dimitri/doxygen/index.html
- headdoc http://developer.apple.com/opensource/tools/headerdoc.html
- appledoc http://gentlebytes.com/appledoc/
appledoc 是在 stackoverflow 上被大家推荐的一个注释工具。有以下优点:
- 它默认生成的文档风格和苹果的官方文档是一致的,而 doxygen 需要另外配置。
- appledoc 就是用 objective-c 生成的,必要的时候调试和改动也比较方便。
- 可以生成 docset,并且集成到 Xcode 中。这一点是很赞的,相当于在源码中按住 option 再单击就可以调出相应方法的帮助。
- appledoc 源码在 github 上,而 doxygen 在 svn 上。我个人比较偏激地认为比较活跃的开源项目都应该在 github 上。
- 相对于 headerdoc,它没有特殊的注释要求,可以用
/\*\* \*/
的格式,也可以兼容/\*! \*/
的格式的注释,并且生成的注释有汇总页面。
Github链接:https://github.com/tomaz/appledoc
安装(Terminal):
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh
出现下面时表示安装成功。
也可以通过命令: appledoc --version 来查看是否安装成功。
接下来就可以对工程进行文档了。
cd 到工程目录,执行命令(appledoc --project-name + 工程名 --project-company + 公司名 )"./" 表示导出到当前文件夹:
appledoc --project-name "TestSecurityAdvance" --project-company "XueshanFinancial" ./
会发现当前工程目录中多了一个 docset-installed.txt 文件。
目录即为文档目录。
对工程新建个 target :
新建 Run Script:
把一下代码粘贴进去(记得更改公司名等):
#appledoc Xcode script # Start constants company="xueshanfinancial"; companyID="com.xueshanfinancial"; companyURL="http://xueshanfinancial.com"; target="iphoneos"; #target="macosx"; outputPath="~/help"; # End constants /usr/local/bin/appledoc \ --project-name "${PROJECT_NAME}" \ --project-company "${company}" \ --company-id "${companyID}" \ --docset-atom-filename "${company}.atom" \ --docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \ --docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \ --docset-fallback-url "${companyURL}/${company}" \ --output "${outputPath}" \ --publish-docset \ --docset-platform-family "${target}" \ --logformat xcode \ --keep-intermediate-files \ --no-repeat-first-par \ --no-warn-invalid-crossref \ --exit-threshold 2 \ "${PROJECT_DIR}"
接下来就可以在工程成添加注释了--appledoc 支持以下注释。
/// 这是单行注释。 /** 这也是单行注释 */ /*! 同样是单行注释 */ /** 这也是单行注释, * 第二行会接上第一行。 */ /** 第一行是类的简介 在简介的下面,就是类的详细介绍了。 没有间隔换行会被消除,就像Html那样。 下面是常用的markdown语法 - - - 无序列表: (每行以 '*'、'-'、'+' 开头): * this is the first line * this is the second line * this is the third line 有序列表: (每行以 1.2.3、a.b.c 开头): a. this is the first line b. this is the secode line 多级列表: * this is the first line a. this is line a b. this is line b * this is the second line 1. this in line 1 2. this is line 2 标题: # This is an H1 ## This is an H2 ### This is an H3 #### This is an h4 ##### This is an h5 ###### This is an H6 链接: 普通URL直接写上,appledoc会自动翻译成链接: http:// blog.ibireme.com [这个](http://example.net/) 链接会隐藏实际URL. 表格: | header1 | header2 | header3 | |---------|:-------:|--------:| | normal | center | right | | cell | cell | cell | 引用: 这里会引用到方法 `someMethod:`,这里会引用到类 `YYColor` 这里会引用到一个代码块 void CMYK2RGB(float c, float m, float y, float k, float *r, float *g, float *b) { *r = (1 - c) * (1 - k); *g = (1 - m) * (1 - k); *b = (1 - y) * (1 - k); } @since iOS5.0 */ @interface AppledocExample : NSObject ///这里是属性的说明 @property (nonatomic, strong) NSString *name; /** @brief 这里是方法的简介。该Tag不能放到类注释里。 @exception UIColorException 这里是方法抛出异常的说明 @see YYColor @see someMethod: @warning 这里是警告,会显示成蓝色的框框 @bug 这里是bug,会显示成黄色的框框 @param red 这里是参数说明1 @param green 这里是参数说明2 @param blue 这里是参数说明3 @return 这里是返回值说明 */ - (UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue; - (void)someMethod:(NSString *)str; @end
查看文档:
在 docset-installed.txt 文件中,可以看到文档路径。显示包内容。~/Contents/Resources/Documents.
打开 index.html ,即可查看文档: