Adding documentation for AFSerialization

AFNetworking/AFSerialization.h

@@ -25,12 +25,20 @@
 #import "AFHTTPRequestOperation.h"
 
 /**
+ The `AFURLRequestSerialization` protocol is adopted by an object that encodes parameters for a specified HTTP requests. Request serializers may encode parameters as query strings, HTTP bodies, setting the appropriate HTTP header fields as necessary.
  
+ For example, a JSON request serializer may set the HTTP body of the request to a JSON representation, and set the `Content-Type` HTTP header field value to `application/json`.
  */
 @protocol AFURLRequestSerialization <NSCoding, NSCopying>
 
 /**
+ Returns a request with the specified parameters encoded into a copy of the original request.
+
+ @param request The original request.
+ @param parameters The parameters to be encoded.
+ @param error The error that occurred while attempting to encode the request parameters.
  
+ @return A serialized request.
  */
 - (NSURLRequest *)requestBySerializingRequest:(NSURLRequest *)request
                                withParameters:(NSDictionary *)parameters
@@ -39,17 +47,31 @@
 @end
 
 /**
+ The `AFURLResponseSerialization` protocol is adopted by an object that decodes data into a more useful object representation, according to details in the server response. Response serializers may additionally perform validation on the incoming response and data.
  
+ For example, a JSON response serializer may check for an acceptable status code (`2XX` range) and content type (`application/json`), decoding a valid JSON response into an object.
  */
 @protocol AFURLResponseSerialization <NSCoding, NSCopying>
 
 /**
+ Whether the serializer can process the specified response. 
+ 
+ Classes like `AFHTTPRequestOperation` & `AFHTTPClient` are configured with an array of potential response serializers. In order to determine the correct decoding behavior, response serializers perform passed the response to `canProcessResponse` until a serializer returns `YES`.
  
+ @param response The response to be processed.
+ 
+ @return `YES` if the serializer can process the specified response, otherwise `NO`.
  */
 - (BOOL)canProcessResponse:(NSHTTPURLResponse *)response;
 
 /**
+ The response object decoded from the data associated with a specified response.
+ 
+ @param response The response to be processed.
+ @param data The response data to be decoded.
+ @param error The error that occurred while attempting to decode the response data.
  
+ @return The object decoded from the specified response data.
  */
 - (id)responseObjectForResponse:(NSURLResponse *)response
                            data:(NSData *)data
@@ -67,10 +89,15 @@ typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
 };
 
 /**
+ `AFHTTPSerializer` conforms to the `AFURLRequestSerialization` & `AFURLResponseSerialization` protocols, offering a concrete base implementation of query string / URL form-encoded parameter serialization and default request headers, as well as response status code and content type validation.
  
+ Any request or response serializer dealing with HTTP is encouraged to subclass `AFHTTPSerializer` in order to ensure consistent default behavior.
  */
 @interface AFHTTPSerializer : NSObject <AFURLRequestSerialization, AFURLResponseSerialization>
 
+/**
+ The string encoding used to serialize parameters.
+ */
 @property (nonatomic, assign) NSStringEncoding stringEncoding;
 
 #pragma mark AFURLRequestSerialization
@@ -80,12 +107,12 @@ typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
 ///---------------------------------------
 
 /**
- 
+ Default HTTP header field values to be applied to serialized requests. 
  */
 @property (readonly, nonatomic, strong) NSDictionary *HTTPRequestHeaders;
 
 /**
-
+ Creates and returns a serializer with default configuration.
  */
 + (instancetype)serializer;
 
@@ -124,17 +151,23 @@ typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
 ///-------------------------------------------------------
 
 /**
- `GET`, `HEAD`, and `DELETE` by default.
+ HTTP methods for which serialized requests will encode parameters as a query string. `GET`, `HEAD`, and `DELETE` by default.
  */
 @property (nonatomic, strong) NSSet *HTTPMethodsEncodingParametersInURI;
 
 /**
+ Set the method of query string serialization according to one of the pre-defined styles.
  
+ @param style The serialization style.
+ 
+ @see AFHTTPRequestQueryStringSerializationStyle
  */
 - (void)setQueryStringSerializationWithStyle:(AFHTTPRequestQueryStringSerializationStyle)style;
 
 /**
+ Set the a custom method of query string serialization according to the specified block.
  
+ @param block A block that defines a process of encoding parameters into a query string. This block returns the query string and takes three arguments: the request, the parameters to encode, and the error that occured when attempting to encode parameters for the given request.
  */
 - (void)setQueryStringSerializationWithBlock:(NSString * (^)(NSURLRequest *request, NSDictionary *parameters, NSError *__autoreleasing *error))block;
 
