Merge pull request #2722 from dreampiggy/documentation_page_update

Update the documentation coverage for jazzy. Use the correct format to provide class/protocol/type API Documentation

SDWebImage/NSButton+WebCache.h

@@ -12,6 +12,9 @@
 
 #import "SDWebImageManager.h"
 
+/**
+ * Integrates SDWebImage async downloading and caching of remote images with NSButton.
+ */
 @interface NSButton (WebCache)
 
 #pragma mark - Image

SDWebImage/NSData+ImageContentType.h

@@ -24,6 +24,9 @@ static const SDImageFormat SDImageFormatWebP      = 4;
 static const SDImageFormat SDImageFormatHEIC      = 5;
 static const SDImageFormat SDImageFormatHEIF      = 6;
 
+/**
+ NSData category about the image content type and UTI.
+ */
 @interface NSData (ImageContentType)
 
 /**

SDWebImage/NSImage+Compatibility.h

@@ -8,10 +8,11 @@
 
 #import "SDWebImageCompat.h"
 
-// This category is provided to easily write cross-platform(AppKit/UIKit) code. For common usage, see `UIImage+Metadata.h`.
-
 #if SD_MAC
 
+/**
+ This category is provided to easily write cross-platform(AppKit/UIKit) code. For common usage, see `UIImage+Metadata.h`.
+ */
 @interface NSImage (Compatibility)
 
 /**

SDWebImage/SDAnimatedImage.h

@@ -59,6 +59,9 @@
 
 @end
 
+/**
+ The image class which supports animating on `SDAnimatedImageView`. You can also use it on normal UIImageView/NSImageView.
+ */
 @interface SDAnimatedImage : UIImage <SDAnimatedImage>
 
 // This class override these methods from UIImage(NSImage), and it supports NSSecureCoding.

SDWebImage/SDAnimatedImageRep.h

@@ -10,10 +10,11 @@
 
 #if SD_MAC
 
-// A subclass of `NSBitmapImageRep` to fix that GIF loop count issue because `NSBitmapImageRep` will reset `NSImageCurrentFrameDuration` by using `kCGImagePropertyGIFDelayTime` but not `kCGImagePropertyGIFUnclampedDelayTime`.
-// Built in GIF coder use this instead of `NSBitmapImageRep` for better GIF rendering. If you do not want this, only enable `SDImageIOCoder`, which just call `NSImage` API and actually use `NSBitmapImageRep` for GIF image.
-// This also support APNG format using `SDImageAPNGCoder`. Which provide full alpha-channel support and the correct duration match the `kCGImagePropertyAPNGUnclampedDelayTime`.
-
+/**
+ A subclass of `NSBitmapImageRep` to fix that GIF loop count issue because `NSBitmapImageRep` will reset `NSImageCurrentFrameDuration` by using `kCGImagePropertyGIFDelayTime` but not `kCGImagePropertyGIFUnclampedDelayTime`.
+ Built in GIF coder use this instead of `NSBitmapImageRep` for better GIF rendering. If you do not want this, only enable `SDImageIOCoder`, which just call `NSImage` API and actually use `NSBitmapImageRep` for GIF image.
+ This also support APNG format using `SDImageAPNGCoder`. Which provide full alpha-channel support and the correct duration match the `kCGImagePropertyAPNGUnclampedDelayTime`.
+ */
 @interface SDAnimatedImageRep : NSBitmapImageRep
 
 @end

SDWebImage/SDAnimatedImageView+WebCache.h

@@ -12,6 +12,9 @@
 
 #import "SDWebImageManager.h"
 
+/**
+ Integrates SDWebImage async downloading and caching of remote images with SDAnimatedImageView.
+ */
 @interface SDAnimatedImageView (WebCache)
 
 /**

SDWebImage/SDDiskCache.h

@@ -9,7 +9,9 @@
 #import "SDWebImageCompat.h"
 
 @class SDImageCacheConfig;
-// A protocol to allow custom disk cache used in SDImageCache.
+/**
+ A protocol to allow custom disk cache used in SDImageCache.
+ */
 @protocol SDDiskCache <NSObject>
 
 // All of these method are called from the same global queue to avoid blocking on main queue and thread-safe problem. But it's also recommend to ensure thread-safe yourself using lock or other ways.
@@ -97,9 +99,13 @@
 
 @end
 
-// The built-in disk cache
+/**
+ The built-in disk cache.
+ */
 @interface SDDiskCache : NSObject <SDDiskCache>
-
+/**
+ Cache Config object - storing all kind of settings.
+ */
 @property (nonatomic, strong, readonly, nonnull) SDImageCacheConfig *config;
 
 - (nonnull instancetype)init NS_UNAVAILABLE;

