Xcode 5 自动读取注释增强 Quick Help

本文为迁移文章，原发布时间为 2013-10-26 14:38:00

最近发现了这个功能，今晚看 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 型

  /**   
   *  多行注释....
   */
  

  /// 单行注释
  

  • Headdoc 型

  /*!
   *  多行注释....
   */
  

  //! 单行注释
  

我常用的是 JavaDoc 型，分享一下我的注释习惯：

对于方法或带参 Block ：

/**
 *  快速构建分享菜单。
 *
 *  @param status       传入用户的timeline 的信息
 *  @param successBlock 分享成功回调
 *  @param errorBlock   分享失败回调
 *
 *  @since 1.2.1
 */
+ (void)showWithStatus:(IBLStatus *)status success:(IBLShareSuccessBlock)successBlock failed:(IBLShareFailedBlock)errorBlock;

/**
 *  获取群组标签个数
 *
 *  @param group 当前用户群组，如果传 nil，则返回全部用户群组的标签个数。
 *
 *  @return 标签个数
 *
 *  @since 1.2.0
 */
+ (NSInteger)numberOfTagsWithGroup:(IBLGroup *)group;

/**
 *  获取用户信息并处理
 *
 *  @param  result      回复标识，YES：获取成功，NO：获取失败
 *  @param  userInfo    用户信息
 *
 *  @since 1.2.1
 */
typedef void(^IBLGetUserInfoSuccessBlock)(BOOL result, id<ISSUserInfo> userInfo);

对于属性或变量：

/// 用户的状态, 0 表示不存用户信息; 1 表示已经存在用户信息
@property (nonatomic, copy) NSString *status;

如果你按照这样的风格对代码进行注释，那么如果在工程中任意调用此方法的地方按下 option 键并单击此方法，Xcode 5 会自动读取你的注释并在 Quick Help 面板中显示给调用者：

当然，你也可以按照其他的风格，例如下面这样：

/**
  快速构建分享菜单。     
  param status       传入用户的timeline 的信息
  param successBlock 分享成功回调
  param errorBlock   分享失败回调     
  since 1.2.1
 */
+ (void)showWithStatus:(IBLStatus *)status success:(IBLShareSuccessBlock)successBlock   failed:(IBLShareFailedBlock)errorBlock;

///  快速构建分享菜单。
///
///  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 型 的注释格式，你需要做的只是填写注释内容而已：