@@ -143,17 +176,27 @@ typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
 ///-----------------------------------------
 
 /**
+ The acceptable HTTP status codes for responses. When non-`nil`, responses with status codes not contained by the set will result in an error during validation. 
  
+ See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
  */
 @property (nonatomic, strong) NSIndexSet *acceptableStatusCodes;
 
 /**
- 
+ The acceptable MIME types for responses. When non-`nil`, responses with a `Content-Type` with MIME types that do not intersect with the set will result in an error during validation.
  */
 @property (nonatomic, strong) NSSet *acceptableContentTypes;
 
 /**
+ Validates the specified response and data. 
+ 
+ In its base implementation, this method checks for an acceptable status code and content type. Subclasses may wish to add other domain-specific checks.
+ 
+ @param response The response to be validated.
+ @param data The data associated with the response.
+ @param error The error that occurred while attempting to validate the response.
  
+ @return `YES` if the response is valid, otherwise `NO`.
  */
 - (BOOL)validateResponse:(NSHTTPURLResponse *)response
                     data:(NSData *)data
@@ -164,22 +207,30 @@ typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
 #pragma mark -
 
 /**
+ `AFJSONSerializer` is a subclass of `AFHTTPSerializer` that validates and decodes JSON responses.
  
+ By default, `AFJSONSerializer` accepts the following MIME types, which includes the official standard, `application/json`, as well as other commonly-used types:
+
+ - `application/json`
+ - `text/json`
  */
 @interface AFJSONSerializer : AFHTTPSerializer
 
 /**
- 
+ Options for reading the response JSON data and creating the Foundation objects. For possible values, see the `NSJSONSerialization` documentation section "NSJSONReadingOptions". `0` by default.
  */
 @property (nonatomic, assign) NSJSONReadingOptions readingOptions;
 
 /**
- 
+ Options for writing the request JSON data from Foundation objects. For possible values, see the `NSJSONSerialization` documentation section "NSJSONWritingOptions". `0` by default.
  */
 @property (nonatomic, assign) NSJSONWritingOptions writingOptions;
 
 /**
+ Creates and returns a JSON serializer with specified reading and writing options.
  
+ @param readingOptions The specified JSON reading options.
+ @param writingOptions The specified JSON writing options.
  */
 + (instancetype)serializerWithReadingOptions:(NSJSONReadingOptions)readingOptions
                               writingOptions:(NSJSONWritingOptions)writingOptions;
@@ -189,7 +240,12 @@ typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
 #pragma mark -
 
 /**
+ `AFXMLParserSerializer` is a subclass of `AFHTTPSerializer` that validates and decodes XML responses as an `NSXMLParser` objects.
  
+ By default, `AFXMLParserSerializer` accepts the following MIME types, which includes the official standard, `application/xml`, as well as other commonly-used types:
+
+ - `application/xml`
+ - `text/xml`
  */
 @interface AFXMLParserSerializer : AFHTTPSerializer
 
@@ -199,12 +255,25 @@ typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
 
 #ifdef __MAC_OS_X_VERSION_MIN_REQUIRED
 
+/**
+ `AFXMLDocumentSerializer` is a subclass of `AFHTTPSerializer` that validates and decodes XML responses as an `NSXMLDocument` objects.
+
+ By default, `AFXMLDocumentSerializer` accepts the following MIME types, which includes the official standard, `application/xml`, as well as other commonly-used types:
+
+ - `application/xml`
+ - `text/xml`
+ */
 @interface AFXMLDocumentSerializer : AFHTTPSerializer
 
+/**
+ Input and output options specifically intended for `NSXMLDocument` objects. For possible values, see the `NSJSONSerialization` documentation section "NSJSONReadingOptions". `0` by default.
+ */
 @property (nonatomic, assign) NSUInteger options;
 
 /**
+ Creates and returns an XML document serializer with the specified options.
 
+ @param mask The XML document options.
  */
 + (instancetype)serializerWithXMLDocumentOptions:(NSUInteger)mask;
 
@@ -215,27 +284,35 @@ typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
 #pragma mark -
 
 /**
- 
+ `AFPropertyListSerializer` is a subclass of `AFHTTPSerializer` that validates and decodes XML responses as an `NSXMLDocument` objects.
+
+ By default, `AFPropertyListSerializer` accepts the following MIME types:
+
+ - `application/x-plist`
  */
 @interface AFPropertyListSerializer : AFHTTPSerializer
 
 /**
- 
+ The property list format. Possible values are described in "NSPropertyListFormat".
  */
 @property (nonatomic, assign) NSPropertyListFormat format;
 
 /**
- 
+ The property list reading options. Possible values are described in "NSPropertyListMutabilityOptions."
  */
 @property (nonatomic, assign) NSPropertyListReadOptions readOptions;
 
 /**
- 
+ @warning The `writeOptions` property is currently unused.
  */
 @property (nonatomic, assign) NSPropertyListWriteOptions writeOptions;
 
 /**
+ Creates and returns a property list serializer with a specified format, read options, and write options.
  
+ @param format The property list format.
+ @param readOptions The property list reading options.
+ @param writeOptions The property list write options.
  */
 + (instancetype)serializerWithFormat:(NSPropertyListFormat)format
                          readOptions:(NSPropertyListReadOptions)readOptions
@@ -246,7 +323,20 @@ typedef NS_ENUM(NSUInteger, AFHTTPRequestQueryStringSerializationStyle) {
 #pragma mark -
 
 /**
- 
+ `AFImageSerializer` is a subclass of `AFHTTPSerializer` that validates and decodes image responses.
+
+ By default, `AFImageSerializer` 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 AFImageSerializer : AFHTTPSerializer