Add header documentation for RKRouter; add object parameter to named route URL generation

Code/Network/RKRoute.m

@@ -84,7 +84,7 @@
     if (self) {
         if ([self isMemberOfClass:[RKRoute class]]) {
             @throw [NSException exceptionWithName:NSInternalInconsistencyException
-                                           reason:[NSString stringWithFormat:@"%@ is not meant to be directly instantiated. Use one of the initializer methods instead..",
+                                           reason:[NSString stringWithFormat:@"%@ is not meant to be directly instantiated. Use one of the initializer methods instead.",
                                                    NSStringFromClass([self class])]
                                          userInfo:nil];
         }

Code/Network/RKRouter.h

@@ -21,15 +21,104 @@
 #import "RKRequest.h"
 @class RKURL, RKRouteSet;
 
+/**
+ An RKRouter instance is responsible for generating RKURL objects with a given
+ base URL and a route set. It is used to centralize the knowledge about the URL's
+ that are used by the application.
+
+ URL's can be generated by the router in three ways:
+    1. By name. Named routes link a symbolic name with a resource path and an HTTP request method.
+    2. By object. Routes can be defined by class and HTTP request method. When a URL is requested from the
+        router for an object, the router will identify the most appropriate route for the object
+        and instantiate an RKURL with the route's resource path pattern and interpolate it against the object.
+    3. By object relationship. Routes can be defined for relationships to other objects. When a URL is requested
+        from the router for a relationship, the router will retrieve the appropriate route for the relationship
+        from the route set and interpolate the route's resource path pattern against the source object.
+
+ @see RKURL
+ @see RKRoute
+ @see RKRouteSet
+ */
 @interface RKRouter : NSObject
 
+/**
+ The baseURL with which to construct all RKURL instance generated through the receiver.
+ */
 @property (nonatomic, retain) RKURL *baseURL;
+
+/**
+ A route set defining all the routes addressable through the receiver.
+ */
 @property (nonatomic, retain) RKRouteSet *routeSet;
 
+///-----------------------------------------------------------------------------
+/// @name Initializing a Router
+///-----------------------------------------------------------------------------
+
+/**
+ Initializes a router with a given base URL.
+
+ @param baseURL The base URL with which to initialize the receiver.
+ @return The receiver, initialized with the given base URL.
+ */
 - (id)initWithBaseURL:(RKURL *)baseURL;
 
-- (RKURL *)URLForRouteNamed:(NSString *)routeName method:(out RKRequestMethod *)method;
+///-----------------------------------------------------------------------------
+/// @name Generating URLs
+///-----------------------------------------------------------------------------
+
+/**
+ Generates a URL for the route with the given name.
+
+ The route set is searched for a route with the given name and a new RKURL object is instantiated
+ with the baseURL of the receiver and the resource path pattern of the route, optionally interpolated
+ with a given object. If a pointer to an RKRequestMethod variable is provided, the HTTP method
+ for the route will be assigned to the reference.
+
+ @param routeName The name of the route for which a URL is to be generated.
+ @param method A pointer to an RKRequestMethod variable in which to store the HTTP method associated
+    with the named route.
+ @param object An optional object against which to interpolate the resource path pattern.
+ @return A new URL object constructed by appending the resource path pattern to the baseURL of the
+    receiver and interpolating against a given object; or nil if no route was found with the given
+    name.
+ */
+- (RKURL *)URLForRouteNamed:(NSString *)routeName method:(out RKRequestMethod *)method object:(id)object;
+
+/**
+ Generates a URL for a given object with a given HTTP method.
+
+ The route set is searched for a route that matches the HTTP method and class of
+ the object being routed. If there is not an exact match for the object's class, the inheritance
+ hierarchy is searched until a match is found or all possible routes are exhausted. Exact HTTP request
+ matches are favored over the wildcard method (RKRequestMethodAny). Once the appropriate route is identified,
+ a new RKURL object is instantiated with the baseURL of the receiver and the resource path pattern of the route,
+ interpolated against the object being routed.
+
+ @param object The object for which a URL is to be generated.
+ @param method The HTTP method for which the URL is to be generated.
+ @return A new URL object constructed by appending the resource path pattern of the route for the object and
+ HTTP method to the baseURL of the receiver, interpolated against the routed object; or nil if no route was found
+ for the given object and HTTP method.
+ */
 - (RKURL *)URLForObject:(id)object method:(RKRequestMethod)method;
+
+/**
+ Generates a URL for a relationship of a given object with a given HTTP method.
+
+ The route set is searched for a route that matches the relationship of the given object's class and the given
+ HTTP method. If a matching route is found, a new RKURL object is instantiated with the baseURL of the receiver
+ and the resource path pattern of the route, interpolated against the object being routed.
+
+ @param relationshipName The name of the relationship for which a URL is to be generated.
+ @param object The object for which the URL is to be generated.
+ @param method The HTTP method for which the URL is to be generated.
+ @return A new URL object constructed by appending the resource path pattern of the route for the given object's
+ relationship and HTTP method to the baseURL of the receiver, interpolated against the routed object; or nil if no
+ route was found for the given relationship, object and HTTP method.
+ */
 - (RKURL *)URLForRelationship:(NSString *)relationshipName ofObject:(id)object method:(RKRequestMethod)method;
 
 @end
+
+// TODO: Add compatibility aliases...

Code/Network/RKRouter.m

@@ -56,12 +56,12 @@
     [super dealloc];
 }
 
-- (RKURL *)URLForRouteNamed:(NSString *)routeName method:(out RKRequestMethod *)method
+- (RKURL *)URLForRouteNamed:(NSString *)routeName method:(out RKRequestMethod *)method object:(id)object
 {
     RKRoute *route = [self.routeSet routeForName:routeName];
     if (! route) return nil;
     if (method) *method = route.method;
-    return [self.baseURL URLByAppendingResourcePath:[self resourcePathFromRoute:route forObject:nil]];
+    return [self.baseURL URLByAppendingResourcePath:[self resourcePathFromRoute:route forObject:object]];
 }
 
 - (RKURL *)URLForObject:(id)object method:(RKRequestMethod)method