From c492d488d87b9d7101cf41cd437f2855130d9c0f Mon Sep 17 00:00:00 2001 From: Mattt Thompson Date: Wed, 12 Oct 2011 10:42:53 -0500 Subject: [PATCH] Further documentation revisions --- AFNetworking/AFHTTPRequestOperation.h | 2 +- AFNetworking/AFImageCache.h | 2 +- AFNetworking/AFImageRequestOperation.h | 20 +++++++++++++++---- AFNetworking/AFJSONRequestOperation.h | 9 ++++++++- AFNetworking/AFJSONRequestOperation.m | 2 +- AFNetworking/AFPropertyListRequestOperation.h | 8 +++++++- AFNetworking/AFPropertyListRequestOperation.m | 4 ++-- AFNetworking/AFURLConnectionOperation.h | 8 ++++---- AFNetworking/AFXMLRequestOperation.h | 9 ++++++++- 9 files changed, 48 insertions(+), 16 deletions(-) diff --git a/AFNetworking/AFHTTPRequestOperation.h b/AFNetworking/AFHTTPRequestOperation.h index 73ceef8..d93ea67 100644 --- a/AFNetworking/AFHTTPRequestOperation.h +++ b/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; diff --git a/AFNetworking/AFImageCache.h b/AFNetworking/AFImageCache.h index 8c16508..94fed9f 100644 --- a/AFNetworking/AFImageCache.h +++ b/AFNetworking/AFImageCache.h @@ -26,7 +26,7 @@ #import /** - `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. */ diff --git a/AFNetworking/AFImageRequestOperation.h b/AFNetworking/AFImageRequestOperation.h index 06e130d..d18b6be 100644 --- a/AFNetworking/AFImageRequestOperation.h +++ b/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 */ diff --git a/AFNetworking/AFJSONRequestOperation.h b/AFNetworking/AFJSONRequestOperation.h index bba9742..b489343 100644 --- a/AFNetworking/AFJSONRequestOperation.h +++ b/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 diff --git a/AFNetworking/AFJSONRequestOperation.m b/AFNetworking/AFJSONRequestOperation.m index ac98f52..2af8624 100644 --- a/AFNetworking/AFJSONRequestOperation.m +++ b/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 { diff --git a/AFNetworking/AFPropertyListRequestOperation.h b/AFNetworking/AFPropertyListRequestOperation.h index 23063d8..bc02738 100644 --- a/AFNetworking/AFPropertyListRequestOperation.h +++ b/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 diff --git a/AFNetworking/AFPropertyListRequestOperation.m b/AFNetworking/AFPropertyListRequestOperation.m index 4a32fc3..01a81b1 100644 --- a/AFNetworking/AFPropertyListRequestOperation.m +++ b/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; diff --git a/AFNetworking/AFURLConnectionOperation.h b/AFNetworking/AFURLConnectionOperation.h index eb17580..210ac43 100644 --- a/AFNetworking/AFURLConnectionOperation.h +++ b/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 diff --git a/AFNetworking/AFXMLRequestOperation.h b/AFNetworking/AFXMLRequestOperation.h index 12c262e..441a841 100644 --- a/AFNetworking/AFXMLRequestOperation.h +++ b/AFNetworking/AFXMLRequestOperation.h @@ -26,7 +26,14 @@ #import /** - `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