From 0f2013d67beecd3933648e66ebfc4525d3c60013 Mon Sep 17 00:00:00 2001 From: Blake Watters Date: Tue, 11 Sep 2012 19:53:23 -0400 Subject: [PATCH] Docs formatting for RKRoute --- Code/Network/RKRoute.h | 108 +++++++++++++++++++---------------------- 1 file changed, 50 insertions(+), 58 deletions(-) diff --git a/Code/Network/RKRoute.h b/Code/Network/RKRoute.h index de0a7bc6..92e7bb6e 100644 --- a/Code/Network/RKRoute.h +++ b/Code/Network/RKRoute.h @@ -21,73 +21,24 @@ #import "RKHTTPUtilities.h" /** - The RKRoute class models a single routable path pattern in use by the application. A route - can be combined with an NSURL base URL and interpolated with an object to produce a new fully hydrated - URL object. Routes are always instantiated with a path pattern and metadata to provide for - the subsequent identification of the defined route. + The RKRoute class models a single routable path pattern in use by the application. A route can be combined with an `NSURL` base URL and interpolated with an object to produce a new fully hydrated URL object. Routes are always instantiated with a path pattern and metadata to provide for the subsequent identification of the defined route. There are three types of routes modeled by the RKRoute class: - 1. Named Routes: A named route represents a single path and optional request method within - the application. The route is not affiliated with any particular class. For example, one might - define a route with the name `@"airlines_list"` as a GET to the path '/airlines.json'. - 1. Class Routes: An class route represents a single path that is identified by object class - and request method for which it is appropriate. For example, one might define a route for the class - `RKArticle` for a POST to the path '/articles.json'. - 1. Relationship Routes: A relationship route represents a single path through which the relationship - of a parent object can be manipulated. For example, given an `RKArticle` and `RKComment` class, one - might define a relationship route for the `RKArticle` class's `@"comments"` relationship as pointing to - a GET to the path `@"/articles/:articleID/comments". + 1. **Named Routes**: A named route represents a single path and optional request method within the application. The route is not affiliated with any particular class. For example, one might define a route with the name `@"airlines_list"` as a GET to the path '/airlines.json'. + 1. **Class Routes**: An class route represents a single path that is identified by object class and request method for which it is appropriate. For example, one might define a route for the class `RKArticle` for a POST to the path '/articles.json'. + 1. **Relationship Routes**: A relationship route represents a single path through which the relationship of a parent object can be manipulated. For example, given an `RKArticle` and `RKComment` class, one might define a relationship route for the `RKArticle` class's `@"comments"` relationship as pointing to a GET to the path `@"/articles/:articleID/comments". - The RKRoute class is internally implemented as a class cluster and is not to be directly instantiated via alloc and - init. + The RKRoute class is internally implemented as a class cluster and is not to be directly instantiated via alloc and init. @see RKRouter @see RKRouteSet */ @interface RKRoute : NSObject -/** - The name of the receiver. - - The name is used to identify named and relationship routes and is nil for object routes. - */ -@property (nonatomic, strong, readonly) NSString *name; - -/** - The object class of the receiver. - - Defines the class for which the route is appropriate. Nil for named routes. - */ -@property (nonatomic, strong, readonly) Class objectClass; - -/** - The request method of the receiver. - - Appropriate for all route types. If the route is appropriate for any HTTP request method, - then the value RKRequestMethodAny is used. - */ -@property (nonatomic, assign, readonly) RKRequestMethod method; - -/** - The path pattern of the receiver. - - A SOCKit pattern that describes the format of the path portion of URL's generated from the receiver. Required and used by all route types. - - @see SOCPattern - */ -@property (nonatomic, strong, readonly) NSString *pathPattern; - -/** - A Boolean value that determines if the path pattern should be escaped when evaluated. - - *Default*: NO - */ -@property (nonatomic, assign) BOOL shouldEscapePath; - -///----------------------------------------------------------------------------- +///--------------------------- /// @name Instantiating Routes -///----------------------------------------------------------------------------- +///--------------------------- /** Creates and returns a new named route object with the given name, path pattern and method. @@ -120,9 +71,50 @@ */ + (id)routeWithRelationshipName:(NSString *)name objectClass:(Class)objectClass pathPattern:(NSString *)pathPattern method:(RKRequestMethod)method; -///----------------------------------------------------------------------------- +///--------------------------------- +/// @name Accessing Route Attributes +///--------------------------------- + +/** + The name of the receiver. + + The name is used to identify named and relationship routes and is always `nil` for object routes. + */ +@property (nonatomic, strong, readonly) NSString *name; + +/** + The object class of the receiver. + + Defines the class for which the route is appropriate. Always returns `nil` for named routes. + */ +@property (nonatomic, strong, readonly) Class objectClass; + +/** + The request method of the receiver. + + Appropriate for all route types. If the route is appropriate for any HTTP request method, then the `RKRequestMethodAny` value is used. + */ +@property (nonatomic, assign, readonly) RKRequestMethod method; + +/** + The path pattern of the receiver. + + A SOCKit pattern that describes the format of the path portion of URL's generated from the receiver. Required and used by all route types. + + @see `SOCPattern` + */ +@property (nonatomic, strong, readonly) NSString *pathPattern; + +/** + A Boolean value that determines if the path pattern should be escaped when evaluated. + + *Default*: `NO` + */ +@property (nonatomic, assign) BOOL shouldEscapePath; + +///----------------------------- /// @name Inspecting Route Types -///----------------------------------------------------------------------------- +///----------------------------- /** Determines if the receiver is a named route.