Update all the comments about aniamted player

SDWebImage/Core/SDAnimatedImagePlayer.h

@@ -10,6 +10,7 @@
 #import "SDWebImageCompat.h"
 #import "SDImageCoder.h"
 
+/// A player to control the playback of animated image, which can be used to drive Animated ImageView or any rendering usage, like CALayer/WatchKit/SwiftUI rendering.
 @interface SDAnimatedImagePlayer : NSObject
 
 /// Current playing frame image. This value is KVO Compliance.
@@ -22,38 +23,60 @@
 @property (nonatomic, readonly) NSUInteger currentLoopCount;
 
 /// Total frame count for niamted image rendering. Defaults is animated image's frame count.
+/// @note For progressive animation, you can update this value when your provider receive more frames.
 @property (nonatomic, assign) NSUInteger totalFrameCount;
 
 /// Total loop count for animated image rendering. Default is animated image's loop count.
 @property (nonatomic, assign) NSUInteger totalLoopCount;
 
-/**
+/// Provide a max buffer size by bytes. This is used to adjust frame buffer count and can be useful when the decoding cost is expensive (such as Animated WebP software decoding). Default is 0.
- Provide a max buffer size by bytes. This is used to adjust frame buffer count and can be useful when the decoding cost is expensive (such as Animated WebP software decoding). Default is 0.
+/// `0` means automatically adjust by calculating current memory usage.
- `0` means automatically adjust by calculating current memory usage.
+/// `1` means without any buffer cache, each of frames will be decoded and then be freed after rendering. (Lowest Memory and Highest CPU)
- `1` means without any buffer cache, each of frames will be decoded and then be freed after rendering. (Lowest Memory and Highest CPU)
+/// `NSUIntegerMax` means cache all the buffer. (Lowest CPU and Highest Memory)
- `NSUIntegerMax` means cache all the buffer. (Lowest CPU and Highest Memory)
- */
 @property (nonatomic, assign) NSUInteger maxBufferSize;
 
-/**
+/// You can specify a runloop mode to let it rendering.
- You can specify a runloop mode to let it rendering.
+/// Default is NSRunLoopCommonModes on multi-core device, NSDefaultRunLoopMode on single-core device
- Default is NSRunLoopCommonModes on multi-core iOS device, NSDefaultRunLoopMode on single-core iOS device
- */
 @property (nonatomic, copy, nonnull) NSRunLoopMode runLoopMode;
 
+/// Create a player with animated image provider. If the provider's `animatedImageFrameCount` is less than 1, returns nil.
+/// The provider can be any protocol implementation, like `SDAnimatedImage`, `SDImageGIFCoder`, etc.
+/// @note This provider can represent mutable content, like prorgessive animated loading. But you need to update the frame count by yourself
+/// @param provider The animated provider
 - (nullable instancetype)initWithProvider:(nonnull id<SDAnimatedImageProvider>)provider;
+
+/// Create a player with animated image provider. If the provider's `animatedImageFrameCount` is less than 1, returns nil.
+/// The provider can be any protocol implementation, like `SDAnimatedImage` or `SDImageGIFCoder`, etc.
+/// @note This provider can represent mutable content, like prorgessive animated loading. But you need to update the frame count by yourself
+/// @param provider The animated provider
 + (nullable instancetype)playerWithProvider:(nonnull id<SDAnimatedImageProvider>)provider;
 
+/// The handler block when current frame and index changed.
 @property (nonatomic, copy, nullable) void (^animationFrameHandler)(NSUInteger index, UIImage * _Nonnull frame);
+
+/// The handler block when one loop count finished.
 @property (nonatomic, copy, nullable) void (^animationLoopHandler)(NSUInteger loopCount);
 
-@property (readonly) BOOL isPlaying;
+/// Return the status whehther animation is playing.
+@property (nonatomic, readonly) BOOL isPlaying;
+
+/// Start the animation. Or resume the previously paused animation.
 - (void)startPlaying;
+
+/// Pause the aniamtion. Keep the current frame index and loop count.
 - (void)pausePlaying;
+
+/// Stop the animation. Reset the current frame index and loop count.
 - (void)stopPlaying;
 
+/// Seek to the desired frame index and loop count.
+/// @note This can be used for advanced control like progressive loading, or skipping specify frames.
+/// @param index The frame index
+/// @param loopCount The loop count
 - (void)seekToFrameAtIndex:(NSUInteger)index loopCount:(NSUInteger)loopCount;
 
+/// Clear the frame cache buffer. The frame cache buffer size can be controled by `maxBufferSize`.
+/// By default, when stop or pause the animation, the frame buffer is still kept to ready for the next restart
 - (void)clearFrameBuffer;
 
 @end