Docs updates for object request operation. Extracted subclass only declarations into subclass header.

Code/Network/RKManagedObjectRequestOperation.m

@@ -22,6 +22,7 @@
 #import "RKLog.h"
 #import "RKHTTPUtilities.h"
 #import "RKResponseMapperOperation.h"
+#import "RKRequestOperationSubclass.h"
 
 // Set Logging Component
 #undef RKLogComponent

Code/Network/RKObjectRequestOperation.h

@@ -36,7 +36,9 @@
  
  ## Caching
  
- TBD
+ Instances of `RKObjectRequestOperation` support all the HTTP caching facilities available via the `NSURLConnection` family of API's. For caching to be enabled, the remote web server that the application is communicating with must emit the appropriate `Cache-Control`, `Expires`, and/or `ETag` headers. When the response headers include the appropriate caching information, the shared `NSURLCache` instance will manage responses and transparently add conditional GET support to cachable requests. HTTP caching is a deep topic explored in depth across the web and detailed in RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html
+
+ The `RKObjectRequestOperation` class also provides support for utilizing the `NSURLCache` to satisfy requests without hitting the network. This support enables applications to display views presenting data retrieved via a cachable `GET` request without revalidating with the server and incurring any overhead. The optimization is controlled via `avoidsNetworkAccess` property. When enabled, the operation will skip the network transport portion of the object request operation and proceed directly to object mapping the cached response data. When the object request operation is an instance of `RKManagedObjectRequestOperation`, the deserialization and mapping portion of the process can be skipped entirely and the operation will fetch the appropriate object directly from Core Data, falling back to network transport once the cache entry has expired. Please refer to the documentation accompanying `RKManagedObjectRequestOperation` for more details.
  
  ## Core Data
  
@@ -64,9 +66,9 @@
  */
 - (id)initWithRequest:(NSURLRequest *)request responseDescriptors:(NSArray *)responseDescriptors;
 
-///------------------------------------------------------------
+///---------------------------------
 /// @name Configuring Object Mapping
-///------------------------------------------------------------
+///---------------------------------
 
 /**
  The array of `RKResponseDescriptor` objects that specify how the deserialized `responseData` is to be object mapped.
@@ -122,17 +124,34 @@
 /**
  When `YES`, network access is avoided entirely if a valid, non-expired cache entry is available for the request being loaded. No conditional GET request is sent to the server and the cache entry is assumed to be fresh. This optimization enables the object mapping to begin immediately using the cached response data. In high latency environments, this can result in an improved user experience as the operation does not wait for a 304 (Not Modified) response to be returned before proceeding with mapping.
  
- This optimization has even greater impact when the object request operation is an instance of `RKManagedObjectRequestOperation` as object mapping can skipped entirely and the objects loaded directly from Core Data.
+ This optimization has even greater impact when the object request operation is an instance of `RKManagedObjectRequestOperation` as object mapping can skipped entirely and the objects loaded directly from Core Data. Please refer to the documentation accompanying `RKManagedObjectRequestOperation`.
  
  **Default**: Dependent on the `cachePolicy` of the `NSURLRequest` used to initialize the operation. `YES` unless the request has a `cachePolicy` value equal to `NSURLRequestReloadIgnoringLocalCacheData` or `NSURLRequestReloadIgnoringLocalAndRemoteCacheData`.
+
+ @see `RKManagedObjectRequestOperation`
  */
 @property (nonatomic, assign) BOOL avoidsNetworkAccess;
 
 /**
- Returns `YES` if the value of the `response` and `responseData` was loaded by `NSURLCache`, else `NO`.
+ Returns `YES` if the value of the `response` and `responseData` was loaded from `NSURLCache`, else `NO`.
  */
 @property (nonatomic, readonly) BOOL isResponseFromCache;
 
