Further additions to AFRestClient documentation

AFNetworking/AFHTTPRequestOperation.h

@@ -86,7 +86,7 @@ extern NSString * const AFHTTPOperationDidFinishNotification;
 /**
  Creates and returns an `AFHTTPRequestOperation` object and sets the specified completion callback.
  
- @param urlRequest The request object to be loaded asynchronously during execution of the operation
+ @param urlRequest The request object to be loaded asynchronously during execution of the operation.
  @param completion A block object to be executed when the HTTP request operation is finished. This block has no return value and takes four arguments: the NSURLRequest sent from the client and the NSHTTPURLResponse received from the server, the NSData received by the server during the execution of the request, and an NSError, which will have been set if an error occured while loading the request.
  
  @see operationWithRequest:inputStream:outputStream:completion
@@ -97,9 +97,9 @@ extern NSString * const AFHTTPOperationDidFinishNotification;
                                       completion:(void (^)(NSURLRequest *request, NSHTTPURLResponse *response, NSData *data, NSError *error))completion;
 
 /**
- Creates and returns an `AFHTTPRequestOperation` object and sets the specified input and output streams, and completion callback.
+ Creates and returns a streaming `AFHTTPRequestOperation` object and sets the specified input and output streams, and completion callback.
  
- @param urlRequest The request object to be loaded asynchronously during execution of the operation
+ @param urlRequest The request object to be loaded asynchronously during execution of the operation.
  @param inputStream The input stream object for reading data to be sent during the request. If set, the input stream is set as the HTTPBodyStream on the NSMutableURLRequest, and the request method is changed to `POST`. This argument may be `nil`.
  @param outputStream The output stream object for writing data received during the request. If set, data accumulated in NSURLConnectionDelegate methods will be sent to the output stream, and the NSData parameter in the completion block will be `nil`. This argument may be `nil`.
  @param completion A block object to be executed when the HTTP request operation is finished. This block has no return value and takes four arguments: the NSURLRequest sent from the client and the NSHTTPURLResponse received from the server, the NSData received by the server during the execution of the request, and an NSError, which will have been set if an error occured while loading the request. This argument may be `NULL`.

AFNetworking/AFRestClient.h

@@ -34,12 +34,18 @@
 }
 
 /**
- An `NSURL` object that is used as the base for paths specified in methods such as `getPath:parameteres:success:failure`
+ The url used as the base for paths specified in methods such as `getPath:parameteres:success:failure`
  */
 @property (readonly, nonatomic, retain) NSURL *baseURL;
 
+/**
+ The string encoding used in constructing url requests. This is `NSUTF8StringEncoding` by default.
+ */
 @property (nonatomic, assign) NSStringEncoding stringEncoding;
 
+/**
+ The operation queue which manages operations enqueued by the REST client.
+ */
 @property (readonly, nonatomic, retain) NSOperationQueue *operationQueue;;
 
 ///--------------------------------
@@ -101,17 +107,29 @@
 ///-------------------------------
 
 /**
- Creates an `NSMutableURLRequest` object with the specified HTTP method, resource path, and parameters, with the default HTTP headers specified for the client.
+ Creates an `NSMutableURLRequest` object with the specified HTTP method and resource path. If the HTTP method is `GET`, the parameters will be used to construct a url-encoded query string that is appended to the request's URL. If `POST`, `PUT`, or `DELETE`, the parameters will be encoded into a `application/x-www-form-urlencoded` HTTP body.
  
- @param method The HTTP method for the request, such as `GET`, `POST`, `PUT`, or `DELETE`
- @param path The resource path to be appended to the REST client's base URL and used as the request URL
- @param parameters The parameters to be either set as a query string for `GET` requests, or form URL-encoded and set in the request HTTP body
+ @param method The HTTP method for the request, such as `GET`, `POST`, `PUT`, or `DELETE`.
+ @param path The resource path to be appended to the REST client's base URL and used as the request URL.
+ @param parameters The parameters to be either set as a query string for `GET` requests, or the request HTTP body.
  
  @return An `NSMutableURLRequest` object
  */
 - (NSMutableURLRequest *)requestWithMethod:(NSString *)method 
                                       path:(NSString *)path parameters:(NSDictionary *)parameters;
 
