参考资料1
参考资料2
从stackoverflow上找到三个比较
popular
的工具：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/
介绍
docxygen
docxygen感觉是这3个工具中支持语言最多的，可以配置的地方也比较多。我大概看了一下文档，觉得还是比较复杂，而且默认生成的风格与苹果的风格不一致。就去看后面2个工具的介绍了。另外，它虽然是开源软件，但是没有将源码放到github上让我感觉这个工具的开发活跃度是不是不够。
headerdoc
headerdoc是xcode 自带的文档生成工具。在安装完xcode后，就可以用命令行：headdoc2html + 源文件名 来生成对应的文档。我个人试用了一下，还是比较方便的，不过headerdoc的注释生成规则比较特别，只生成以
的格式的注释。还有一个缺点是每个类文件对应一个注释文件，没有汇总的文件，这点感觉有点不爽。
appledoc
appledoc是在stackoverflow上被大家推荐的一个注释工具。有几个原因造成我比较喜欢它：
它默认生成的文档风格和苹果的官方文档是一致的，而doxygen需要另外配置。
appledoc就是用objective-c生成的，必要的时候调试和改动也比较方便。
可以生成docset，并且集成到xcode中。这一点是很赞的，相当于在源码中按住option再单击就可以调出相应方法的帮助。
appledoc源码在github上，而doxygen在svn上。我个人比较偏激地认为比较活跃的开源项目都应该在github上。
相对于headerdoc，它没有特殊的注释要求，可以用
的格式，也可以兼容
的格式的注释，并且生成的注释有汇总页面。
安装
那么简单介绍一下如何安装appledoc，安装非常简单，只需要2步：
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh
其他方法：
brew install appledoc
自己编译：去Github把工程clone下来，用Xcode打开，然后随便搞。。
安装完成后，验证一下OK了没:
appledoc –version
使用
使用appledoc时，只需要用如下命令即可：
appledoc会扫描当前路径下的所有文件，然后生成好文档放到doc目录下。
如果想要详细的参数，可以查看帮助
如果想要集成进Xcode工程:
1.选中你的工程,点击Add Target按钮,选择 Other -> Aggregate模板新建.
2.点击Add Build Phase按钮,添加一个Run Script.
3.把下面的模板代码复制进去,把前几行参数改成你自己的.
4.在Xcode左上角选择这个新建的Target,然后点击build.
5.文档就会编译好并且自动安装进Xcode了(重启Xcode生效).
#appledoc Xcode script
# Start constants
company="ACME";
companyID="com.ACME";
companyURL="http://ACME.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 \
"${PROJECT_DIR}"
语法
appledoc官方原来是有一篇语法的，但是现在貌似维护中了。。所以这里尽量多介绍一下。
首先，文档中的注释只有符合规范，才能被appledoc认可。
凡是以
"///"
、
"/**"
或
"/*!"
开头的注释块，都算所appledoc注释。下面是示例:
/// 这是单行注释。
/** 这也是单行注释 */
/*! 同样是单行注释 */
/** 这也是单行注释，
* 第二行会接上第一行。
*/
注释块中，每一行开头的空格和”*”字符多数情况都会被appledoc忽略。
连续的两行(即没有间隔空行)的注释，将被合并成一个段落，并忽略换行，就像html。
在注释块内，appledoc支持如下语法：Markdown、HTML、HeaderDoc Tags。
Markdown的语法在这里有介绍(中文翻译)，用Github的童鞋应该很熟悉。OSX上可以用Mou实时查看效果，Chrome也有一个插件来实时查看效果。这个东西可以说一看就会，学习成本很低。Markdown有很多方言，而且appledoc支持的也不算完整。所以用的时候可以试着在appledoc编译一下看看效果。
HTML这个就不用说了，支持Markdown肯定也支持HTML。。如果想要把控住更多细节，那就直接码Html吧。
HeaderDoc Tags这个东西是苹果的HeaderDoc工具的语法。详情可以见官网文档。例如@param、@return、@warning这样的东西，appledoc会进行解释。当然appledoc对这个东西的支持也不算完整 :?: 所以用的时候也要尝试一下。
通常情况下，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 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
编译出的效果是这样：
appledoc还有很多不太完善的地方，比如C方法和宏定义上面的注释就不被识别，URL链接有时会识别错误等。。这时候只能手动修改生成好的html了；或者比较勤快自己手动fork一个appledoc改一下。。
其他
编译出的Docset默认会放在
/Users/ibireme/Library/Developer/Shared/Documentation/DocSets
路径下。
Docset格式，实际上是一个bundle,里面包含了一些xml和html。显示包内容后就可以查看和修改了。如果需要放到网站上，那单独将html部分取出来就行。
Docset安装后，在Xcode中就可以实时查看某个方法的说明了，体验和官方文档保持一致。（有一点，category中的注释不会出现在xcode的快速帮助中，不知道新版xcode是否会有改进..）