本文记录的是如何更好的编写注释。好的注释，可以让使用者能够像使用官方文档一样，使用 option + 单击 就可查看其使用说明。

对于枚举类型，可以像如下这样:

1
2
3
4
5
/** 定义的HTTP请求类型 */
typedef NS_ENUM(NSUInteger, ACLApiManagerRequestType) {
    ACLApiManagerRequestTypeGet,   /**< Get请求 */
    ACLApiManagerRequestTypePost,  /**< Post请求 */
};

请自行注意注释使用的符号, 注释枚举值和枚举类型时使用的符号也有差别。

对于属性，可以像如下这样:

1
@property (nonatomic, copy, readonly) NSString *errorMessage;  /**< 错误信息说明 */

对于方法的注释，强烈建议安装喵神的插件VVDocumenter-Xcode。然后在方法上部连续键入///触发插入注释，然后删除 placeholder 的地方，填入实际的注释说明，如下:

1
2
3
4
5
6
7
8
9
/**
 *  <#Description#>
 *
 *  @param manager <#manager description#>
 *  @param data    <#data description#>
 *
 *  @return <#return value description#>
 */
 - (BOOL)manager:(ACLAPIBaseManager *)manager isCorrectWithParamsData:(NSDictionary *)data;

但是对于没有参数的方法，或者我们觉得方法的命名自解释已经很清楚了，则可以像如下注释:

1
2
/** API 请求除 base url 之外的 url部分 */
- (NSString *)methodName;

使用 | 来引用注释中的变量名及符号名而不是使用引号。

这会避免二义性，尤其是当符号是一个常用词汇，这使用语句读起来很糟糕。例如，对于符号 count ：

// Sometimes we need |count| to be less than zero.

参考:

Documentation

目前已转行教育行业，欢迎加微信交流：CaryaLiu