Add documentation

Sources/ImageProcessor.swift

@@ -73,7 +73,7 @@ public extension ImageProcessor {
     ///
     /// - parameter another: An `ImageProcessor` you want to append to `self`.
     ///
-    /// - returns: The new `ImageProcessor`. It will process the image in the order
+    /// - returns: The new `ImageProcessor` will process the image in the order
     ///            of the two processors concatenated.
     public func append(another: ImageProcessor) -> ImageProcessor {
         let newIdentifier = identifier.appending("|>\(another.identifier)")
@@ -104,13 +104,21 @@ public struct DefaultImageProcessor: ImageProcessor {
     /// A default `DefaultImageProcessor` could be used across.
     public static let `default` = DefaultImageProcessor()
     
+    /// Identifier of the processor.
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public let identifier = ""
     
     /// Initialize a `DefaultImageProcessor`
-    ///
-    /// - returns: An initialized `DefaultImageProcessor`.
     public init() {}
     
+    /// Process an input `ImageProcessItem` item to an image for this processor.
+    ///
+    /// - parameter item:    Input item which will be processed by `self`
+    /// - parameter options: Options when processing the item.
+    ///
+    /// - returns: The processed image.
+    /// 
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public func process(item: ImageProcessItem, options: KingfisherOptionsInfo) -> Image? {
         switch item {
         case .image(let image):
@@ -128,6 +136,9 @@ public struct DefaultImageProcessor: ImageProcessor {
 /// Processor for making round corner images. Only CG-based images are supported in macOS, 
 /// if a non-CG image passed in, the processor will do nothing.
 public struct RoundCornerImageProcessor: ImageProcessor {
+    
+    /// Identifier of the processor.
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public let identifier: String
 
     /// Corner radius will be applied in processing.
@@ -142,8 +153,6 @@ public struct RoundCornerImageProcessor: ImageProcessor {
     /// - parameter targetSize:   Target size of output image should be. If `nil`, 
     ///                           the image will keep its original size after processing.
     ///                           Default is `nil`.
-    ///
-    /// - returns: An initialized `RoundCornerImageProcessor`.
     public init(cornerRadius: CGFloat, targetSize: CGSize? = nil) {
         self.cornerRadius = cornerRadius
         self.targetSize = targetSize
@@ -154,6 +163,14 @@ public struct RoundCornerImageProcessor: ImageProcessor {
         }
     }
     
+    /// Process an input `ImageProcessItem` item to an image for this processor.
+    ///
+    /// - parameter item:    Input item which will be processed by `self`
+    /// - parameter options: Options when processing the item.
+    ///
+    /// - returns: The processed image.
+    ///
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public func process(item: ImageProcessItem, options: KingfisherOptionsInfo) -> Image? {
         switch item {
         case .image(let image):
@@ -179,6 +196,9 @@ public enum ContentMode {
 
 /// Processor for resizing images. Only CG-based images are supported in macOS.
 public struct ResizingImageProcessor: ImageProcessor {
+    
+    /// Identifier of the processor.
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public let identifier: String
     
     /// Target size of output image should be.
@@ -192,8 +212,6 @@ public struct ResizingImageProcessor: ImageProcessor {
     ///
     /// - parameter targetSize: Target size of output image should be.
     /// - parameter contentMode: Target content mode of output image should be.
-    ///
-    /// - returns: An initialized `ResizingImageProcessor`.
     public init(targetSize: CGSize, contentMode: ContentMode = .none) {
         self.targetSize = targetSize
         self.targetContentMode = contentMode
@@ -205,6 +223,14 @@ public struct ResizingImageProcessor: ImageProcessor {
         }
     }
     
+    /// Process an input `ImageProcessItem` item to an image for this processor.
+    ///
+    /// - parameter item:    Input item which will be processed by `self`
+    /// - parameter options: Options when processing the item.
+    ///
+    /// - returns: The processed image.
+    ///
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public func process(item: ImageProcessItem, options: KingfisherOptionsInfo) -> Image? {
         switch item {
         case .image(let image):
@@ -218,6 +244,9 @@ public struct ResizingImageProcessor: ImageProcessor {
 /// Processor for adding blur effect to images. `Accelerate.framework` is used underhood for 
 /// a better performance. A simulated Gaussian blur with specified blur radius will be applied.
 public struct BlurImageProcessor: ImageProcessor {
+    
+    /// Identifier of the processor.
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public let identifier: String
     
     /// Blur radius for the simulated Gaussian blur.
@@ -226,13 +255,19 @@ public struct BlurImageProcessor: ImageProcessor {
     /// Initialize a `BlurImageProcessor`
     ///
     /// - parameter blurRadius: Blur radius for the simulated Gaussian blur.
-    ///
-    /// - returns: An initialized `BlurImageProcessor`.
     public init(blurRadius: CGFloat) {
         self.blurRadius = blurRadius
         self.identifier = "com.onevcat.Kingfisher.BlurImageProcessor(\(blurRadius))"
     }
     
+    /// Process an input `ImageProcessItem` item to an image for this processor.
+    ///
+    /// - parameter item:    Input item which will be processed by `self`
+    /// - parameter options: Options when processing the item.
+    ///
+    /// - returns: The processed image.
+    ///
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public func process(item: ImageProcessItem, options: KingfisherOptionsInfo) -> Image? {
         switch item {
         case .image(let image):
@@ -247,7 +282,9 @@ public struct BlurImageProcessor: ImageProcessor {
 /// Processor for adding an overlay to images. Only CG-based images are supported in macOS.
 public struct OverlayImageProcessor: ImageProcessor {
     
-    public var identifier: String
+    /// Identifier of the processor.
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
+    public let identifier: String
     
     /// Overlay color will be used to overlay the input image.
     public let overlay: Color
@@ -260,14 +297,20 @@ public struct OverlayImageProcessor: ImageProcessor {
     /// - parameter overlay:  Overlay color will be used to overlay the input image.
     /// - parameter fraction: Fraction will be used when overlay the color to image. 
     ///                       From 0.0 to 1.0. 0.0 means solid color, 1.0 means transparent overlay.
-    ///
-    /// - returns: An initialized `OverlayImageProcessor`.
     public init(overlay: Color, fraction: CGFloat = 0.5) {
         self.overlay = overlay
         self.fraction = fraction
         self.identifier = "com.onevcat.Kingfisher.OverlayImageProcessor(\(overlay.hex)_\(fraction))"
     }
     
+    /// Process an input `ImageProcessItem` item to an image for this processor.
+    ///
+    /// - parameter item:    Input item which will be processed by `self`
+    /// - parameter options: Options when processing the item.
+    ///
+    /// - returns: The processed image.
+    ///
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public func process(item: ImageProcessItem, options: KingfisherOptionsInfo) -> Image? {
         switch item {
         case .image(let image):
@@ -281,6 +324,8 @@ public struct OverlayImageProcessor: ImageProcessor {
 /// Processor for tint images with color. Only CG-based images are supported.
 public struct TintImageProcessor: ImageProcessor {
     
+    /// Identifier of the processor.
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public let identifier: String
     
     /// Tint color will be used to tint the input image.
@@ -289,13 +334,19 @@ public struct TintImageProcessor: ImageProcessor {
     /// Initialize a `TintImageProcessor`
     ///
     /// - parameter tint: Tint color will be used to tint the input image.
-    ///
-    /// - returns: An initialized `TintImageProcessor`.
     public init(tint: Color) {
         self.tint = tint
         self.identifier = "com.onevcat.Kingfisher.TintImageProcessor(\(tint.hex))"
     }
     
+    /// Process an input `ImageProcessItem` item to an image for this processor.
+    ///
+    /// - parameter item:    Input item which will be processed by `self`
+    /// - parameter options: Options when processing the item.
+    ///
+    /// - returns: The processed image.
+    ///
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public func process(item: ImageProcessItem, options: KingfisherOptionsInfo) -> Image? {
         switch item {
         case .image(let image):
@@ -310,6 +361,8 @@ public struct TintImageProcessor: ImageProcessor {
 /// watchOS is not supported.
 public struct ColorControlsProcessor: ImageProcessor {
     
+    /// Identifier of the processor.
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public let identifier: String
     
     /// Brightness changing to image.
@@ -330,8 +383,6 @@ public struct ColorControlsProcessor: ImageProcessor {
     /// - parameter contrast:   Contrast changing to image.
     /// - parameter saturation: Saturation changing to image.
     /// - parameter inputEV:    InputEV changing to image.
-    ///
-    /// - returns: An initialized `ColorControlsProcessor`
     public init(brightness: CGFloat, contrast: CGFloat, saturation: CGFloat, inputEV: CGFloat) {
         self.brightness = brightness
         self.contrast = contrast
@@ -340,6 +391,14 @@ public struct ColorControlsProcessor: ImageProcessor {
         self.identifier = "com.onevcat.Kingfisher.ColorControlsProcessor(\(brightness)_\(contrast)_\(saturation)_\(inputEV))"
     }
     
+    /// Process an input `ImageProcessItem` item to an image for this processor.
+    ///
+    /// - parameter item:    Input item which will be processed by `self`
+    /// - parameter options: Options when processing the item.
+    ///
+    /// - returns: The processed image.
+    ///
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public func process(item: ImageProcessItem, options: KingfisherOptionsInfo) -> Image? {
         switch item {
         case .image(let image):
@@ -353,32 +412,70 @@ public struct ColorControlsProcessor: ImageProcessor {
 /// Processor for applying black and white effect to images. Only CG-based images are supported.
 /// watchOS is not supported.
 public struct BlackWhiteProcessor: ImageProcessor {
+    
+    /// Identifier of the processor.
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public let identifier = "com.onevcat.Kingfisher.BlackWhiteProcessor"
     
     /// Initialize a `BlackWhiteProcessor`
-    ///
-    /// - returns: An initialized `BlackWhiteProcessor`
     public init() {}
     
+    /// Process an input `ImageProcessItem` item to an image for this processor.
+    ///
+    /// - parameter item:    Input item which will be processed by `self`
+    /// - parameter options: Options when processing the item.
+    ///
+    /// - returns: The processed image.
+    ///
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public func process(item: ImageProcessItem, options: KingfisherOptionsInfo) -> Image? {
         return ColorControlsProcessor(brightness: 0.0, contrast: 1.0, saturation: 0.0, inputEV: 0.7)
             .process(item: item, options: options)
     }
 }
 
+/// Processor for cropping an image. Only CG-based images are supported.
+/// watchOS is not supported.
 public struct CroppingImageProcessor: ImageProcessor {
     
+    /// Identifier of the processor.
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public let identifier: String
     
+    /// Target size of output image should be.
     public let size: CGSize
+    
+    /// Anchor point from which the output size should be calculate.
+    /// The anchor point is consisted by two values between 0.0 and 1.0.
+    /// It indicates a related point in current image. 
+    /// See `CroppingImageProcessor.init(size:anchor:)` for more.
     public let anchor: CGPoint
     
+    /// Initialize a `CroppingImageProcessor`
+    ///
+    /// - Parameters:
+    ///   - size: Target size of output image should be.
+    ///   - anchor: The anchor point from which the size should be calculated.
+    /// - Note:
+    ///   The anchor point is consisted by two values between 0.0 and 1.0.
+    ///   It indicates a related point in current image, eg: (0.0, 0.0) for top-left
+    ///   corner, (0.5, 0.5) for center and (1.0, 1.0) for bottom-right corner.
+    ///   The `size` property of `CroppingImageProcessor` will be used along with
+    ///   `anchor` to calculate a target rectange in the size of image.
     public init(size: CGSize, anchor: CGPoint = CGPoint(x: 0.5, y: 0.5)) {
         self.size = size
         self.anchor = anchor
         self.identifier = "com.onevcat.Kingfisher.CroppingImageProcessor(\(size)_\(anchor))"
     }
     
+    /// Process an input `ImageProcessItem` item to an image for this processor.
+    ///
+    /// - parameter item:    Input item which will be processed by `self`
+    /// - parameter options: Options when processing the item.
+    ///
+    /// - returns: The processed image.
+    ///
+    /// - Note: See documentation of `ImageProcessor` protocol for more.
     public func process(item: ImageProcessItem, options: KingfisherOptionsInfo) -> Image? {
         switch item {
         case .image(let image):