+/**
+ Creates an `NSMutableURLRequest` object with the specified HTTP method and resource path, and constructs a `multipart/form-data` HTTP body, using the specified parameters and multipart form data block.
+ 
+ @param method The HTTP method for the request. Must be either `POST`, `PUT`, or `DELETE`.
+ @param path The resource path to be appended to the REST 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 block A block that takes a single argument and appends data to the HTTP body. The block argument is an object adopting the `AFMultipartFormDataProxy` protocol. This can be used to upload files, encode HTTP body as JSON or XML, or specify multiple values for the same parameter, as one might for array values.
+ 
+ @see AFMultipartFormDataProxy
+ 
+ @return An `NSMutableURLRequest` object
+ */
 - (NSMutableURLRequest *)multipartFormRequestWithMethod:(NSString *)method
                                                    path:(NSString *)path
                                              parameters:(NSDictionary *)parameters
@@ -121,8 +139,14 @@
 ///--------------------------------
 /// @name Enqueuing HTTP Operations
 ///--------------------------------
-- (void)enqueueHTTPOperation:(AFHTTPRequestOperation *)operation;
 
+/**
+ Constructs and enqueues an `AFHTTPRequestOperation` to the REST client's operation queue.
+ 
+ @param request The request object to be loaded asynchronously during execution of the operation.
+ @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 types (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.
+ */
 - (void)enqueueHTTPOperationWithRequest:(NSURLRequest *)request 
                                 success:(void (^)(id response))success 
                                 failure:(void (^)(NSError *error))failure;
@@ -131,9 +155,13 @@
 /// @name Cancelling HTTP Operations
 ///---------------------------------
 
-- (void)cancelHTTPOperationsWithRequest:(NSURLRequest *)request;
-
-- (void)cancelAllHTTPOperations;
+/**
+ Cancels all operations in the REST client's operation queue that match the specified HTTP method and URL.
+ 
+ @param method The HTTP method to match for the cancelled requests, such as `GET`, `POST`, `PUT`, or `DELETE`.
+ @param url The URL to match for the cancelled requests.
+ */
+- (void)cancelHTTPOperationsWithMethod:(NSString *)method andURL:(NSURL *)url;
 
 ///---------------------------
 /// @name Making HTTP Requests

AFNetworking/AFRestClient.m

@@ -222,31 +222,23 @@ static NSString * AFURLEncodedStringFromStringWithEncoding(NSString *string, NSS
     return request;
 }
 
-- (void)enqueueHTTPOperation:(AFHTTPRequestOperation *)operation {
-    [self.operationQueue addOperation:operation];
-}
-
 - (void)enqueueHTTPOperationWithRequest:(NSURLRequest *)request success:(void (^)(id response))success failure:(void (^)(NSError *error))failure {
 	if ([request URL] == nil || [[request URL] isEqual:[NSNull null]]) {
 		return;
 	}
     
     AFHTTPRequestOperation *operation = [AFJSONRequestOperation operationWithRequest:request success:success failure:failure];
-    [self enqueueHTTPOperation:operation];
+    [self.operationQueue addOperation:operation];
 }
 
-- (void)cancelHTTPOperationsWithRequest:(NSURLRequest *)request {
+- (void)cancelHTTPOperationsWithMethod:(NSString *)method andURL:(NSURL *)url {
     for (AFHTTPRequestOperation *operation in [self.operationQueue operations]) {
-        if ([[operation request] isEqual:request]) {
+        if ([[[operation request] HTTPMethod] isEqualToString:method] && [[[operation request] URL] isEqual:url]) {
             [operation cancel];
         }
     }
 }
 
-- (void)cancelAllHTTPOperations {
-    [self.operationQueue cancelAllOperations];
-}
-
 #pragma mark -
 
 - (void)getPath:(NSString *)path parameters:(NSDictionary *)parameters success:(void (^)(id response))success failure:(void (^)(NSError *error))failure {