增加注释

Author: longbai

QiniuSDK/Common/QNConfig.h

@@ -8,16 +8,37 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+ *    默认上传服务器
+ */
 extern NSString *const kQNUpHost;
 
+/**
+ *    备用上传服务器，当默认服务器网络连接失败时使用
+ */
 extern NSString *const kQNUpHostBackup;
 
+/**
+ *    断点上传时的分片大小
+ */
 extern const UInt32 kQNChunkSize;
 
+/**
+ *    断点上传时的分块大小
+ */
 extern const UInt32 kQNBlockSize;
 
+/**
+ *    上传失败的重试次数
+ */
 extern const UInt32 kQNRetryMax;
 
+/**
+ *    如果大于此值就使用断点上传，否则使用form上传
+ */
 extern const UInt32 kQNPutThreshold;
 
+/**
+ *    超时时间
+ */
 extern const float kQNTimeoutInterval;

QiniuSDK/Common/QNCrc32.h

@@ -8,10 +8,29 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+ *    生成crc32 校验码
+ */
 @interface QNCrc32 : NSObject
 
+/**
+ *    文件校验
+ *
+ *    @param filePath 文件路径
+ *    @param error    文件读取错误
+ *
+ *    @return 校验码
+ */
 + (UInt32)file:(NSString *)filePath
          error:(NSError **)error;
+
+/**
+ *    二进制字节校验
+ *
+ *    @param data 二进制数据
+ *
+ *    @return 校验码
+ */
 + (UInt32)data:(NSData *)data;
 
 @end

QiniuSDK/Common/QNEtag.h

@@ -8,8 +8,28 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+ *    服务器 hash etag 生成
+ */
 @interface QNEtag : NSObject
+
+/**
+ *    文件etag
+ *
+ *    @param filePath 文件路径
+ *    @param error    输出文件读取错误
+ *
+ *    @return etag
+ */
 + (NSString *)file:(NSString *)filePath
              error:(NSError **)error;
+
+/**
+ *    二进制数据etag
+ *
+ *    @param data 数据
+ *
+ *    @return etag
+ */
 + (NSString *)data:(NSData *)data;
 @end

QiniuSDK/Common/QNUrlSafeBase64.h

@@ -7,10 +7,27 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+ *    url safe base64 编码类, 对/ 做了处理
+ */
 @interface QNUrlSafeBase64 : NSObject
 
+/**
+ *    字符串编码
+ *
+ *    @param source 字符串
+ *
+ *    @return base64 字符串
+ */
 + (NSString *)encodeString:(NSString *)source;
 
+/**
+ *    二进制数据编码
+ *
+ *    @param source 二进制数据
+ *
+ *    @return base64字符串
+ */
 + (NSString *)encodeData:(NSData *)source;
 
 @end

QiniuSDK/Common/QNVersion.h

@@ -8,4 +8,7 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+ *    sdk 版本
+ */
 static const NSString *kQiniuVersion = @"7.0.6";

QiniuSDK/Http/QNResponseInfo.h

@@ -8,30 +8,115 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+ *    中途取消的状态码
+ */
 extern const int kQNRequestCancelled;
+
+/**
+ *    网络错误状态码
+ */
 extern const int kQNNetworkError;
+
+/**
+ *    错误参数状态码
+ */
 extern const int kQNInvalidArgument;
+
+/**
+ *    读取文件错误状态码
+ */
 extern const int kQNFileError;
 
+/**
+ *    上传完成后返回的状态信息
+ */
 @interface QNResponseInfo : NSObject
 
+/**
+ *    状态码
+ */
 @property (readonly) int statusCode;
+
+/**
+ *    七牛服务器生成的请求ID，用来跟踪请求信息，如果使用过程中出现问题，请反馈此ID
+ */
 @property (nonatomic, copy, readonly) NSString *reqId;
+
+/**
+ *    七牛服务器内部跟踪记录
+ */
 @property (nonatomic, copy, readonly) NSString *xlog;
+
+/**
+ *    错误信息，出错时请反馈此记录
+ */
 @property (nonatomic, copy, readonly) NSError *error;
+
+/**
+ *    是否取消
+ */
 @property (nonatomic, readonly, getter = isCancelled) BOOL canceled;
