First (half of a) draft of AFRestClient documentation

AFNetworking/AFRestClient.h

@@ -33,27 +33,101 @@
     NSOperationQueue *_operationQueue;
 }
 
+/**
+ An `NSURL` object that is used as the base for paths specified in methods such as `getPath:parameteres:success:failure`
+ */
+@property (readonly, nonatomic, retain) NSURL *baseURL;
+
+///--------------------------------
+/// @name Initializing REST Clients
+///--------------------------------
+
+/**
+ Initializes an `AFRestClient` object with the specified base URL.
+ 
+ @param url The base URL for the REST client. This argument must not be nil.
+ 
+ @return The newly-initialized REST client
+ */
 - (id)initWithBaseURL:(NSURL *)url;
 
+///----------------------------------
+/// @name Managing HTTP Header Values
+///----------------------------------
+
+/**
+ Returns the value for the HTTP headers set in request objects created by the REST client
+ 
+ @param header The HTTP header to return the default value for
+ 
+ @return The default value for the HTTP header, or `nil` if unspecified
+ */
 - (NSString *)defaultValueForHeader:(NSString *)header;
+
+/**
+ Sets the value for the HTTP headers set in request objects made by the REST client. If `nil`, removes the existing value for that header.
+ 
+ @param header The HTTP header to set a default value for
+ @param value The value set as default for the specified header, or `nil
+ */
 - (void)setDefaultHeader:(NSString *)header value:(NSString *)value;
+
+/**
+ Sets the "Authorization" HTTP header set in request objects made by the REST client to a basic authentication value with Base64-encoded username and password. This overwrites any existing value for this header.
+ 
+ @param username The HTTP basic auth username
+ @param password The HTTP basic auth password
+ */
 - (void)setAuthorizationHeaderWithUsername:(NSString *)username password:(NSString *)password;
+
+/**
+ Sets the "Authorization" HTTP header set in request objects made by the REST client to a token-based authentication value, such as an OAuth access token. This overwrites any existing value for this header.
+ 
+ @param token The authentication token
+ */
 - (void)setAuthorizationHeaderWithToken:(NSString *)token;
+
+/**
+ Clears any existing value for the "Authorization" HTTP header.
+ */
 - (void)clearAuthorizationHeader;
 
+///-------------------------------
+/// @name Creating Request Objects
+///-------------------------------
+
+/**
+ Creates an `NSMutableURLRequest` object with the specified HTTP method, resource path, and parameters, with the default HTTP headers specified for the client.
+ 
+ @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
+ 
+ @return An `NSMutableURLRequest` object
+ */
 - (NSMutableURLRequest *)requestWithMethod:(NSString *)method 
                                       path:(NSString *)path parameters:(NSDictionary *)parameters;
 
+///--------------------------------
+/// @name Enqueuing HTTP Operations
+///--------------------------------
 - (void)enqueueHTTPOperation:(AFHTTPRequestOperation *)operation;
 
 - (void)enqueueHTTPOperationWithRequest:(NSURLRequest *)request 
                                 success:(void (^)(id response))success 
                                 failure:(void (^)(NSError *error))failure;
 
+///---------------------------------
+/// @name Cancelling HTTP Operations
+///---------------------------------
+
 - (void)cancelHTTPOperationsWithRequest:(NSURLRequest *)request;
 
 - (void)cancelAllHTTPOperations;
 
+///---------------------------
+/// @name Making HTTP Requests
+///---------------------------
 - (void)getPath:(NSString *)path 
      parameters:(NSDictionary *)parameters 
         success:(void (^)(id response))success