Make cancelImageDownload internal to simplify the Public API. Add doc…

…umentation. (#18)

Sources/API/OKNameSpace.swift

@@ -42,7 +42,7 @@ extension ObjectWrapper: ImageDownloaderReceiptHandling {
         }
     }
 
-    public func cancelImageDownload(imageDownloader: ImageDownloading = ImageDownloader.shared) {
+    func cancelImageDownload(imageDownloader: ImageDownloading = ImageDownloader.shared) {
         guard let imageDownloaderReceipt = imageDownloaderReceipt else {
             return
         }

Sources/Extensions/UIButton+ImageDownloader.swift

@@ -10,6 +10,7 @@ import UIKit
 
 public extension ObjectWrapper where T: UIButton {
 
+    /// A convenience property that when set will download (or cancel if nil) the url. The getter returns the active imageDownloaderReceipt URL.
     var imageUrl: URL? {
         get {
             imageDownloaderReceipt?.url
@@ -19,12 +20,19 @@ public extension ObjectWrapper where T: UIButton {
         }
     }
 
+    /// A convenience method to set an image based on a URL. This will only set for the .normal state of the UIButton.
+    /// - Parameters:
+    ///   - url: the HTTP URL for the image download. If set to nil, it will cancel any active requests based on the imageDownloaderReceipt. Note: This does not currently support local file system URLs.
+    ///   - imageDownloader: The Image Downloader shared instance. Used for unit testing injection of mocks.
+    ///   - completionHandler: If set to nil, the image will be automatically set on completion. If completionHandler is set, the image will not be automatically set and instead returned via the completionHandler for further modifications (resizing, image filters, custom animation transitions, etc.)
+    /// - Returns: The receipt for the active image download.
+    @discardableResult
     func setImage(url: URL?,
                   imageDownloader: ImageDownloading = ImageDownloader.shared,
-                  completionHandler: ImageDownloader.CompletionHandler? = nil) {
+                  completionHandler: ImageDownloader.CompletionHandler? = nil) -> ImageDownloaderReceipt? {
         guard let url = url else {
             cancelImageDownload(imageDownloader: imageDownloader)
-            return
+            return nil
         }
 
         if imageDownloaderReceipt != nil {
@@ -50,6 +58,8 @@ public extension ObjectWrapper where T: UIButton {
 
             completionHandler(result, downloadReceipt)
         }
+
+        return imageDownloaderReceipt
     }
 
 }

Sources/Extensions/UIImageView+ImageDownloader.swift

@@ -9,7 +9,8 @@
 import UIKit
 
 public extension ObjectWrapper where T: UIImageView {
-
+
+    /// A convenience property that when set will download (or cancel if nil) the url. The getter returns the active imageDownloaderReceipt URL.
     var imageUrl: URL? {
         get {
             imageDownloaderReceipt?.url
@@ -19,12 +20,19 @@ public extension ObjectWrapper where T: UIImageView {
         }
     }
 
+    /// A convenience method to set an image based on a URL.
+    /// - Parameters:
+    ///   - url: the HTTP URL for the image download. If set to nil, it will cancel any active requests based on the imageDownloaderReceipt. Note: This does not currently support local file system URLs.
+    ///   - imageDownloader: The Image Downloader shared instance. Used for unit testing injection of mocks.
+    ///   - completionHandler: If set to nil, the image will be automatically set on completion. If completionHandler is set, the image will not be automatically set and instead returned via the completionHandler for further modifications (resizing, image filters, custom animation transitions, etc.)
+    /// - Returns: The receipt for the active image download.
+    @discardableResult
     func setImage(url: URL?,
                   imageDownloader: ImageDownloading = ImageDownloader.shared,
-                  completionHandler: ImageDownloader.CompletionHandler? = nil) {
+                  completionHandler: ImageDownloader.CompletionHandler? = nil) -> ImageDownloaderReceipt? {
         guard let url = url else {
             cancelImageDownload(imageDownloader: imageDownloader)
-            return
+            return nil
         }
 
         if imageDownloaderReceipt != nil {
@@ -50,6 +58,8 @@ public extension ObjectWrapper where T: UIImageView {
 
             completionHandler(result, downloadReceipt)
         }
+
+        return imageDownloaderReceipt
     }
 
 }

Tests/UIButtonImageDownloaderTests.swift

@@ -38,9 +38,10 @@ final class UIButtonImageDownloaderTests: XCTestCase {
 
         XCTAssertNil(button.ok.imageDownloaderReceipt)
 
-        button.ok.setImage(url: url, imageDownloader: imageDownloader, completionHandler: nil)
+        let receipt: ImageDownloaderReceipt? = button.ok.setImage(url: url, imageDownloader: imageDownloader, completionHandler: nil)
 
         XCTAssertNotNil(button.ok.imageDownloaderReceipt)
+        XCTAssertEqual(button.ok.imageDownloaderReceipt, receipt)
     }
 
     func test_setImageUrl_whenSuccess_itNilsTheImageDownloadReceipt() {

Tests/UIImageViewImageDownloaderTests.swift

@@ -38,9 +38,10 @@ final class UIImageViewImageDownloaderTests: XCTestCase {
 
         XCTAssertNil(imageView.ok.imageDownloaderReceipt?.url)
 
-        imageView.ok.setImage(url: url, imageDownloader: imageDownloader, completionHandler: nil)
+        let receipt: ImageDownloaderReceipt? = imageView.ok.setImage(url: url, imageDownloader: imageDownloader, completionHandler: nil)
 
-        XCTAssertNotNil(imageView.ok.imageDownloaderReceipt?.url)
+        XCTAssertNotNil(imageView.ok.imageDownloaderReceipt)
+        XCTAssertEqual(imageView.ok.imageDownloaderReceipt, receipt)
     }
 
     func test_setImageUrl_whenSuccess_itNilsTheImageDownloadReceipt() {