Docs formatting for RKRoute

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.