Further logic and documentation improvements

Author: maicki

AsyncDisplayKit/ASNetworkImageNode.h

@@ -26,7 +26,7 @@ NS_ASSUME_NONNULL_BEGIN
 @interface ASNetworkImageNode : ASImageNode
 
 /**
- * The designated initializer.  Cache and Downloader are WEAK references.
+ * The designated initializer. Cache and Downloader are WEAK references.
  *
  * @param cache The object that implements a cache of images for the image node.  Weak reference.
  * @param downloader The object that implements image downloading for the image node.  Must not be nil.  Weak reference.
@@ -38,7 +38,7 @@ NS_ASSUME_NONNULL_BEGIN
 - (instancetype)initWithCache:(nullable id<ASImageCacheProtocol>)cache downloader:(id<ASImageDownloaderProtocol>)downloader NS_DESIGNATED_INITIALIZER;
 
 /**
- * Convenience initialiser.
+ * Convenience initializer.
  *
  * @return An ASNetworkImageNode configured to use the NSURLSession-powered ASBasicImageDownloader, and no extra cache.
  */
@@ -49,6 +49,17 @@ NS_ASSUME_NONNULL_BEGIN
  */
 @property (nullable, nonatomic, weak, readwrite) id<ASNetworkImageNodeDelegate> delegate;
 
+/**
+ * The image to display.
+ *
+ * @discussion By setting an image to the image property the ASNetworkImageNode will act like a plain ASImageNode.
+ * As soon as the URL is set the ASNetworkImageNode will act like an ASNetworkImageNode and the image property
+ * will be managed internally. This means the image property will be cleared out and replaced by the placeholder 
+ * (<defaultImage>) image while loading and the final image after the new image data was downloaded and processed.
+ * If you want to use a placholder image functionality use the defaultImage property instead.
+ */
+@property (nullable, nonatomic, strong) UIImage *image;
+
 /**
  * A placeholder image to display while the URL is loading.
  */
@@ -57,16 +68,21 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * The URL of a new image to download and display.
  *
- * @discussion Changing this property will reset the displayed image to a placeholder (<defaultImage>) while loading.
+ * @discussion By setting an URL, the image property of this node will be managed internally. This means previously
+ * directly set images to the image property will be cleared out and replaced by the placeholder (<defaultImage>) image
+ * while loading and the final image after the new image data was downloaded and processed.
  */
 @property (nullable, nonatomic, strong, readwrite) NSURL *URL;
 
 /**
  * Download and display a new image.
  *
  * @param URL The URL of a new image to download and display.
- *
  * @param reset Whether to display a placeholder (<defaultImage>) while loading the new image.
+ *
+ * @discussion By setting an URL, the image property of this node will be managed internally. This means previously
+ * directly set images to the image property will be cleared out and replaced by the placeholder (<defaultImage>) image
+ * while loading and the final image after the new image data was downloaded and processed.
  */
 - (void)setURL:(nullable NSURL *)URL resetToDefault:(BOOL)reset;
 

AsyncDisplayKit/ASNetworkImageNode.mm

@@ -73,6 +73,8 @@ @interface ASNetworkImageNode ()
 
 @implementation ASNetworkImageNode
 
+@dynamic image;
+
 - (instancetype)initWithCache:(id<ASImageCacheProtocol>)cache downloader:(id<ASImageDownloaderProtocol>)downloader
 {
   if (!(self = [super init]))
@@ -121,20 +123,13 @@ - (void)dealloc
 /// Setter for public image property. It has the side effect to set an internal _imageWasSetExternally that prevents setting an image internally. Setting an image internally should happen with the _setImage: method
 - (void)setImage:(UIImage *)image
 {
-  __instanceLock__.lock();
-  
-#ifdef DEBUG
-  if (_URL != nil) {
-    NSLog(@"Setting the image directly on an %@ and setting and setting an URL is not supported. If you want to use a placeholder image please use defaultImage .", NSStringFromClass([self class]));
-  }
-#endif
+  ASDN::MutexLocker l(__instanceLock__);
 
   _imageWasSetExternally = (image != nil);
   if (_imageWasSetExternally) {
-    [self __cancelDownloadAndClearImage];
+    [self _cancelDownloadAndClearImage];
     _URL = nil;
   }
-  __instanceLock__.unlock();
 
   [self _setImage:image];
 }
@@ -153,11 +148,6 @@ - (void)setURL:(NSURL *)URL resetToDefault:(BOOL)reset
 {
   ASDN::MutexLocker l(__instanceLock__);
 
-#ifdef DEBUG
-  if (_imageWasSetExternally) {
-    NSLog(@"Setting the image directly on an %@ and setting and setting an URL is not supported. If you want to use a placeholder image please use defaultImage .", NSStringFromClass([self class]));
-  }
-#endif
   _imageWasSetExternally = NO;
 
   if (ASObjectIsEqual(URL, _URL)) {
@@ -352,7 +342,7 @@ - (void)didExitPreloadState
       return;
     }
 
-    [self __cancelDownloadAndClearImage];
+    [self _cancelDownloadAndClearImage];
   }
 }
 
@@ -419,7 +409,7 @@ - (void)_updateProgressImageBlockOnDownloaderIfNeeded
   _downloadIdentifierForProgressBlock = newDownloadIDForProgressBlock;
 }
 
-- (void)__cancelDownloadAndClearImage
+- (void)_cancelDownloadAndClearImage
 {
   [self _cancelImageDownload];
   [self _clearImage];
@@ -428,6 +418,20 @@ - (void)__cancelDownloadAndClearImage
   }
 }
 
+- (void)_cancelImageDownload
+{
+  if (!_downloadIdentifier) {
+    return;
+  }
+
+  if (_downloadIdentifier) {
+    [_downloader cancelImageDownloadForIdentifier:_downloadIdentifier];
+  }
+  _downloadIdentifier = nil;
+
+  _cacheUUID = nil;
+}
+
 - (void)_clearImage
 {
   // Destruction of bigger images on the main thread can be expensive
@@ -449,20 +453,6 @@ - (void)_clearImage
   });
 }
 
-- (void)_cancelImageDownload
-{
-  if (!_downloadIdentifier) {
-    return;
-  }
-
-  if (_downloadIdentifier) {
-    [_downloader cancelImageDownloadForIdentifier:_downloadIdentifier];
-  }
-  _downloadIdentifier = nil;
-
-  _cacheUUID = nil;
-}
-
 - (void)_downloadImageWithCompletion:(void (^)(id <ASImageContainerProtocol> imageContainer, NSError*, id downloadIdentifier))finished
 {
   ASPerformBlockOnBackgroundThread(^{