Skip to content
Browse files

Updating and revising documentation

  • Loading branch information...
1 parent fdf217e commit 58693e8d8c73524f7467565428c1b8f3c79468ec @mattt mattt committed Nov 11, 2011
View
20 AFNetworking/AFHTTPClient.h
@@ -306,8 +306,8 @@ extern NSString * AFQueryStringFromParametersWithEncoding(NSDictionary *paramete
@param path The path to be appended to the HTTP client's base URL and used as the request URL.
@param parameters The parameters to be encoded and appended as the query string for the request URL.
- @param success A block object to be executed when the request operation finishes successfully, with a status code in the 2xx range, and with an acceptable content type (e.g. `application/json`). This block has no return value and takes a single argument, which is the response object created from the response data of request.
- @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data as JSON. This block has no return value and takes a single argument, which is the `NSError` object describing the network or parsing error that occurred.
+ @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the created request operation and the object created from the response data of request.
+ @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the `NSError` object describing the network or parsing error that occurred.
@see HTTPRequestOperationWithRequest:success:failure
*/
@@ -321,8 +321,8 @@ extern NSString * AFQueryStringFromParametersWithEncoding(NSDictionary *paramete
@param path The path to be appended to the HTTP client's base URL and used as the request URL.
@param parameters The parameters to be encoded and set in the request HTTP body.
- @param success A block object to be executed when the request operation finishes successfully, with a status code in the 2xx range, and with an acceptable content type (e.g. `application/json`). This block has no return value and takes a single argument, which is the response object created from the response data of request.
- @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data as JSON. This block has no return value and takes a single argument, which is the `NSError` object describing the network or parsing error that occurred.
+ @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the created request operation and the object created from the response data of request.
+ @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the `NSError` object describing the network or parsing error that occurred.
@see HTTPRequestOperationWithRequest:success:failure
*/
@@ -336,8 +336,8 @@ extern NSString * AFQueryStringFromParametersWithEncoding(NSDictionary *paramete
@param path The path to be appended to the HTTP client's base URL and used as the request URL.
@param parameters The parameters to be encoded and set in the request HTTP body.
- @param success A block object to be executed when the request operation finishes successfully, with a status code in the 2xx range, and with an acceptable content type (e.g. `application/json`). This block has no return value and takes a single argument, which is the response object created from the response data of request.
- @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data as JSON. This block has no return value and takes a single argument, which is the `NSError` object describing the network or parsing error that occurred.
+ @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the created request operation and the object created from the response data of request.
+ @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the `NSError` object describing the network or parsing error that occurred.
@see HTTPRequestOperationWithRequest:success:failure
*/
@@ -351,8 +351,8 @@ extern NSString * AFQueryStringFromParametersWithEncoding(NSDictionary *paramete
@param path The path to be appended to the HTTP client's base URL and used as the request URL.
@param parameters The parameters to be encoded and set in the request HTTP body.
- @param success A block object to be executed when the request operation finishes successfully, with a status code in the 2xx range, and with an acceptable content type (e.g. `application/json`). This block has no return value and takes a single argument, which is the response object created from the response data of request.
- @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data as JSON. This block has no return value and takes a single argument, which is the `NSError` object describing the network or parsing error that occurred.
+ @param success A block object to be executed when the request operation finishes successfully. This block has no return value and takes two arguments: the created request operation and the object created from the response data of request.
+ @param failure A block object to be executed when the request operation finishes unsuccessfully, or that finishes successfully, but encountered an error while parsing the resonse data. This block has no return value and takes two arguments:, the created request operation and the `NSError` object describing the network or parsing error that occurred.
@see HTTPRequestOperationWithRequest:success:failure
*/
@@ -368,7 +368,6 @@ extern NSString * AFQueryStringFromParametersWithEncoding(NSDictionary *paramete
The `AFMultipartFormData` protocol defines the methods supported by the parameter in the block argument of `multipartFormRequestWithMethod:path:parameters:constructingBodyWithBlock:`.
@see `AFHTTPClient -multipartFormRequestWithMethod:path:parameters:constructingBodyWithBlock:`
-
*/
@protocol AFMultipartFormData
@@ -395,11 +394,9 @@ extern NSString * AFQueryStringFromParametersWithEncoding(NSDictionary *paramete
@param name The name to be associated with the specified data. This parameter must not be `nil`.
@param mimeType The MIME type of the specified data. (For example, the MIME type for a JPEG image is image/jpeg.) For a list of valid MIME types, see http://www.iana.org/assignments/media-types/. This parameter must not be `nil`.
@param name The filename to be associated with the specified data. This parameter must not be `nil`.
-
*/
- (void)appendPartWithFileData:(NSData *)data name:(NSString *)name fileName:(NSString *)fileName mimeType:(NSString *)mimeType;
-
/**
Appends the HTTP header `Content-Disposition: file; filename=#{generated filename}; name=#{name}"` and `Content-Type: #{generated mimeType}`, followed by the encoded file data and the multipart form boundary.
@@ -426,5 +423,6 @@ extern NSString * AFQueryStringFromParametersWithEncoding(NSDictionary *paramete
@param string The string to be encoded and appended to the form data.
*/
- (void)appendString:(NSString *)string;
+
@end
View
5 AFNetworking/AFHTTPRequestOperation.h
@@ -83,7 +83,12 @@
///-----------------------------------------------------------
/**
+ Sets the `completionBlock` property with a block that executes either the specified success or failure block, depending on the state of the request on completion. If `error` returns a value, which can be caused by an unacceptable status code or content type, then `failure` is executed. Otherwise, `success` is executed.
+ @param success The block to be executed on the completion of a successful request. This block has no return value and takes two arguments: the receiver operation and the object constructed from the response data of the request.
+ @param failure The block to be executed on the completion of an unsuccessful request. This block has no return value and takes two arguments: the receiver operation and the error that occured during the request.
+
+ @discussion This method should be overridden in subclasses in order to specify the response object passed into the success block.
*/
- (void)setCompletionBlockWithSuccess:(void (^)(AFHTTPRequestOperation *operation, id responseObject))success
failure:(void (^)(AFHTTPRequestOperation *operation, NSError *error))failure;
View
1 AFNetworking/AFImageCache.h
@@ -47,7 +47,6 @@
@return The image associated with the URL and cache name, or `nil` if not image exists.
*/
-
#if __IPHONE_OS_VERSION_MIN_REQUIRED
- (UIImage *)cachedImageForURL:(NSURL *)url
cacheName:(NSString *)cacheName;
View
10 AFNetworking/AFImageRequestOperation.h
@@ -59,23 +59,25 @@
#endif
}
-#if __IPHONE_OS_VERSION_MIN_REQUIRED
/**
An image constructed from the response data. If an error occurs during the request, `nil` will be returned, and the `error` property will be set to the error.
*/
+#if __IPHONE_OS_VERSION_MIN_REQUIRED
@property (readonly, nonatomic, retain) UIImage *responseImage;
+#elif __MAC_OS_X_VERSION_MIN_REQUIRED
+@property (readonly, nonatomic, retain) NSImage *responseImage;
+#endif
+#if __IPHONE_OS_VERSION_MIN_REQUIRED
/**
The scale factor used when interpreting the image data to construct `responseImage`. Specifying a scale factor of 1.0 results in an image whose size matches the pixel-based dimensions of the image. Applying a different scale factor changes the size of the image as reported by the size property. This is set to the value of `[[UIScreen mainScreen] scale]` by default, which automatically scales images for retina displays, for instance.
*/
@property (nonatomic, assign) CGFloat imageScale;
-#elif __MAC_OS_X_VERSION_MIN_REQUIRED
+#endif
/**
An image constructed from the response data. If an error occurs during the request, `nil` will be returned, and the `error` property will be set to the error.
*/
-@property (readonly, nonatomic, retain) NSImage *responseImage;
-#endif
/**
Creates and returns an `AFImageRequestOperation` object and sets the specified success callback.
View
1 AFNetworking/AFJSONRequestOperation.h
@@ -64,4 +64,5 @@
+ (AFJSONRequestOperation *)JSONRequestOperationWithRequest:(NSURLRequest *)urlRequest
success:(void (^)(NSURLRequest *request, NSURLResponse *response, id JSON))success
failure:(void (^)(NSURLRequest *request, NSURLResponse *response, NSError *error, id JSON))failure;
+
@end
View
1 AFNetworking/AFNetworkActivityIndicatorManager.h
@@ -62,4 +62,5 @@
- (void)decrementActivityCount;
@end
+
#endif
View
1 AFNetworking/AFNetworkActivityIndicatorManager.m
@@ -110,4 +110,5 @@ - (void)decrementActivityCount {
}
@end
+
#endif
View
6 AFNetworking/AFURLConnectionOperation.h
@@ -46,7 +46,7 @@ extern NSString * const AFNetworkingOperationDidFinishNotification;
This is the base class of all network request operations. You may wish to create your own subclass in order to implement additional `NSURLConnection` delegate methods (see "`NSURLConnection` Delegate Methods" below), or to provide additional properties and/or class constructors.
- If you are creating a subclass that communicates over the HTTP or HTTPS protocols, you may want to consider subclassing `AFHTTPRequestOperation`, which supports specifying acceptable content types or status codes.
+ If you are creating a subclass that communicates over the HTTP or HTTPS protocols, you may want to consider subclassing `AFHTTPRequestOperation` instead, as it supports specifying acceptable content types or status codes.
## NSURLConnection Delegate Methods
@@ -71,7 +71,7 @@ extern NSString * const AFNetworkingOperationDidFinishNotification;
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.
- @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)
+ @warning Subclasses are strongly discouraged from overriding `setCompletionBlock:`, as `AFURLConnectionOperation`'s implementation includes a 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
@@ -185,4 +185,4 @@ extern NSString * const AFNetworkingOperationDidFinishNotification;
*/
- (void)setDownloadProgressBlock:(void (^)(NSInteger bytesRead, NSInteger totalBytesRead, NSInteger totalBytesExpectedToRead))block;
-@end
+@end
View
1 AFNetworking/UIImageView+AFNetworking.h
@@ -71,4 +71,5 @@
- (void)cancelImageRequestOperation;
@end
+
#endif
View
1 AFNetworking/UIImageView+AFNetworking.m
@@ -129,4 +129,5 @@ - (void)cancelImageRequestOperation {
}
@end
+
#endif

0 comments on commit 58693e8

Please sign in to comment.
Something went wrong with that request. Please try again.