使用appledoc自动生成api文档

AppleDoc可以根据项目中的注释自动生成类似于Apple官方文档的文档文件.

安装 appledoc

git clone git://github.com/tomaz/appledoc.git
cd ./appledoc
sudo sh install-appledoc.sh

如果出现 INSTALL SUCCEEDED 则说明我们安装成功了。

使用方法

进入工程主目录,执行

appledoc  --project-name "Your Project Name"  --company-id "com.yourcommpany"  --project-company "Your Company"  ./

这里省略了可以不添加的参数.如果有需要可以自己添加. 执行完成会在当前目录下生成一个docset-installed.txt的文件.这里是生成的docset存放地址.

集成到Xcode

新建一个target,类型为other中的Aggregate,将脚本添加到此target中,需要生成文档时,选择此target.平时build时不执行脚本.

也可以在当前的工程project下,打开build phrase,在Run Script下添加脚本.这样在bulid当前工程时就会执行脚本.

#appledoc Xcode script
# Start constants
company="abc";
companyID="com.abc";
companyURL="http://abc.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}"

或者直接添加刚才在终端输入的命令也是可以的.

这样在build的时候,xcode会自动执行脚本,生成新的文档.

支持注释格式

/// 这是单行注释。

/** 这也是单行注释 */

/*! 同样是单行注释 */

/** 这也是单行注释，

* 第二行会接上第一行。

*/

/** 第一行是类的简介

在简介的下面,就是类的详细介绍了。

没有间隔换行会被消除，就像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 linea

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

经常使用的标签：

@brief : 使用它来写一段你正在文档化的method, PRoperty, class, file, struct, 或enum的短描述信息。
@discusstion: 用它来写一段详尽的描述。如果需要你可以添加换行。
@param:通过它你可以描述一个 method 或 function的参数信息。你可以使用多个这种标签。
@return: 用它来制定一个 method 或 function的返回值。
@see: 用它来指明其他相关的 method 或 function。你可以使用多个这种标签。
@sa:同上
@code ： 使用这个标签，你可以在文档当中嵌入代码段。当在Help Inspector当中查看文档时，代码通过在一个特别的盒子中用一种不同的字体来展示。始终记住在写的代码结尾处使用@endcode标签。
@remark : 在写文档时，用它来强调任何关于代码的特殊之处。

注意: 不管是直接使用终端还是集成到xcode,AppleDoc 使用的时候如果项目中有pod第三方的会报错。无法生成 docset-installed.txt和文档。 此时此时你可以 cd 到你项目的代码文件夹，再去执行脚本.

结果出现

Generation step 4/4 failed: GBDocSetInstallGenerator failed generating output, aborting! Documentation set was installed, but couldn't reload documentation within Xcode. Expected end of line but found identifier.

并且生成 docset-installed.txt和文档.