Update all the documentation of the SDGraphicsImageRenderer, fix small behavior to match Apple's documentation

SDWebImage/Core/SDGraphicsImageRenderer.h

@@ -8,8 +8,15 @@
 
 #import "SDWebImageCompat.h"
 
-typedef void (^SDGraphicsImageDrawingActions)(CGContextRef _Nonnull context);
+/**
+ These following class are provided to use `UIGraphicsImageRenderer` with polyfill, which allows write cross-platform(AppKit/UIKit) code and avoid runtime version check.
+ Compared to `UIGraphicsBeginImageContext`, `UIGraphicsImageRenderer` use dynamic bitmap info from your draw code to generate CGContext, not always use ARGB8888, which is more performant on RAM usage.
+ For usage, See more in Apple's documentation: https://developer.apple.com/documentation/uikit/uigraphicsimagerenderer
+ For UIKit on iOS/tvOS 10+, these method just use the same `UIGraphicsImageRenderer` API.
+ For others (macOS/watchOS or iOS/tvOS 10-), these method use the `SDImageGraphics.h` to implements the same behavior.
+*/
 
+typedef void (^SDGraphicsImageDrawingActions)(CGContextRef _Nonnull context);
 typedef NS_ENUM(NSInteger, SDGraphicsImageRendererFormatRange) {
     SDGraphicsImageRendererFormatRangeUnspecified = -1,
     SDGraphicsImageRendererFormatRangeAutomatic = 0,
@@ -17,28 +24,49 @@ typedef NS_ENUM(NSInteger, SDGraphicsImageRendererFormatRange) {
     SDGraphicsImageRendererFormatRangeStandard
 };
 
+/// A set of drawing attributes that represent the configuration of an image renderer context.
 @interface SDGraphicsImageRendererFormat : NSObject
 
+/// The display scale of the image renderer context.
+/// The default value is equal to the scale of the main screen.
 @property (nonatomic) CGFloat scale;
+
+/// A Boolean value indicating whether the underlying Core Graphics context has an alpha channel.
+/// The default value is NO.
 @property (nonatomic) BOOL opaque;
 
-/**
- For iOS 12+, the value is from system API
- For iOS 10-11, the value is from `prefersExtendedRange` property
- For iOS 9, the value is `.unspecified`
- */
+/// Specifying whether the bitmap context should use extended color.
+/// For iOS 12+, the value is from system `preferredRange` property
+/// For iOS 10-11, the value is from system `prefersExtendedRange` property
+/// For iOS 9-, the value is `.standard`
 @property (nonatomic) SDGraphicsImageRendererFormatRange preferredRange;
 
+/// Init the default format. See each properties's default value.
 - (nonnull instancetype)init;
+
+/// Returns a new format best suited for the main screen’s current configuration.
 + (nonnull instancetype)preferredFormat;
 
 @end
 
+/// A graphics renderer for creating Core Graphics-backed images.
 @interface SDGraphicsImageRenderer : NSObject
 
+/// Creates an image renderer for drawing images of a given size.
+/// @param size The size of images output from the renderer, specified in points.
+/// @return An initialized image renderer.
 - (nonnull instancetype)initWithSize:(CGSize)size;
+
+/// Creates a new image renderer with a given size and format.
+/// @param size The size of images output from the renderer, specified in points.
+/// @param format A SDGraphicsImageRendererFormat object that encapsulates the format used to create the renderer context.
+/// @return An initialized image renderer.
 - (nonnull instancetype)initWithSize:(CGSize)size format:(nonnull SDGraphicsImageRendererFormat *)format;
 
+/// Creates an image by following a set of drawing instructions.
+/// @param actions A SDGraphicsImageDrawingActions block that, when invoked by the renderer, executes a set of drawing instructions to create the output image.
+/// @note You should not retain or use the context outside the block, it's non-escaping.
+/// @return A UIImage object created by the supplied drawing actions.
 - (nonnull UIImage *)imageWithActions:(nonnull NS_NOESCAPE SDGraphicsImageDrawingActions)actions;
 
 @end

SDWebImage/Core/SDGraphicsImageRenderer.m

@@ -124,9 +124,16 @@
             self.uiformat = uiformat;
         } else {
 #endif
-            self.scale = 1.0;
+#if SD_WATCH
+            CGFloat screenScale = [WKInterfaceDevice currentDevice].screenScale;
+#elif SD_UIKIT
+            CGFloat screenScale = [UIScreen mainScreen].scale;
+#elif SD_MAC
+            CGFloat screenScale = [NSScreen mainScreen].backingScaleFactor;
+#endif
+            self.scale = screenScale;
             self.opaque = NO;
-            self.preferredRange = SDGraphicsImageRendererFormatRangeUnspecified;
+            self.preferredRange = SDGraphicsImageRendererFormatRangeStandard;
 #if SD_UIKIT
         }
 #endif
@@ -160,7 +167,7 @@
 #endif
             self.scale = screenScale;
             self.opaque = NO;
-            self.preferredRange = SDGraphicsImageRendererFormatRangeUnspecified;
+            self.preferredRange = SDGraphicsImageRendererFormatRangeStandard;
 #if SD_UIKIT
         }
 #endif

SDWebImage/Core/SDImageGraphics.h

@@ -13,6 +13,7 @@
  These following graphics context method are provided to easily write cross-platform(AppKit/UIKit) code.
  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.
+ @note If you don't care bitmap format (ARGB8888) and just draw image, use `SDGraphicsImageRenderer` instead. It's more performant on RAM usage.`
  */
 
 /// Returns the current graphics context.