本文记录的是如何更好的编写注释。好的注释,可以让使用者能够像使用官方文档一样,使用 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


如果觉得本文对你有帮助,就请用微信随意打赏我吧^_^