项目管理之 使用 appledoc 生成开发文档

　　写项目时通常会遇到要求写开发文档的需求，但是就源代码来说，文档最好和源码在一起，这样更新起来更加方便和顺手。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 上被大家推荐的一个注释工具。有以下优点：

1. 它默认生成的文档风格和苹果的官方文档是一致的，而 doxygen 需要另外配置。
2. appledoc 就是用 objective-c 生成的，必要的时候调试和改动也比较方便。
3. 可以生成 docset，并且集成到 Xcode 中。这一点是很赞的，相当于在源码中按住 option 再单击就可以调出相应方法的帮助。
4. appledoc 源码在 github 上，而 doxygen 在 svn 上。我个人比较偏激地认为比较活跃的开源项目都应该在 github 上。
5. 相对于 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 ,即可查看文档：