Vincent Sit

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

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

最近发现了这个功能,今晚看 WWDC 2013,在 What’s New in the LLVM Compiler 里也有特别提到。

这个功能是由最新的 LLVM 编译器支持的,简单来说就是编译器在编译代码的同时,会顺带分析你的注释,并把它附加到你的代码声明上(WWDC 视频是这么讲的,实践中发现并不需要编译就可以读取到注释,如果是我理解有误请指出。谢谢!)。

最新的 Xcode 5.0 内置的 LLVM 5.0 支持 DoxygenHeaderDoc 两种强大的文档系统。
这也就就意味着如果你想把你写的注释显示在 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 型 的注释格式,你需要做的只是填写注释内容而已:

作者

Vincent Sit

查看评论
下一篇

iOS 开发实践之 Auto Layout

上一篇

iOS 应用如何检测用户截屏