Permalink
Browse files

Add appledoc comments

  • Loading branch information...
1 parent 6574083 commit 110799614f351ba51fec1ae962757d5c9a7216f1 @rs committed May 10, 2012
@@ -18,7 +18,7 @@
537612B6155AB74D005750A4 /* DetailViewController.xib in Resources */ = {isa = PBXBuildFile; fileRef = 537612B4155AB74D005750A4 /* DetailViewController.xib */; };
537612E7155ABA44005750A4 /* ImageIO.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 537612E6155ABA44005750A4 /* ImageIO.framework */; };
53761328155AD31B005750A4 /* MapKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 537612E3155ABA3C005750A4 /* MapKit.framework */; };
- 53A2B4FC155B096D00B12423 /* libSDWebImage ARC.a in Frameworks */ = {isa = PBXBuildFile; fileRef = 53A2B4F9155B095800B12423 /* libSDWebImage ARC.a */; };
+ 53A2B4FC155B096D00B12423 /* libSDWebImageARC.a in Frameworks */ = {isa = PBXBuildFile; fileRef = 53A2B4F9155B095800B12423 /* libSDWebImageARC.a */; };
53A2B50D155B155A00B12423 /* placeholder.png in Resources */ = {isa = PBXBuildFile; fileRef = 53A2B50B155B155A00B12423 /* placeholder.png */; };
53A2B50E155B155A00B12423 /* placeholder@2x.png in Resources */ = {isa = PBXBuildFile; fileRef = 53A2B50C155B155A00B12423 /* placeholder@2x.png */; };
/* End PBXBuildFile section */
@@ -77,7 +77,7 @@
isa = PBXFrameworksBuildPhase;
buildActionMask = 2147483647;
files = (
- 53A2B4FC155B096D00B12423 /* libSDWebImage ARC.a in Frameworks */,
+ 53A2B4FC155B096D00B12423 /* libSDWebImageARC.a in Frameworks */,
53761328155AD31B005750A4 /* MapKit.framework in Frameworks */,
537612E7155ABA44005750A4 /* ImageIO.framework in Frameworks */,
5376129A155AB74D005750A4 /* UIKit.framework in Frameworks */,
@@ -222,7 +222,7 @@
53A2B4F9155B095800B12423 /* libSDWebImage ARC.a */ = {
isa = PBXReferenceProxy;
fileType = archive.ar;
- path = "libSDWebImage ARC.a";
+ path = libSDWebImageARC.a;
remoteRef = 53A2B4F8155B095800B12423 /* PBXContainerItemProxy */;
sourceTree = BUILT_PRODUCTS_DIR;
};
View
@@ -115,28 +115,14 @@ Here is a simple example of how to use SDWebImageManager:
```objective-c
SDWebImageManager *manager = [SDWebImageManager sharedManager];
-
-UIImage *cachedImage = [manager imageWithURL:url];
-
-if (cachedImage)
-{
- // Use the cached image immediatly
-}
-else
-{
- // Start an async download
- [manager downloadWithURL:url delegate:self];
-}
-```
-
-Your class will have to implement the SDWebImageManagerDelegate protocol, and to implement the
-webImageManager:didFinishWithImage: method from this protocol:
-
-```objective-c
-- (void)webImageManager:(SDWebImageManager *)imageManager didFinishWithImage:(UIImage *)image
-{
- // Do something with the downloaded image
-}
+[manager downloadWithURL:imageURL
+ delegate:self
+ options:0
+ success:^(UIImage *image)
+ {
+ // do something with image
+ }
+ failure:nil];
```
### Using Asynchronous Image Downloader Independently
@@ -11,6 +11,9 @@
#import "SDWebImageManagerDelegate.h"
#import "SDWebImageManager.h"
+/**
+ * Integrates SDWebImage async downloading and caching of remote images with MKAnnotationView.
+ */
@interface MKAnnotationView (WebCache) <SDWebImageManagerDelegate>
/**
View
@@ -9,26 +9,117 @@
#import <Foundation/Foundation.h>
#import "SDImageCacheDelegate.h"
+/**
+ * SDImageCache maintains a memory cache and an optional disk cache. Disk cache write operations are performed
+ * asynchronous so it doesn’t add unnecessary latency to the UI.
+ */
@interface SDImageCache : NSObject
{
NSMutableDictionary *memCache;
NSString *diskCachePath;
NSOperationQueue *cacheInQueue, *cacheOutQueue;
}
+/**
+ * Returns global shared cache instance
+ *
+ * @return SDImageCache global instance
+ */
+ (SDImageCache *)sharedImageCache;
+
+/**
+ * Store an image into memory and disk cache at the given key.
+ *
+ * @param image The image to store
+ * @param key The unique image cache key, usually it's image absolute URL
+ */
- (void)storeImage:(UIImage *)image forKey:(NSString *)key;
+
+/**
+ * Store an image into memory and optionally disk cache at the given key.
+ *
+ * @param image The image to store
+ * @param key The unique image cache key, usually it's image absolute URL
+ * @param toDisk Store the image to disk cache if YES
+ */
- (void)storeImage:(UIImage *)image forKey:(NSString *)key toDisk:(BOOL)toDisk;
+
+/**
+ * Store an image into memory and optionally disk cache at the given key.
+ *
+ * @param image The image to store
+ * @param data The image data as returned by the server, this representation will be used for disk storage
+ * instead of converting the given image object into a storable/compressed image format in order
+ * to save quality and CPU
+ * @param key The unique image cache key, usually it's image absolute URL
+ * @param toDisk Store the image to disk cache if YES
+ */
- (void)storeImage:(UIImage *)image imageData:(NSData *)data forKey:(NSString *)key toDisk:(BOOL)toDisk;
+
+/**
+ * Query the memory cache for an image at a given key and fallback to disk cache
+ * synchronousely if not found in memory.
+ *
+ * @warning This method may perform some synchronous IO operations
+ *
+ * @param key The unique key used to store the wanted image
+ */
- (UIImage *)imageFromKey:(NSString *)key;
+
+/**
+ * Query the memory cache for an image at a given key and optionnaly fallback to disk cache
+ * synchronousely if not found in memory.
+ *
+ * @warning This method may perform some synchronous IO operations if fromDisk is YES
+ *
+ * @param key The unique key used to store the wanted image
+ * @param fromDisk Try to retrive the image from disk if not found in memory if YES
+ */
- (UIImage *)imageFromKey:(NSString *)key fromDisk:(BOOL)fromDisk;
+
+
+/**
+ * Query the disk cache asynchronousely.
+ *
+ * @param key The unique key used to store the wanted image
+ * @param delegate The delegate object to send response to
+ * @param info An NSDictionary with some user info sent back to the delegate
+ */
- (void)queryDiskCacheForKey:(NSString *)key delegate:(id <SDImageCacheDelegate>)delegate userInfo:(NSDictionary *)info;
+/**
+ * Remove the image from memory and disk cache synchronousely
+ *
+ * @param key The unique image cache key
+ */
- (void)removeImageForKey:(NSString *)key;
+
+/**
+ * Remove the image from memory and optionaly disk cache synchronousely
+ *
+ * @param key The unique image cache key
+ * @param fromDisk Also remove cache entry from disk if YES
+ */
- (void)removeImageForKey:(NSString *)key fromDisk:(BOOL)fromDisk;
+
+/**
+ * Clear all memory cached images
+ */
- (void)clearMemory;
+
+/**
+ * Clear all disk cached images
+ */
- (void)clearDisk;
+
+/**
+ * Remove all expired cached image from disk
+ */
- (void)cleanDisk;
+
+/**
+ * Get the size used by the disk cache
+ */
- (int)getSize;
@end
@@ -10,10 +10,30 @@
@class SDImageCache;
+/**
+ * Delegate protocol for SDImageCache
+ */
@protocol SDImageCacheDelegate <NSObject>
@optional
+
+/**
+ * Called when [SDImageCache queryDiskCacheForKey:delegate:userInfo:] retrived the image from cache
+ *
+ * @param imageCache The cache store instance
+ * @param image The requested image instance
+ * @param key The requested image cache key
+ * @param info The provided user info dictionary
+ */
- (void)imageCache:(SDImageCache *)imageCache didFindImage:(UIImage *)image forKey:(NSString *)key userInfo:(NSDictionary *)info;
+
+/**
+ * Called when [SDImageCache queryDiskCacheForKey:delegate:userInfo:] did not find the image in the cache
+ *
+ * @param imageCache The cache store instance
+ * @param key The requested image cache key
+ * @param info The provided user info dictionary
+ */
- (void)imageCache:(SDImageCache *)imageCache didNotFindImageForKey:(NSString *)key userInfo:(NSDictionary *)info;
@end
@@ -49,14 +49,26 @@
#endif
-NS_INLINE UIImage *SDScaledImageForPath(NSString *path, NSData *imageData)
+NS_INLINE UIImage *SDScaledImageForPath(NSString *path, NSObject *imageOrData)
{
- if (!imageData)
+ if (!imageOrData)
{
return nil;
}
- UIImage *image = [[UIImage alloc] initWithData:imageData];
+ UIImage *image = nil;
+ if ([imageOrData isKindOfClass:[NSData class]])
+ {
+ image = [[UIImage alloc] initWithData:(NSData *)imageOrData];
+ }
+ else if ([imageOrData isKindOfClass:[NSData class]])
+ {
+ image = SDWIReturnRetained((UIImage *)imageOrData);
+ }
+ else
+ {
+ return nil;
+ }
if ([[UIScreen mainScreen] respondsToSelector:@selector(scale)])
{
@@ -13,18 +13,49 @@
@protocol SDWebImageDecoderDelegate;
+/**
+ * Decoding image data is the most expensive step, and it is performed on the main thread. SDWebImageDecoder force the
+ * image decoding in a separate thread so UIImage will have high chance to reuse the cached result when used by UI in
+ * the main thread.
+ *
+ * @see https://github.com/rs/SDWebImage/pull/18
+ */
+
@interface SDWebImageDecoder : NSObject
{
NSOperationQueue *imageDecodingQueue;
}
+/**
+ * Returns a shared global instance of image decoder
+ *
+ * @return An SDWebImageDecoder shared instance
+ */
+ (SDWebImageDecoder *)sharedImageDecoder;
+
+/**
+ * Pre-decode a given image in a separate thread.
+ *
+ * @param image The image to pre-decode
+ * @param delegate The object to notify once pre-decoding is completed
+ * @param info A user info object
+ */
- (void)decodeImage:(UIImage *)image withDelegate:(id <SDWebImageDecoderDelegate>)delegate userInfo:(NSDictionary *)info;
@end
+/**
+ * Delegate protocol for SDWebImageDecoder
+ */
@protocol SDWebImageDecoderDelegate <NSObject>
+/**
+ * Called when pre-decoding is completed
+ *
+ * @param decoder The image decoder instance
+ * @param image The pre-decoded image
+ * @param userInfo the provided user info dictionary
+ */
- (void)imageDecoder:(SDWebImageDecoder *)decoder didFinishDecodingImage:(UIImage *)image userInfo:(NSDictionary *)userInfo;
@end
@@ -13,6 +13,9 @@
extern NSString *const SDWebImageDownloadStartNotification;
extern NSString *const SDWebImageDownloadStopNotification;
+/**
+ * Asynchronous downloader dedicated and optimized for image loading.
+ */
@interface SDWebImageDownloader : NSObject
{
@private
@@ -32,12 +35,41 @@ extern NSString *const SDWebImageDownloadStopNotification;
@property (nonatomic, retain) NSMutableData *imageData;
@property (nonatomic, retain) id userInfo;
@property (nonatomic, readwrite) BOOL lowPriority;
+
+/**
+ * If set to YES, enables progressive download support.
+ *
+ * The [SDWebImageDownloaderDelegate imageDownloader:didUpdatePartialImage:] delegate method is then called
+ * while the image is downloaded with an image object containing the portion of the currently downloaded
+ * image.
+ *
+ * @see http://www.cocoaintheshell.com/2011/05/progressive-images-download-imageio/
+ */
@property (nonatomic, readwrite) BOOL progressive;
+/**
+ * Creates a SDWebImageDownloader async downloader instance with a given URL
+ *
+ * The delegate will be informed when the image is finish downloaded or an error has happen.
+ *
+ * @see SDWebImageDownloaderDelegate
+ *
+ * @param url The URL to the image to download
+ * @param delegate The delegate object
+ * @param userInfo A NSDictionary containing custom info
+ * @param lowPriority Ensure the download won't run during UI interactions
+ *
+ * @return A new SDWebImageDownloader instance
+ */
+ (id)downloaderWithURL:(NSURL *)url delegate:(id<SDWebImageDownloaderDelegate>)delegate userInfo:(id)userInfo lowPriority:(BOOL)lowPriority;
+ (id)downloaderWithURL:(NSURL *)url delegate:(id<SDWebImageDownloaderDelegate>)delegate userInfo:(id)userInfo;
+ (id)downloaderWithURL:(NSURL *)url delegate:(id<SDWebImageDownloaderDelegate>)delegate;
+
- (void)start;
+
+/**
+ * Cancel the download immediatelly
+ */
- (void)cancel;
// This method is now no-op and is deprecated
@@ -10,13 +10,37 @@
@class SDWebImageDownloader;
+/**
+ * Delegate protocol for SDWebImageDownloader
+ */
@protocol SDWebImageDownloaderDelegate <NSObject>
@optional
- (void)imageDownloaderDidFinish:(SDWebImageDownloader *)downloader;
+
+/**
+ * Called repeatedly while the image is downloading when [SDWebImageDownloader progressive] is enabled.
+ *
+ * @param downloader The SDWebImageDownloader instance
+ * @param image The partial image representing the currently download portion of the image
+ */
- (void)imageDownloader:(SDWebImageDownloader *)downloader didUpdatePartialImage:(UIImage *)image;
+
+/**
+ * Called when download completed successfuly.
+ *
+ * @param downloader The SDWebImageDownloader instance
+ * @param image The downloaded image object
+ */
- (void)imageDownloader:(SDWebImageDownloader *)downloader didFinishWithImage:(UIImage *)image;
+
+/**
+ * Called when an error occurred
+ *
+ * @param downloader The SDWebImageDownloader instance
+ * @param error The error details
+ */
- (void)imageDownloader:(SDWebImageDownloader *)downloader didFailWithError:(NSError *)error;
@end
Oops, something went wrong.

0 comments on commit 1107996

Please sign in to comment.