最近发现了这个功能，今晚看 WWDC 2013，在 What’s New in the LLVM Compiler 里也有特别提到。
这个功能是由最新的 LLVM 编译器支持的，简单来说就是编译器在编译代码的同时，会顺带分析你的注释，并把它附加到你的代码声明上（WWDC 视频是这么讲的，实践中发现并不需要编译就可以读取到注释，如果是我理解有误请指出。谢谢！）。
最新的 Xcode 5.0 内置的 LLVM 5.0 支持 Doxygen 和 HeaderDoc 两种强大的文档系统。 这也就就意味着如果你想把你写的注释显示在 Quick Help 中，那么你必须按照这两种文档系统的风格来写注释。
- HeaderDoc 是苹果制定和维护的文档系统，支持非常多的标签，在早期的 Xcode 版本中有内置快捷菜单，后移除。
- Doxygen 是大家比较熟悉的文档系统。有相当多的人在 Xcode 中都用它来制作文档。这篇文章主要讲这种风格的注释，也是我一直使用的风格。
Doxygen 一般分为两种风格：
- JavaDoc 型
1 2 3
/** * 多行注释.... */1
/// 单行注释- Headdoc 型
1 2 3
/*! * 多行注释.... */1
//! 单行注释
我常用的是 JavaDoc 型，分享一下我的注释习惯：
对于方法或带参 Block ：
1
2
3
4
5
6
7
8
9
10
/**
* 快速构建分享菜单。
*
* @param status 传入用户的timeline 的信息
* @param successBlock 分享成功回调
* @param errorBlock 分享失败回调
*
* @since 1.2.1
*/
+ (void)showWithStatus:(IBLStatus *)status success:(IBLShareSuccessBlock)successBlock failed:(IBLShareFailedBlock)errorBlock;
1
2
3
4
5
6
7
8
9
10
/**
* 获取群组标签个数
*
* @param group 当前用户群组，如果传 nil，则返回全部用户群组的标签个数。
*
* @return 标签个数
*
* @since 1.2.0
*/
+ (NSInteger)numberOfTagsWithGroup:(IBLGroup *)group;
1
2
3
4
5
6
7
8
9
/**
* 获取用户信息并处理
*
* @param result 回复标识，YES：获取成功，NO：获取失败
* @param userInfo 用户信息
*
* @since 1.2.1
*/
typedef void(^IBLGetUserInfoSuccessBlock)(BOOL result, id<ISSUserInfo> userInfo);
对于属性或变量：
1
2
/// 用户的状态, 0 表示不存用户信息; 1 表示已经存在用户信息
@property (nonatomic, copy) NSString *status;
如果你按照这样的风格对代码进行注释，那么如果在工程中任意调用此方法的地方按下 option 键并单击此方法，Xcode 5 会自动读取你的注释并在 Quick Help 面板中显示给调用者：
当然，你也可以按照其他的风格，例如下面这样：
1
2
3
4
5
6
7
8
/**
快速构建分享菜单。
\param status 传入用户的timeline 的信息
\param successBlock 分享成功回调
\param errorBlock 分享失败回调
\since 1.2.1
*/
+ (void)showWithStatus:(IBLStatus *)status success:(IBLShareSuccessBlock)successBlock failed:(IBLShareFailedBlock)errorBlock;
1
2
3
4
5
6
7
8
/// 快速构建分享菜单。
///
/// \param status 传入用户的timeline 的信息
/// \param successBlock 分享成功回调
/// \param errorBlock 分享失败回调
///
/// \since 1.2.1
+ (void)showWithStatus:(IBLStatus *)status success:(IBLShareSuccessBlock)successBlock failed:(IBLShareFailedBlock)errorBlock;
等等等。更多的风格可以点击两种文档系统的名称了解，选择你最喜欢的风格。只要你按照上面提到的两种文档所支持的风格来进行注释，Xcode 5 都可以解析并显示出来。
这个特性真的超棒，如果封装者按照规范写了注释，调用者轻而易举就能知道每个参数的意思，而不用再返回到方法的封装类去看了。
2018.09.21 更新：苹果在 Xcode 8 及之后的版本中已经内置了此功能，无需再安装插件。
如果你觉得格式太麻烦，我推荐你安装 VVDocumenter-Xcode 这个插件，它会根据你的代码自动提取变量生成 JavaDoc 型 的注释格式，你需要做的只是填写注释内容而已：