+///-------------------------------------------------------
+/// @name Setting the Completion Block and Callback Queues
+///-------------------------------------------------------
+
+/**
+ 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 operation. This block has no return value and takes two arguments: the receiver operation and the mapping result from object mapping the response data of the request.
+ @param failure The block to be executed on the completion of an unsuccessful operation. This block has no return value and takes two arguments: the receiver operation and the error that occurred during the execution of the operation.
+
+ @discussion This method should be overridden in subclasses in order to specify the response object passed into the success block.
+ */
+- (void)setCompletionBlockWithSuccess:(void (^)(RKObjectRequestOperation *operation, RKMappingResult *mappingResult))success
+                              failure:(void (^)(RKObjectRequestOperation *operation, NSError *error))failure;
+
 /**
  The callback dispatch queue on success. If `NULL` (default), the main queue is used.
  
@@ -147,40 +166,10 @@
  */
 @property (nonatomic, assign) dispatch_queue_t failureCallbackQueue;
 
-// TODO: Add a Boolean to enable the network if possible
-
-///-----------------------------------
-/// @name Setting the Completion Block
-///-----------------------------------
-
-/**
- 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 operation. This block has no return value and takes two arguments: the receiver operation and the mapping result from object mapping the response data of the request.
- @param failure The block to be executed on the completion of an unsuccessful operation. This block has no return value and takes two arguments: the receiver operation and the error that occurred during the execution of the operation.
- 
- @discussion This method should be overridden in subclasses in order to specify the response object passed into the success block.
- */
-- (void)setCompletionBlockWithSuccess:(void (^)(RKObjectRequestOperation *operation, RKMappingResult *mappingResult))success
-                              failure:(void (^)(RKObjectRequestOperation *operation, NSError *error))failure;
-
-///-----------------------------------
-/// @name Setting the Completion Block
-///-----------------------------------
-
 // Things to consider:
 //  - (void)willMapObject:(id* inout)object | willMapResponseObject:
 // mapperDelegate
-
+// TODO: Add a Boolean to enable the network if possible
 // TODO: Need tests for: success, request failure, request timeout, parsing failure, no matching mapping descriptors, parsing an error out of the payload,
 // no mappable content found, unable to parse the MIME type returned, handling a 204 response, getting back a 200 with 'blank' content (i.e. render :nothing => true)
 @end
-
-// Move to RKObjectRequestOperationSubclass.h
-@interface RKObjectRequestOperation (ForSubclassEyesOnly)
-
-// Subclass Overrides
-- (RKMappingResult *)performMappingOnResponse:(NSError **)error;
-- (void)willFinish;
-
-@end

Code/Network/RKRequestOperationSubclass.h

@@ -0,0 +1,45 @@
+//
+//  RKRequestOperationSubclass.h
+//  RestKit
+//
+//  Created by Blake Watters on 9/16/12.
+//  Copyright (c) 2012 RestKit. All rights reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//  http://www.apache.org/licenses/LICENSE-2.0
+//
+//  Unless required by applicable law or agreed to in writing, software
+//  distributed under the License is distributed on an "AS IS" BASIS,
+//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//  See the License for the specific language governing permissions and
+//  limitations under the License.
+//
+
+/*
+ The extensions to the `RKObjectRequestOperation` class declared in the `ForSubclassEyesOnly` category are to be used by subclasses implementations only. Code that uses `RKObjectRequestOperation` objects must never call these methods.
+ */
+@interface RKObjectRequestOperation (ForSubclassEyesOnly)
+
+///----------------------------
+/// @name Subclassing Overrides
+///----------------------------
+
+/**
+ Performs object mapping using the `response` and `responseData` properties.
+
+ The `RKObjectRequestOperation` superclass is responsible for the invocation of this method and the subsequent handling of the mapping result or error.
+
+ @param error A pointer to an `NSError` object to be set in the event that the object mapping process has failed.
+ @return A mapping result or `nil` if an error has occurred.
+ */
+- (RKMappingResult *)performMappingOnResponse:(NSError **)error;
+
+/**
+ Invoked to tell the receiver that the object request operation is finishing its work and is about to transition into the finished state. Used to perform any necessary cleanup before the operation is finished.
+ */
+- (void)willFinish;
+
+@end