iOS中这样写注释

欢迎到我的 个人博客 http://liumh.com 浏览此文

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

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

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

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

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

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

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

/**
 *  <#Description#>
 *
 *  @param manager <#manager description#>
 *  @param data    <#data description#>
 *
 *  @return <#return value description#>
 */
 - (BOOL)manager:(ACLAPIBaseManager *)manager isCorrectWithParamsData:(NSDictionary *)data;

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

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

参考:

Documentation