+
+/**
+ *    成功的请求
+ */
 @property (nonatomic, readonly, getter = isOK) BOOL ok;
+
+/**
+ *    是否网络错误
+ */
 @property (nonatomic, readonly, getter = isConnectionBroken) BOOL broken;
+
+/**
+ *    是否需要重试，内部使用
+ */
 @property (nonatomic, readonly) BOOL couldRetry;
 
+/**
+ *    工厂函数，内部使用
+ *
+ *    @return 取消的实例
+ */
 + (instancetype)cancel;
 
+/**
+ *    工厂函数，内部使用
+ *
+ *    @param desc 错误参数描述
+ *
+ *    @return 错误参数实例
+ */
 + (instancetype)responseInfoWithInvalidArgument:(NSString *)desc;
 
+/**
+ *    工厂函数，内部使用
+ *
+ *    @param error 错误信息
+ *
+ *    @return 网络错误实例
+ */
 + (instancetype)responseInfoWithNetError:(NSError *)error;
 
+/**
+ *    工厂函数，内部使用
+ *
+ *    @param error 错误信息
+ *
+ *    @return 文件错误实例
+ */
 + (instancetype)responseInfoWithFileError:(NSError *)error;
 
+/**
+ *    构造函数
+ *
+ *    @param status 状态码
+ *    @param reqId  七牛服务器请求id
+ *    @param xlog   七牛服务器记录
+ *    @param body   服务器返回内容
+ *
+ *    @return 实例
+ */
 - (instancetype)init:(int)status
            withReqId:(NSString *)reqId
             withXLog:(NSString *)xlog

QiniuSDK/Http/QNUserAgent.h

@@ -8,4 +8,9 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+ *    UserAgent 生成函数
+ *
+ *    @return UserAgent 字串
+ */
 NSString *QNUserAgent(void);

QiniuSDK/Recorder/QNFileRecorder.h

@@ -9,15 +9,42 @@
 #import <Foundation/Foundation.h>
 #import "QNRecorderDelegate.h"
 
+/**
+ *    将上传记录保存到文件系统中
+ */
 @interface QNFileRecorder : NSObject <QNRecorderDelegate>
 
+/**
+ *    用指定保存的目录进行初始化
+ *
+ *    @param directory 目录
+ *    @param error     输出的错误信息
+ *
+ *    @return 实例
+ */
 + (instancetype)fileRecorderWithFolder:(NSString *)directory
                                  error:(NSError *__autoreleasing *)error;
 
+/**
+ *    用指定保存的目录，以及是否进行base64编码进行初始化，
+ *
+ *    @param directory 目录
+ *    @param encode    为避免因为特殊字符或含有/，无法保存持久化记录，故用此参数指定是否要base64编码
+ *    @param error     输出错误信息
+ *
+ *    @return 实例
+ */
 + (instancetype)fileRecorderWithFolder:(NSString *)directory
                              encodeKey:(BOOL)encode
                                  error:(NSError *__autoreleasing *)error;
 
+/**
+ *    从外部手动删除记录，如无特殊需求，不建议使用
+ *
+ *    @param key    持久化记录key
+ *    @param dir    目录
+ *    @param encode 是否encode
+ */
 + (void)removeKey:(NSString *)key
         directory:(NSString *)dir
         encodeKey:(BOOL)encode;

QiniuSDK/Recorder/QNRecorderDelegate.h

@@ -8,13 +8,38 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+ *    持久化记录接口，可以实现将记录持久化到文件，数据库等
+ */
 @protocol QNRecorderDelegate <NSObject>
 
+/**
+ *    保存记录
+ *
+ *    @param key   持久化记录的key
+ *    @param value 持久化记录上传状态信息
+ *
+ *    @return 错误信息，成功为nil
+ */
 - (NSError *)set:(NSString *)key
             data:(NSData *)value;
 
+/**
+ *    取出保存的持久化上传状态信息
+ *
+ *    @param key 持久化记录key
+ *
+ *    @return 上传中间状态信息
+ */
 - (NSData *)get:(NSString *)key;
 
+/**
+ *    删除持久化记录，一般在上传成功后自动调用
+ *
+ *    @param key 持久化记录key
+ *
+ *    @return 错误信息，成功为nil
+ */
 - (NSError *)del:(NSString *)key;
 
 @end