SDWebImage/SDImageCache.h

@@ -12,6 +12,7 @@
 #import "SDImageCacheConfig.h"
 #import "SDImageCacheDefine.h"
 
+/// Image Cache Options
 typedef NS_OPTIONS(NSUInteger, SDImageCacheOptions) {
     /**
      * By default, we do not query image data when the image is already cached in memory. This mask can force to query image data at the same time. However, this query is asynchronously unless you specify `SDImageCacheQueryMemoryDataSync`

SDWebImage/SDImageCacheConfig.h

@@ -9,6 +9,7 @@
 #import <Foundation/Foundation.h>
 #import "SDWebImageCompat.h"
 
+/// Image Cache Expire Type
 typedef NS_ENUM(NSUInteger, SDImageCacheConfigExpireType) {
     /**
      * When the image is accessed it will update this value
@@ -20,7 +21,10 @@ typedef NS_ENUM(NSUInteger, SDImageCacheConfigExpireType) {
     SDImageCacheConfigExpireTypeModificationDate
 };
 
-// This class conform to NSCopying, make sure to add the property in `copyWithZone:` as well.
+/**
+ The class contains all the config for image cache
+ @note This class conform to NSCopying, make sure to add the property in `copyWithZone:` as well.
+ */
 @interface SDImageCacheConfig : NSObject <NSCopying>
 
 /**

SDWebImage/SDImageCacheDefine.h

@@ -11,6 +11,7 @@
 #import "SDWebImageOperation.h"
 #import "SDWebImageDefine.h"
 
+/// Image Cache Type
 typedef NS_ENUM(NSInteger, SDImageCacheType) {
     /**
      * For query and contains op in response, means the image isn't available in the image cache

SDWebImage/SDImageCachesManager.h

@@ -9,6 +9,7 @@
 #import <Foundation/Foundation.h>
 #import "SDImageCacheDefine.h"
 
+/// Policy for cache operation
 typedef NS_ENUM(NSUInteger, SDImageCachesManagerOperationPolicy) {
     SDImageCachesManagerOperationPolicySerial, // process all caches serially (from the highest priority to the lowest priority cache by order)
     SDImageCachesManagerOperationPolicyConcurrent, // process all caches concurrently
@@ -16,6 +17,9 @@ typedef NS_ENUM(NSUInteger, SDImageCachesManagerOperationPolicy) {
     SDImageCachesManagerOperationPolicyLowestOnly // process the lowest priority cache only
 };
 
+/**
+ A caches manager to manage multiple caches.
+ */
 @interface SDImageCachesManager : NSObject <SDImageCache>
 
 /**

SDWebImage/SDImageCoderHelper.h

@@ -10,6 +10,9 @@
 #import "SDWebImageCompat.h"
 #import "SDImageFrame.h"
 
+/**
+ Provide some common helper methods for building the image decoder/encoder.
+ */
 @interface SDImageCoderHelper : NSObject
 
 /**

SDWebImage/SDImageFrame.h

@@ -9,10 +9,12 @@
 #import <Foundation/Foundation.h>
 #import "SDWebImageCompat.h"
 
+/**
+ This class is used for creating animated images via `animatedImageWithFrames` in `SDImageCoderHelper`.
+ @note If you need to specify animated images loop count, use `sd_imageLoopCount` property in `UIImage+Metadata.h`.
+ */
 @interface SDImageFrame : NSObject
 
-// This class is used for creating animated images via `animatedImageWithFrames` in `SDImageCoderHelper`. Attention if you need to specify animated images loop count, use `sd_imageLoopCount` property in `UIImage+Metadata.h`.
-
 /**
  The image of current frame. You should not set an animated image.
  */

SDWebImage/SDImageGraphics.h

@@ -14,8 +14,14 @@
  For UIKit, these methods just call the same method in `UIGraphics.h`. See the documentation for usage.
  For AppKit, these methods use `NSGraphicsContext` to create image context and match the behavior like UIKit.
  */
+
+/// Returns the current graphics context.
 FOUNDATION_EXPORT CGContextRef __nullable SDGraphicsGetCurrentContext(void) CF_RETURNS_NOT_RETAINED;
+/// Creates a bitmap-based graphics context and makes it the current context.
 FOUNDATION_EXPORT void SDGraphicsBeginImageContext(CGSize size);
+/// Creates a bitmap-based graphics context with the specified options.
 FOUNDATION_EXPORT void SDGraphicsBeginImageContextWithOptions(CGSize size, BOOL opaque, CGFloat scale);
+/// Removes the current bitmap-based graphics context from the top of the stack.
 FOUNDATION_EXPORT void SDGraphicsEndImageContext(void);
+/// Returns an image based on the contents of the current bitmap-based graphics context.
 FOUNDATION_EXPORT UIImage * __nullable SDGraphicsGetImageFromCurrentImageContext(void);

SDWebImage/SDImageLoader.h

@@ -52,11 +52,12 @@ FOUNDATION_EXPORT UIImage * _Nullable SDImageLoaderDecodeProgressiveImageData(NS
 
 #pragma mark - SDImageLoader
 
-// This is the protocol to specify custom image load process. You can create your own class to conform this protocol and use as a image loader to load image from network or any avaiable remote resources defined by yourself.
-// If you want to implement custom loader for image download from network or local file, you just need to concentrate on image data download only. After the download finish, call `SDImageLoaderDecodeImageData` or `SDImageLoaderDecodeProgressiveImageData` to use the built-in decoding process and produce image (Remember to call in the global queue). And finally callback the completion block.
-// If you directlly get the image instance using some third-party SDKs, such as image directlly from Photos framework. You can process the image data and image instance by yourself without that built-in decoding process. And finally callback the completion block.
-// @note It's your responsibility to load the image in the desired global queue(to avoid block main queue). We do not dispatch these method call in a global queue but just from the call queue (For `SDWebImageManager`, it typically call from the main queue).
-
+/**
+ This is the protocol to specify custom image load process. You can create your own class to conform this protocol and use as a image loader to load image from network or any avaiable remote resources defined by yourself.
+ If you want to implement custom loader for image download from network or local file, you just need to concentrate on image data download only. After the download finish, call `SDImageLoaderDecodeImageData` or `SDImageLoaderDecodeProgressiveImageData` to use the built-in decoding process and produce image (Remember to call in the global queue). And finally callback the completion block.
+ If you directlly get the image instance using some third-party SDKs, such as image directlly from Photos framework. You can process the image data and image instance by yourself without that built-in decoding process. And finally callback the completion block.
+ @note It's your responsibility to load the image in the desired global queue(to avoid block main queue). We do not dispatch these method call in a global queue but just from the call queue (For `SDWebImageManager`, it typically call from the main queue).
+*/
 @protocol SDImageLoader <NSObject>
 
 /**

SDWebImage/SDImageLoadersManager.h

@@ -8,6 +8,9 @@
 
 #import "SDImageLoader.h"
 
+/**
+ A loaders manager to manage multiple loaders
+ */
 @interface SDImageLoadersManager : NSObject <SDImageLoader>
 
 /**

SDWebImage/SDImageTransformer.h

@@ -47,10 +47,15 @@ FOUNDATION_EXPORT NSString * _Nullable SDTransformedKeyForKey(NSString * _Nullab
 
 #pragma mark - Pipeline
 
-// Pipeline transformer. Which you can bind multiple transformers together to let the image to be transformed one by one in order and generate the final image.
-// Because transformers are lightweight, if you want to append or arrange transfomers, create another pipeline transformer instead. This class is considered as immutable.
+/**
+ Pipeline transformer. Which you can bind multiple transformers together to let the image to be transformed one by one in order and generate the final image.
+ @note Because transformers are lightweight, if you want to append or arrange transfomers, create another pipeline transformer instead. This class is considered as immutable.
+ */
 @interface SDImagePipelineTransformer : NSObject <SDImageTransformer>
 
+/**
+ All transformers in pipeline
+ */
 @property (nonatomic, copy, readonly, nonnull) NSArray<id<SDImageTransformer>> *transformers;
 
 - (nonnull instancetype)init NS_UNAVAILABLE;
@@ -62,12 +67,35 @@ FOUNDATION_EXPORT NSString * _Nullable SDTransformedKeyForKey(NSString * _Nullab
 // Because transformers are lightweight, these class are considered as immutable.
 #pragma mark - Image Geometry
 
-// Image round corner transformer
+/**
+ Image round corner transformer
+ */
 @interface SDImageRoundCornerTransformer: NSObject <SDImageTransformer>
 
+/**
+ The radius of each corner oval. Values larger than half the
+ rectangle's width or height are clamped appropriately to
+ half the width or height.
+ */
 @property (nonatomic, assign, readonly) CGFloat cornerRadius;
+
+/**
+ A bitmask value that identifies the corners that you want
+ rounded. You can use this parameter to round only a subset
+ of the corners of the rectangle.
+ */
 @property (nonatomic, assign, readonly) SDRectCorner corners;
+
+/**
+ The inset border line width. Values larger than half the rectangle's
+ width or height are clamped appropriately to half the width
+ or height.
+ */
 @property (nonatomic, assign, readonly) CGFloat borderWidth;
+
+/**
+ The border stroke color. nil means clear color.
+ */
 @property (nonatomic, strong, readonly, nullable) UIColor *borderColor;
 
 - (nonnull instancetype)init NS_UNAVAILABLE;
@@ -75,10 +103,19 @@ FOUNDATION_EXPORT NSString * _Nullable SDTransformedKeyForKey(NSString * _Nullab
 
 @end
 
-// Image resizing transformer
+/**
+ Image resizing transformer
+ */
 @interface SDImageResizingTransformer : NSObject <SDImageTransformer>
 
+/**
+ The new size to be resized, values should be positive.
+ */
 @property (nonatomic, assign, readonly) CGSize size;
+
+/**
+ The scale mode for image content.
+ */
 @property (nonatomic, assign, readonly) SDImageScaleMode scaleMode;
 
 - (nonnull instancetype)init NS_UNAVAILABLE;
@@ -86,9 +123,14 @@ FOUNDATION_EXPORT NSString * _Nullable SDTransformedKeyForKey(NSString * _Nullab
 
 @end
 
-// Image cropping transformer
+/**
+ Image cropping transformer
+ */
 @interface SDImageCroppingTransformer : NSObject <SDImageTransformer>
 
+/**
+ Image's inner rect.
+ */
 @property (nonatomic, assign, readonly) CGRect rect;
 
 - (nonnull instancetype)init NS_UNAVAILABLE;
@@ -96,10 +138,19 @@ FOUNDATION_EXPORT NSString * _Nullable SDTransformedKeyForKey(NSString * _Nullab
 
 @end
 
-// Image flipping transformer
+/**
+ Image flipping transformer
+ */
 @interface SDImageFlippingTransformer : NSObject <SDImageTransformer>
 
+/**
+ YES to flip the image horizontally. ⇋
+ */
 @property (nonatomic, assign, readonly) BOOL horizontal;
+
+/**
+ YES to flip the image vertically. ⥯
+ */
 @property (nonatomic, assign, readonly) BOOL vertical;
 
 - (nonnull instancetype)init NS_UNAVAILABLE;
@@ -107,10 +158,20 @@ FOUNDATION_EXPORT NSString * _Nullable SDTransformedKeyForKey(NSString * _Nullab
 
 @end
 
-// Image rotation transformer
+/**
+ Image rotation transformer
+ */
 @interface SDImageRotationTransformer : NSObject <SDImageTransformer>
 
+/**
+ Rotated radians in counterclockwise.⟲
+ */
 @property (nonatomic, assign, readonly) CGFloat angle;
+
+/**
+ YES: new image's size is extend to fit all content.
+ NO: image's size will not change, content may be clipped.
+ */
 @property (nonatomic, assign, readonly) BOOL fitSize;
 
 - (nonnull instancetype)init NS_UNAVAILABLE;
@@ -120,9 +181,14 @@ FOUNDATION_EXPORT NSString * _Nullable SDTransformedKeyForKey(NSString * _Nullab
 
 #pragma mark - Image Blending
 
-// Image tint color transformer
+/**
+ Image tint color transformer
+ */
 @interface SDImageTintTransformer : NSObject <SDImageTransformer>
 
+/**
+ The tint color.
+ */
 @property (nonatomic, strong, readonly, nonnull) UIColor *tintColor;
 
 - (nonnull instancetype)init NS_UNAVAILABLE;
@@ -132,9 +198,14 @@ FOUNDATION_EXPORT NSString * _Nullable SDTransformedKeyForKey(NSString * _Nullab
 
 #pragma mark - Image Effect
 
-// Image blur effect transformer
+/**
+ Image blur effect transformer
+ */
 @interface SDImageBlurTransformer : NSObject <SDImageTransformer>
 
+/**
+ The radius of the blur in points, 0 means no blur effect.
+ */
 @property (nonatomic, assign, readonly) CGFloat blurRadius;
 
 - (nonnull instancetype)init NS_UNAVAILABLE;
@@ -143,9 +214,14 @@ FOUNDATION_EXPORT NSString * _Nullable SDTransformedKeyForKey(NSString * _Nullab
 @end
 
 #if SD_UIKIT || SD_MAC
-// Core Image filter transformer
+/**
+ Core Image filter transformer
+ */
 @interface SDImageFilterTransformer: NSObject <SDImageTransformer>
 
+/**
+ The CIFilter to be applied to the image.
+ */
 @property (nonatomic, strong, readonly, nonnull) CIFilter *filter;
 
 - (nonnull instancetype)init NS_UNAVAILABLE;

SDWebImage/SDMemoryCache.h

@@ -9,7 +9,9 @@
 #import "SDWebImageCompat.h"
 
 @class SDImageCacheConfig;
-// A protocol to allow custom memory cache used in SDImageCache.
+/**
+ A protocol to allow custom memory cache used in SDImageCache.
+ */
 @protocol SDMemoryCache <NSObject>
 
 @required
@@ -65,7 +67,9 @@
 
 @end
 
-// A memory cache which auto purge the cache on memory warning and support weak cache.
+/**
+ A memory cache which auto purge the cache on memory warning and support weak cache.
+ */
 @interface SDMemoryCache <KeyType, ObjectType> : NSCache <KeyType, ObjectType> <SDMemoryCache>
 
 @property (nonatomic, strong, nonnull, readonly) SDImageCacheConfig *config;

SDWebImage/SDWebImageCacheKeyFilter.h

@@ -11,13 +11,19 @@
 
 typedef NSString * _Nullable(^SDWebImageCacheKeyFilterBlock)(NSURL * _Nonnull url);
 
-// This is the protocol for cache key filter. We can use a block to specify the cache key filter. But Using protocol can make this extensible, and allow Swift user to use it easily instead of using `@convention(block)` to store a block into context options.
+/**
+ This is the protocol for cache key filter.
+ We can use a block to specify the cache key filter. But Using protocol can make this extensible, and allow Swift user to use it easily instead of using `@convention(block)` to store a block into context options.
+ */
 @protocol SDWebImageCacheKeyFilter <NSObject>
 
 - (nullable NSString *)cacheKeyForURL:(nonnull NSURL *)url;
 
 @end
 
+/**
+ A cache key filter class with block.
+ */
 @interface SDWebImageCacheKeyFilter : NSObject <SDWebImageCacheKeyFilter>
 
 - (nonnull instancetype)initWithBlock:(nonnull SDWebImageCacheKeyFilterBlock)block;

SDWebImage/SDWebImageCacheSerializer.h

@@ -11,13 +11,19 @@
 
 typedef NSData * _Nullable(^SDWebImageCacheSerializerBlock)(UIImage * _Nonnull image, NSData * _Nullable data, NSURL * _Nullable imageURL);
 
-// This is the protocol for cache serializer. We can use a block to specify the cache serializer. But Using protocol can make this extensible, and allow Swift user to use it easily instead of using `@convention(block)` to store a block into context options.
+/**
+ This is the protocol for cache serializer.
+ We can use a block to specify the cache serializer. But Using protocol can make this extensible, and allow Swift user to use it easily instead of using `@convention(block)` to store a block into context options.
+ */
 @protocol SDWebImageCacheSerializer <NSObject>
 
 - (nullable NSData *)cacheDataWithImage:(nonnull UIImage *)image originalData:(nullable NSData *)data imageURL:(nullable NSURL *)imageURL;
 
 @end
 
+/**
+ A cache serializer class with block.
+ */
 @interface SDWebImageCacheSerializer : NSObject <SDWebImageCacheSerializer>
 
 - (nonnull instancetype)initWithBlock:(nonnull SDWebImageCacheSerializerBlock)block;

SDWebImage/SDWebImageDefine.h

@@ -48,6 +48,7 @@ FOUNDATION_EXPORT UIImage * _Nullable SDScaledImageForScaleFactor(CGFloat scale,
 
 #pragma mark - WebCache Options
 
+/// WebCache options
 typedef NS_OPTIONS(NSUInteger, SDWebImageOptions) {
     /**
      * By default, when a URL fail to be downloaded, the URL is blacklisted so the library won't keep trying.

SDWebImage/SDWebImageDownloader.h

@@ -14,6 +14,7 @@
 #import "SDWebImageDownloaderRequestModifier.h"
 #import "SDImageLoader.h"
 
+/// Downloader options
 typedef NS_OPTIONS(NSUInteger, SDWebImageDownloaderOptions) {
     /**
      * Put the download in the low queue priority and task priority.

SDWebImage/SDWebImageDownloaderConfig.h

@@ -9,6 +9,7 @@
 #import <Foundation/Foundation.h>
 #import "SDWebImageCompat.h"
 
+/// Operation execution order
 typedef NS_ENUM(NSInteger, SDWebImageDownloaderExecutionOrder) {
     /**
      * Default value. All download operations will execute in queue style (first-in-first-out).
@@ -21,6 +22,10 @@ typedef NS_ENUM(NSInteger, SDWebImageDownloaderExecutionOrder) {
     SDWebImageDownloaderLIFOExecutionOrder
 };
 
+/**
+ The class contains all the config for image downloader
+ @note This class conform to NSCopying, make sure to add the property in `copyWithZone:` as well.
+ */
 @interface SDWebImageDownloaderConfig : NSObject <NSCopying>
 
 /**

SDWebImage/SDWebImageDownloaderOperation.h

@@ -42,6 +42,9 @@
 @end
 
 
+/**
+ The download operation class for SDWebImageDownloader.
+ */
 @interface SDWebImageDownloaderOperation : NSOperation <SDWebImageDownloaderOperation>
 
 /**

SDWebImage/SDWebImageDownloaderRequestModifier.h

@@ -11,13 +11,19 @@
 
 typedef NSURLRequest * _Nullable (^SDWebImageDownloaderRequestModifierBlock)(NSURLRequest * _Nonnull request);
 
-// This is the protocol for downloader request modifier. We can use a block to specify the downloader request modifier. But Using protocol can make this extensible, and allow Swift user to use it easily instead of using `@convention(block)` to store a block into context options.
+/**
+ This is the protocol for downloader request modifier.
+ We can use a block to specify the downloader request modifier. But Using protocol can make this extensible, and allow Swift user to use it easily instead of using `@convention(block)` to store a block into context options.
+ */
 @protocol SDWebImageDownloaderRequestModifier <NSObject>
 
 - (nullable NSURLRequest *)modifiedRequestWithRequest:(nonnull NSURLRequest *)request;
 
 @end
 
+/**
+ A downloader request modifier class with block.
+ */
 @interface SDWebImageDownloaderRequestModifier : NSObject <SDWebImageDownloaderRequestModifier>
 
 - (nonnull instancetype)initWithBlock:(nonnull SDWebImageDownloaderRequestModifierBlock)block;

SDWebImage/SDWebImageError.h

@@ -11,8 +11,10 @@
 
 FOUNDATION_EXPORT NSErrorDomain const _Nonnull SDWebImageErrorDomain;
 
+/// The HTTP status code for invalid download response (NSNumber *)
 FOUNDATION_EXPORT NSErrorUserInfoKey const _Nonnull SDWebImageErrorDownloadStatusCodeKey;
 
+/// SDWebImage error domain and codes
 typedef NS_ERROR_ENUM(SDWebImageErrorDomain, SDWebImageError) {
     SDWebImageErrorInvalidURL = 1000, // The URL is invalid, such as nil URL or corrupted URL
     SDWebImageErrorBadImageData = 1001, // The image data can not be decoded to image, or the image data is empty

SDWebImage/SDWebImageIndicator.h

@@ -10,8 +10,10 @@
 
 #if SD_UIKIT || SD_MAC
 
-// A protocol to custom the indicator during the image loading
-// All of these methods are called from main queue
+/**
+ A protocol to custom the indicator during the image loading.
+ All of these methods are called from main queue.
+ */
 @protocol SDWebImageIndicator <NSObject>
 
 @required
@@ -21,10 +23,12 @@
  @return The indicator view
  */
 @property (nonatomic, strong, readonly, nonnull) UIView *indicatorView;
+
 /**
  Start the animating for indicator.
  */
 - (void)startAnimatingIndicator;
+
 /**
  Stop the animating for indicator.
  */
@@ -42,9 +46,11 @@
 
 #pragma mark - Activity Indicator
 
-// Activity indicator class
-// for UIKit(macOS), it use a `UIActivityIndicatorView`
-// for AppKit(macOS), it use a `NSProgressIndicator` with the spinning style
+/**
+ Activity indicator class.
+ for UIKit(macOS), it use a `UIActivityIndicatorView`.
+ for AppKit(macOS), it use a `NSProgressIndicator` with the spinning style.
+ */
 @interface SDWebImageActivityIndicator : NSObject <SDWebImageIndicator>
 
 #if SD_UIKIT
@@ -55,7 +61,9 @@
 
 @end
 
-// Convenience way to use activity indicator.
+/**
+ Convenience way to use activity indicator.
+ */
 @interface SDWebImageActivityIndicator (Conveniences)
 
 /// gray-style activity indicator
@@ -71,9 +79,11 @@
 
 #pragma mark - Progress Indicator
 
-// Progress indicator class
-// for UIKit(macOS), it use a `UIProgressView`
-// for AppKit(macOS), it use a `NSProgressIndicator` with the bar style
+/**
+ Progress indicator class.
+ for UIKit(macOS), it use a `UIProgressView`.
+ for AppKit(macOS), it use a `NSProgressIndicator` with the bar style.
+ */
 @interface SDWebImageProgressIndicator : NSObject <SDWebImageIndicator>
 
 #if SD_UIKIT
@@ -84,7 +94,9 @@
 
 @end
 
-// Convenience way to create progress indicator. Remember to specify the indicator width or use layout constraint if need.
+/**
+ Convenience way to create progress indicator. Remember to specify the indicator width or use layout constraint if need.
+ */
 @interface SDWebImageProgressIndicator (Conveniences)
 
 /// default-style progress indicator

SDWebImage/SDWebImageManager.h

@@ -18,7 +18,9 @@ typedef void(^SDExternalCompletionBlock)(UIImage * _Nullable image, NSError * _N
 
 typedef void(^SDInternalCompletionBlock)(UIImage * _Nullable image, NSData * _Nullable data, NSError * _Nullable error, SDImageCacheType cacheType, BOOL finished, NSURL * _Nullable imageURL);
 
-// A combined operation representing the cache and loader operation. You can use it to cancel the load process.
+/**
+ A combined operation representing the cache and loader operation. You can use it to cancel the load process.
+ */
 @interface SDWebImageCombinedOperation : NSObject <SDWebImageOperation>
 
 /**
@@ -41,6 +43,9 @@ typedef void(^SDInternalCompletionBlock)(UIImage * _Nullable image, NSData * _Nu
 
 @class SDWebImageManager;
 
+/**
+ The manager delegate protocol.
+ */
 @protocol SDWebImageManagerDelegate <NSObject>
 
 @optional

SDWebImage/SDWebImageOperation.h

@@ -8,13 +8,14 @@
 
 #import <Foundation/Foundation.h>
 
+/// A protocol represents cancelable operation.
 @protocol SDWebImageOperation <NSObject>
 
 - (void)cancel;
 
 @end
 
-// NSOperation conform to `SDWebImageOperation`
+/// NSOperation conform to `SDWebImageOperation`.
 @interface NSOperation (SDWebImageOperation) <SDWebImageOperation>
 
 @end

SDWebImage/SDWebImagePrefetcher.h

@@ -11,6 +11,9 @@
 
 @class SDWebImagePrefetcher;
 
+/**
+ A token represents a list of URLs, can be used to cancel the download.
+ */
 @interface SDWebImagePrefetchToken : NSObject <SDWebImageOperation>
 
 /**
@@ -25,6 +28,9 @@
 
 @end
 
+/**
+ The prefetcher delegate protocol
+ */
 @protocol SDWebImagePrefetcherDelegate <NSObject>
 
 @optional

SDWebImage/SDWebImageTransition.h

@@ -11,11 +11,6 @@
 #if SD_UIKIT || SD_MAC
 #import "SDImageCache.h"
 
-// This class is used to provide a transition animation after the view category load image finished. Use this on `sd_imageTransition` in UIView+WebCache.h
-// for UIKit(iOS & tvOS), we use `+[UIView transitionWithView:duration:options:animations:completion]` for transition animation.
-// for AppKit(macOS), we use `+[NSAnimationContext runAnimationGroup:completionHandler:]` for transition animation. You can call `+[NSAnimationContext currentContext]` to grab the context during animations block.
-// These transition are provided for basic usage. If you need complicated animation, consider to directly use Core Animation or use `SDWebImageAvoidAutoSetImage` and implement your own after image load finished.
-
 #if SD_UIKIT
 typedef UIViewAnimationOptions SDWebImageAnimationOptions;
 #else
@@ -28,6 +23,12 @@ typedef void (^SDWebImageTransitionPreparesBlock)(__kindof UIView * _Nonnull vie
 typedef void (^SDWebImageTransitionAnimationsBlock)(__kindof UIView * _Nonnull view, UIImage * _Nullable image);
 typedef void (^SDWebImageTransitionCompletionBlock)(BOOL finished);
 
+/**
+ This class is used to provide a transition animation after the view category load image finished. Use this on `sd_imageTransition` in UIView+WebCache.h
+ for UIKit(iOS & tvOS), we use `+[UIView transitionWithView:duration:options:animations:completion]` for transition animation.
+ for AppKit(macOS), we use `+[NSAnimationContext runAnimationGroup:completionHandler:]` for transition animation. You can call `+[NSAnimationContext currentContext]` to grab the context during animations block.
+ @note These transition are provided for basic usage. If you need complicated animation, consider to directly use Core Animation or use `SDWebImageAvoidAutoSetImage` and implement your own after image load finished.
+ */
 @interface SDWebImageTransition : NSObject
 
 /**
@@ -61,10 +62,11 @@ typedef void (^SDWebImageTransitionCompletionBlock)(BOOL finished);
 
 @end
 
-// Convenience way to create transition. Remember to specify the duration if needed.
-// for UIKit, these transition just use the correspond `animationOptions`. By default we enable `UIViewAnimationOptionAllowUserInteraction` to allow user interaction during transition.
-// for AppKit, these transition use Core Animation in `animations`. So your view must be layer-backed. Set `wantsLayer = YES` before you apply it.
-
+/**
+ Convenience way to create transition. Remember to specify the duration if needed.
+ for UIKit, these transition just use the correspond `animationOptions`. By default we enable `UIViewAnimationOptionAllowUserInteraction` to allow user interaction during transition.
+ for AppKit, these transition use Core Animation in `animations`. So your view must be layer-backed. Set `wantsLayer = YES` before you apply it.
+ */
 @interface SDWebImageTransition (Conveniences)
 
 /// Fade transition.

SDWebImage/UIButton+WebCache.h

@@ -13,7 +13,7 @@
 #import "SDWebImageManager.h"
 
 /**
- * Integrates SDWebImage async downloading and caching of remote images with UIButtonView.
+ * Integrates SDWebImage async downloading and caching of remote images with UIButton.
  */
 @interface UIButton (WebCache)
 

SDWebImage/UIImage+ForceDecode.h

@@ -8,6 +8,9 @@
 
 #import "SDWebImageCompat.h"
 
+/**
+ UIImage category about force decode feature (avoid Image/IO's lazy decoding during rendering behavior).
+ */
 @interface UIImage (ForceDecode)
 
 /**

SDWebImage/UIImage+GIF.h

@@ -9,7 +9,9 @@
 
 #import "SDWebImageCompat.h"
 
-// This category is just use as a convenience method. For more detail control, use methods in `UIImage+MultiFormat.h` or directlly use `SDImageCoder`
+/**
+ This category is just use as a convenience method. For more detail control, use methods in `UIImage+MultiFormat.h` or directlly use `SDImageCoder`.
+ */
 @interface UIImage (GIF)
 
 /**

SDWebImage/UIImage+MemoryCacheCost.h

@@ -8,6 +8,9 @@
 
 #import "SDWebImageCompat.h"
 
+/**
+ UIImage category for memory cache cost.
+ */
 @interface UIImage (MemoryCacheCost)
 
 /**

SDWebImage/UIImage+Metadata.h

@@ -9,6 +9,9 @@
 #import "SDWebImageCompat.h"
 #import "NSData+ImageContentType.h"
 
+/**
+ UIImage category for image metadata, including animation, loop count, format, incremental, etc.
+ */
 @interface UIImage (Metadata)
 
 /**

SDWebImage/UIImage+MultiFormat.h

@@ -9,6 +9,9 @@
 #import "SDWebImageCompat.h"
 #import "NSData+ImageContentType.h"
 
+/**
+ UIImage category for convenient image format decoding/encoding.
+ */
 @interface UIImage (MultiFormat)
 #pragma mark - Decode
 /**

SDWebImage/UIImageView+WebCache.h

@@ -10,8 +10,6 @@
 #import "SDWebImageManager.h"
 
 /**
- * Integrates SDWebImage async downloading and caching of remote images with UIImageView.
- *
  * Usage with a UITableViewCell sub-class:
  *
  * @code
@@ -41,6 +39,10 @@
 
  * @endcode
  */
+
+/**
+ * Integrates SDWebImage async downloading and caching of remote images with UIImageView.
+ */
 @interface UIImageView (WebCache)
 
 /**

SDWebImage/UIView+WebCache.h

@@ -19,6 +19,9 @@ FOUNDATION_EXPORT const int64_t SDWebImageProgressUnitCountUnknown; /* 1LL */
 
 typedef void(^SDSetImageBlock)(UIImage * _Nullable image, NSData * _Nullable imageData, SDImageCacheType cacheType, NSURL * _Nullable imageURL);
 
+/**
+ Integrates SDWebImage async downloading and caching of remote images with UIView subclass.
+ */
 @interface UIView (WebCache)
 
 /**

SDWebImage/UIView+WebCacheOperation.h

@@ -9,8 +9,10 @@
 #import "SDWebImageCompat.h"
 #import "SDWebImageOperation.h"
 
-// These methods are used to support canceling for UIView image loading, it's designed to be used internal but not external.
-// All the stored operations are weak, so it will be dalloced after image loading finished. If you need to store operations, use your own class to keep a strong reference for them.
+/**
+ These methods are used to support canceling for UIView image loading, it's designed to be used internal but not external.
+ All the stored operations are weak, so it will be dalloced after image loading finished. If you need to store operations, use your own class to keep a strong reference for them.
+ */
 @interface UIView (WebCacheOperation)
 
 /**