Merge pull request #400 from BB9z/fix/document-parameter

Some document improves.

SDWebImage/SDWebImageDownloader.h

@@ -82,8 +82,8 @@ typedef void(^SDWebImageDownloaderCompletedBlock)(UIImage *image, NSData *data,
  *
  * @param url The URL to the image to download
  * @param options The options to be used for this download
- * @param progress A block called repeatedly while the image is downloading
+ * @param progressBlock A block called repeatedly while the image is downloading
- * @param completed A block called once the download is completed.
+ * @param completedBlock A block called once the download is completed.
  *                  If the download succeeded, the image parameter is set, in case of error,
  *                  error parameter is set with the error. The last parameter is always YES
  *                  if SDWebImageDownloaderProgressiveDownload isn't use. With the

SDWebImage/SDWebImageManager.h

@@ -85,18 +85,21 @@ typedef void(^SDWebImageCompletedWithFinishedBlock)(UIImage *image, NSError *err
  *
  * Here is a simple example of how to use SDWebImageManager:
  *
- *  SDWebImageManager *manager = [SDWebImageManager sharedManager];
+ * @code
- *  [manager downloadWithURL:imageURL
+
- *                  delegate:self
+SDWebImageManager *manager = [SDWebImageManager sharedManager];
- *                   options:0
+[manager downloadWithURL:imageURL
- *                  progress:nil
+                 options:0
- *                 completed:^(UIImage *image, NSError *error, BOOL fromCache)
+                progress:nil
- *                 {
+               completed:^(UIImage *image, NSError *error, SDImageCacheType cacheType, BOOL finished)
- *                     if (image)
+               {
- *                     {
+                   if (image)
- *                         // do something with image
+                   {
- *                     }
+                       // do something with image
- *                 }];
+                   }
+               }];
+
+ * @endcode
  */
 @interface SDWebImageManager : NSObject
 
@@ -112,11 +115,15 @@ typedef void(^SDWebImageCompletedWithFinishedBlock)(UIImage *image, NSError *err
  * The following example sets a filter in the application delegate that will remove any query-string from the
  * URL before to use it as a cache key:
  *
- * 	[[SDWebImageManager sharedManager] setCacheKeyFilter:^(NSURL *url)
+ * @code
- *	{
+
- *	    url = [[NSURL alloc] initWithScheme:url.scheme host:url.host path:url.path];
+[[SDWebImageManager sharedManager] setCacheKeyFilter:^(NSURL *url)
- *	    return [url absoluteString];
+{
- *	}];
+    url = [[NSURL alloc] initWithScheme:url.scheme host:url.host path:url.path];
+    return [url absoluteString];
+}];
+
+ * @endcode
  */
 @property (strong) NSString *(^cacheKeyFilter)(NSURL *url);
 
@@ -131,21 +138,19 @@ typedef void(^SDWebImageCompletedWithFinishedBlock)(UIImage *image, NSError *err
  * Downloads the image at the given URL if not present in cache or return the cached version otherwise.
  *
  * @param url The URL to the image
- * @param delegate The delegate object used to send result back
  * @param options A mask to specify options to use for this request
  * @param progressBlock A block called while image is downloading
  * @param completedBlock A block called when operation has been completed.
  *
- *                       This block as no return value and takes the requested UIImage as first parameter.
+ *   This block as no return value and takes the requested UIImage as first parameter.
- *                       In case of error the image parameter is nil and the second parameter may contain an NSError.
+ *   In case of error the image parameter is nil and the second parameter may contain an NSError.
  *
- *                       The third parameter is a Boolean indicating if the image was retrived from the local cache
+ *   The third parameter is an `SDImageCacheType` enum indicating if the image was retrived from the local cache
- *                       of from the network.
+ *   or from the memory cache or from the network.
  *
- *                       The last parameter is set to NO when the SDWebImageProgressiveDownload option is used and
+ *   The last parameter is set to NO when the SDWebImageProgressiveDownload option is used and the image is 
- *                       the image is downloading. This block is thus called repetidly with a partial image. When
+ *   downloading. This block is thus called repetidly with a partial image. When image is fully downloaded, the
- *                       image is fully downloaded, the block is called a last time with the full image and the last
+ *   block is called a last time with the full image and the last parameter set to YES.
- *                       parameter set to YES.
  *
  * @return Returns a cancellable NSOperation
  */

SDWebImage/UIButton+WebCache.h

@@ -134,8 +134,10 @@
  *
  * @param url The url for the image.
  * @param state The state that uses the specified title. The values are described in UIControlState.
- * @param success A block to be executed when the image request succeed This block has no return value and takes the retrieved image as argument.
+ * @param completedBlock A block object to be executed after the request operation 
- * @param failure A block object to be executed when the image request failed. This block has no return value and takes the error object describing the network or parsing error that occurred (may be nil).
+ *   completed. This block has no return value and takes three argument: the requested
+ *   `UIImage` object, the `NSError` object describing error that occurred, and an 
+ *   `SDImageCacheType` enum describing the source of the image obtained from.
  */
 - (void)setBackgroundImageWithURL:(NSURL *)url forState:(UIControlState)state completed:(SDWebImageCompletedBlock)completedBlock;
 
@@ -147,8 +149,10 @@
  * @param url The url for the image.
  * @param state The state that uses the specified title. The values are described in UIControlState.
  * @param placeholder The image to be set initially, until the image request finishes.
- * @param success A block to be executed when the image request succeed This block has no return value and takes the retrieved image as argument.
+ * @param completedBlock A block object to be executed after the request operation
- * @param failure A block object to be executed when the image request failed. This block has no return value and takes the error object describing the network or parsing error that occurred (may be nil).
+ *   completed. This block has no return value and takes three argument: the requested
+ *   `UIImage` object, the `NSError` object describing error that occurred, and an
+ *   `SDImageCacheType` enum describing the source of the image obtained from.
  */
 - (void)setBackgroundImageWithURL:(NSURL *)url forState:(UIControlState)state placeholderImage:(UIImage *)placeholder completed:(SDWebImageCompletedBlock)completedBlock;
 
@@ -160,8 +164,10 @@
  * @param url The url for the image.
  * @param placeholder The image to be set initially, until the image request finishes.
  * @param options The options to use when downloading the image. @see SDWebImageOptions for the possible values.
- * @param success A block to be executed when the image request succeed This block has no return value and takes the retrieved image as argument.
+ * @param completedBlock A block object to be executed after the request operation
- * @param failure A block object to be executed when the image request failed. This block has no return value and takes the error object describing the network or parsing error that occurred (may be nil).
+ *   completed. This block has no return value and takes three argument: the requested
+ *   `UIImage` object, the `NSError` object describing error that occurred, and an
+ *   `SDImageCacheType` enum describing the source of the image obtained from.
  */
 - (void)setBackgroundImageWithURL:(NSURL *)url forState:(UIControlState)state placeholderImage:(UIImage *)placeholder options:(SDWebImageOptions)options completed:(SDWebImageCompletedBlock)completedBlock;
 

SDWebImage/UIImageView+WebCache.h

@@ -14,32 +14,34 @@
  *
  * Usage with a UITableViewCell sub-class:
  *
- * 	#import <SDWebImage/UIImageView+WebCache.h>
+ * @code
- * 	
+
- * 	...
+#import <SDWebImage/UIImageView+WebCache.h>
- * 	
+
- * 	- (UITableViewCell *)tableView:(UITableView *)tableView
+...
- * 	         cellForRowAtIndexPath:(NSIndexPath *)indexPath
+
- * 	{
+- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath
- * 	    static NSString *MyIdentifier = @"MyIdentifier";
+{
- * 	
+    static NSString *MyIdentifier = @"MyIdentifier";
- * 	    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:MyIdentifier];
+ 
- * 	
+    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:MyIdentifier];
- * 	    if (cell == nil)
+ 
- * 	    {
+    if (cell == nil)
- * 	        cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault
+    {
- * 	                                       reuseIdentifier:MyIdentifier] autorelease];
+        cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault reuseIdentifier:MyIdentifier]
- * 	    }
+                 autorelease];
- * 	
+    }
- * 	    // Here we use the provided setImageWithURL: method to load the web image
+ 
- * 	    // Ensure you use a placeholder image otherwise cells will be initialized with no image
+    // Here we use the provided setImageWithURL: method to load the web image
- * 	    [cell.imageView setImageWithURL:[NSURL URLWithString:@"http://example.com/image.jpg"]
+    // Ensure you use a placeholder image otherwise cells will be initialized with no image
- * 	                   placeholderImage:[UIImage imageNamed:@"placeholder"]];
+    [cell.imageView setImageWithURL:[NSURL URLWithString:@"http://example.com/image.jpg"]
- * 	
+                   placeholderImage:[UIImage imageNamed:@"placeholder"]];
- * 	    cell.textLabel.text = @"My Text";
+ 
- * 	    return cell;
+    cell.textLabel.text = @"My Text";
- * 	}
+    return cell;
- * 	
+}
+
+ * @endcode
  */
 @interface UIImageView (WebCache)