Further documentation revisions

AFNetworking/AFHTTPRequestOperation.h

@@ -39,7 +39,7 @@
 ///----------------------------------------------
 
 /**
- The last response received by the operation's connection.
+ The last HTTP response received by the operation's connection.
  */
 @property (readonly, nonatomic, retain) NSHTTPURLResponse *response;
 

AFNetworking/AFImageCache.h

@@ -26,7 +26,7 @@
 #import <Availability.h>
 
 /**
- `AFImageCache` is a subclass of `NSCache` that stores and retrieves images from cache.
+ `AFImageCache` is an `NSCache` that stores and retrieves images from cache.
  
  @discussion `AFImageCache` is used to cache images for successful `AFImageRequestOperations` with the proper cache policy.
  */

AFNetworking/AFImageRequestOperation.h

@@ -32,10 +32,22 @@
 #endif
 
 /**
- `AFImageRequestOperation` is an `NSOperation` that wraps the callback from `AFHTTPRequestOperation` to create an image from the response body, and optionally cache the image to memory.
+ `AFImageRequestOperation` is a subclass of `AFHTTPRequestOperation` for downloading an processing images.
  
- @see NSOperation
- @see AFHTTPRequestOperation
+ ## Acceptable Content Types
+ 
+ By default, `AFImageRequestOperation` accepts the following MIME types, which correspond to the image formats supported by UIImage or NSImage:
+ 
+ - `image/tiff`
+ - `image/jpeg`
+ - `image/gif`
+ - `image/png`
+ - `image/ico`
+ - `image/x-icon`
+ - `image/bmp`
+ - `image/x-bmp`
+ - `image/x-xbitmap`
+ - `image/x-win-bitmap`
  */
 @interface AFImageRequestOperation : AFHTTPRequestOperation {
 @private
@@ -56,7 +68,7 @@
  Creates and returns an `AFImageRequestOperation` object and sets the specified success callback.
  
  @param urlRequest The request object to be loaded asynchronously during execution of the operation.
- @param success A block object to be executed when the request finishes successfully, with a status code in the 2xx range, and with an acceptable content type (e.g. `image/png`). This block has no return value and takes a single arguments, the image created from the response data of the request.
+ @param success A block object to be executed when the request finishes successfully. This block has no return value and takes a single arguments, the image created from the response data of the request.
  
  @return A new image request operation
  */

AFNetworking/AFJSONRequestOperation.h

@@ -24,7 +24,14 @@
 #import "AFHTTPRequestOperation.h"
 
 /**
- `AFJSONRequestOperation` is a subclass of `AFHTTPRequestOperation` that provides functionality to work with JSON response data.
+ `AFJSONRequestOperation` is a subclass of `AFHTTPRequestOperation` for downloading and working with JSON response data.
+ 
+ ## Acceptable Content Types
+ 
+ By default, `AFJSONRequestOperation` accepts the following MIME types, which includes the official standard, `application/json`, as well as other commonly-used types:
+ 
+ - `application/json`
+ - `text/json`
  */
 @interface AFJSONRequestOperation : AFHTTPRequestOperation {
 @private

AFNetworking/AFJSONRequestOperation.m

@@ -88,7 +88,7 @@ static dispatch_queue_t json_request_operation_processing_queue() {
 }
 
 + (NSSet *)defaultAcceptableContentTypes {
-    return [NSSet setWithObjects:@"application/json", @"application/x-javascript", @"text/javascript", @"text/x-javascript", @"text/x-json", @"text/json", @"text/plain", nil];
+    return [NSSet setWithObjects:@"application/json", @"text/json", nil];
 }
 
 + (NSSet *)defaultAcceptablePathExtensions {

AFNetworking/AFPropertyListRequestOperation.h

@@ -24,7 +24,13 @@
 #import "AFHTTPRequestOperation.h"
 
 /**
- `AFPropertyListRequestOperation` is a subclass of `AFHTTPRequestOperation` that provides functionality to work with Property List (plist) response data.
+ `AFPropertyListRequestOperation` is a subclass of `AFHTTPRequestOperation` for downloading and deserializing objects with property list (plist) response data.
+ 
+ ## Acceptable Content Types
+ 
+ By default, `AFPropertyListRequestOperation` accepts the following MIME types:
+ 
+ - `application/x-plist`
  */
 @interface AFPropertyListRequestOperation : AFHTTPRequestOperation {
 @private

AFNetworking/AFPropertyListRequestOperation.m

@@ -85,7 +85,7 @@ static dispatch_queue_t property_list_request_operation_processing_queue() {
 }
 
 + (NSSet *)defaultAcceptableContentTypes {
-    return [NSSet setWithObjects:@"application/x-plist", @"application/xml", nil];
+    return [NSSet setWithObjects:@"application/x-plist", nil];
 }
 
 + (NSSet *)defaultAcceptablePathExtensions {
@@ -98,7 +98,7 @@ static dispatch_queue_t property_list_request_operation_processing_queue() {
         return nil;
     }
     
-    self.acceptableContentTypes = [NSSet setWithObjects:@"application/x-plist", @"application/xml", nil];
+    self.acceptableContentTypes = [[self class] defaultAcceptableContentTypes];
     
     self.propertyListReadOptions = NSPropertyListImmutable;
     

AFNetworking/AFURLConnectionOperation.h

@@ -40,7 +40,7 @@ extern NSString * const AFNetworkingOperationDidStartNotification;
 extern NSString * const AFNetworkingOperationDidFinishNotification;
 
 /**
- `AFURLConnectionOperation` is an `NSOperation` that implements the NSURLConnection delegate methods, and provides a simple block-based interface to asynchronously get the result and context of that operation finishes.
+ `AFURLConnectionOperation` is an `NSOperation` that implements NSURLConnection delegate methods.
  
  ## Subclassing Notes
  
@@ -65,13 +65,13 @@ extern NSString * const AFNetworkingOperationDidFinishNotification;
  
  ## Class Constructors
  
- Class constructors, or methods that return a zero-retain-count instance, are the preferred way for subclasses to encapsulate any particular logic for handling the setup or parsing of response data. For instance, `AFJSONRequestOperation` provides `JSONRequestOperationWithRequest:success:failure:`, which takes block arguments, whose parameter on for a successful request is the JSON object initialized from the `response data`.
+ Class constructors, or methods that return an unowned (zero retain count) instance, are the preferred way for subclasses to encapsulate any particular logic for handling the setup or parsing of response data. For instance, `AFJSONRequestOperation` provides `JSONRequestOperationWithRequest:success:failure:`, which takes block arguments, whose parameter on for a successful request is the JSON object initialized from the `response data`.
  
  ## Callbacks and Completion Blocks
  
- The built-in `completionBlock` provided by `NSOperation` allows for custom behavior to be executed after the request finishes. It is a common pattern for class constructors in subclasses to take callback block parameters, and execute them conditionally in the body of its `completionBlock`. See the implementation of any of the `AFHTTPRequestOperation` subclasses for an example of this.
+ The built-in `completionBlock` provided by `NSOperation` allows for custom behavior to be executed after the request finishes. It is a common pattern for class constructors in subclasses to take callback block parameters, and execute them conditionally in the body of its `completionBlock`. Make sure to handle cancelled operations appropriately when setting a `completionBlock` (e.g. returning early before parsing response data). See the implementation of any of the `AFHTTPRequestOperation` subclasses for an example of this.
  
- One common oversight when setting completion blocks is to forget to check for whether the operation was cancelled. Be sure to handle called operations appropriately (e.g. returning early before parsing response data).
+ @warning Subclasses are strongly discouraged from overriding `setCompletionBlock:`, as `AFURLConnectionOperation`'s implementation includes a particular workaround to mitigate retain cycles, and what Apple rather ominously refers to as "The Deallocation Problem" (See http://developer.apple.com/library/ios/technotes/tn2109/_index.html#//apple_ref/doc/uid/DTS40010274-CH1-SUBSECTION11) 
  */
 @interface AFURLConnectionOperation : NSOperation {
 @private

AFNetworking/AFXMLRequestOperation.h

@@ -26,7 +26,14 @@
 #import <Availability.h>
 
 /**
- `AFXMLRequestOperation` is a subclass of `AFHTTPRequestOperation` that provides functionality to work with XML response data.
+ `AFXMLRequestOperation` is a subclass of `AFHTTPRequestOperation` for downloading and working with XML response data.
+ 
+ ## Acceptable Content Types
+ 
+ By default, `AFXMLRequestOperation` accepts the following MIME types, which includes the official standard, `application/xml`, as well as other commonly-used types:
+ 
+ - `application/xml`
+ - `text/xml`
  */
 @interface AFXMLRequestOperation : AFHTTPRequestOperation {
 @private