Small docs tweaks

docs/api/Location.md

@@ -0,0 +1,65 @@
+API: `Location` (object)
+========================
+
+The router uses "location" objects to determine the current state of
+the application and update it when needed. In a browser environment,
+the location represents the URL in the browser's location bar. On the
+server, the location is the URL path that was used in the request.
+
+ReactRouter ships with several locations that make it convenient to
+use in many different scenarios. They are listed below.
+
+  | `HashLocation`      | Stores the current URL in `window.location.hash`. Use this if you need to support browsers that do not support the HTML5 history API |
+  | `HistoryLocation`   | Uses the HTML5 history API to store state in clean URLs |
+  | `RefreshLocation`   | A fallback for having clean URLs in browsers that do not support the HTML5 history API by updating `window.location` whenever the route changes. The router automatically falls back to this when you try to use `HistoryLocation` in old browsers |
+  | `StaticLocation`    | A location for stateless environments (like servers) where the URL is given once |
+  | `TestLocation`      | A location that allows you to easily stub out URL history when writing tests |
+
+You can also supply the router with your own location implementation. The
+following methods must be implemented:
+
+Methods
+-------
+
+### `addChangeListener(listener)`
+
+Adds a function to the location that should be called when it changes.
+
+### `removeChangeListener(listener)`
+
+Stop calling the given function when the location changes.
+
+### `push`
+
+Called when the router is transitioning from one path to another.
+
+### `replace`
+
+Called when the router is replacing (not transitioning) one url with
+another.
+
+### `pop`
+
+Called when the router attempts to go back one entry in the history.
+
+### `getCurrentPath`
+
+Should return the current URL path, complete with query string (if applicable).
+This method should be ready to go immediately after setup.
+
+### `toString`
+
+Should return a useful string for logging and debugging.
+
+History
+-------
+
+Additionally, location objects must:
+
+- Increment `ReactRouter.History.length` immediately **after** the URL changes
+- Decrement `ReactRouter.History.length` immediately **before** going back to the
+  previous URL
+
+Please refer to the [built-in location objects][locations] to get an idea for how this is done.
+
+[locations]: /locations

docs/api/README.md

@@ -1,28 +1,25 @@
 React Router API 
 ================
 
-- [`Router`](/docs/api/Router.md)
-
 - [`Router.run`](/docs/api/run.md)
-
 - [`Router.create`](/docs/api/create.md)
+- [`Location`](/docs/api/Location.md)
+- [`Transition`](/docs/api/Transition.md)
 
-- Components
-  - [`DefaultRoute`](/docs/api/components/DefaultRoute.md)
+- Renderable Components
+  - [`RouteHandler`](/docs/api/components/RouteHandler.md)
   - [`Link`](/docs/api/components/Link.md)
+
+- Configuration Components
+  - [`Route`](/docs/api/components/Route.md)
+  - [`DefaultRoute`](/docs/api/components/DefaultRoute.md)
   - [`NotFoundRoute`](/docs/api/components/NotFoundRoute.md)
   - [`Redirect`](/docs/api/components/Redirect.md)
-  - [`Route`](/docs/api/components/Route.md)
-  - [`RouteHandler`](/docs/api/components/RouteHandler.md)
 
 - Mixins
   - [`State`](/docs/api/mixins/State.md)
   - [`Navigation`](/docs/api/mixins/Navigation.md)
 
-- Misc 
-  - [`Location`](/docs/api/misc/Location.md)
-  - [`transition`](/docs/api/misc/transition.md)
-
 Public Modules
 --------------
 

docs/api/misc/transition.md → docs/api/Transition.md

@@ -1,7 +1,7 @@
-API: `transition` (object)
+API: `Transition` (object)
 ==========================
 
-This object is sent to the [transition hooks][transition-hooks] as the
+A `Transition` object is sent to the [transition hooks][transition-hooks] as the
 first argument.
 
 Methods

docs/api/components/DefaultRoute.md

@@ -1,15 +1,15 @@
 API: `DefaultRoute` (component)
 ===============================
 
-A `DefaultRoute` is active when the parent route's path matches exactly.
+A `<DefaultRoute>` is active when the parent route's path matches exactly.
 
-Note, this is not a `NotFoundRoute`. It is only active when the parent's
+Note, this is not a `<NotFoundRoute>`. It is only active when the parent's
 route path is matched exactly.
 
 Props
 -----
 
-See [Route::props][routeProps]
+See [<Route props>][routeProps]
 
 Example
 -------

docs/api/components/Link.md

@@ -1,9 +1,11 @@
 API: `Link` (component)
 =========================
 
-Creates an anchor tag that links to a route in the application. Also
-gets the `active` class automatically when the route matches. If you
-change the path of your route, you don't have to change your links.
+A `<Link>` renders an `<a>` tag that links to a route in the application. If
+you change the path of your route, you don't also have to change your links.
+
+A `<Link>` also knows when the route it links to is active and automatically
+applies its `activeClassName` and/or `activeStyle` when it is.
 
 Props
 -----
@@ -14,7 +16,7 @@ The name of the route to link to, or a full URL.
 
 ### `params`
 
-Object, the parameters to fill in the dynamic segments of your route.
+An object of the names/values that correspond with dynamic segments in your route path.
 
 #### Example
 
@@ -31,17 +33,15 @@ Object, the parameters to fill in the dynamic segments of your route.
 
 ### `query`
 
-Object, Query parameters to add to the link. Access query parameters in
-your route handler with `this.getQuery()`.
+The query string parameters as a JavaScript object.
 
 ### `activeClassName`
 
-The className a `Link` receives when its route is active. Defaults to
-`active`.
+The className a `Link` receives when its route is active. Defaults to `active`.
 
 ### `activeStyle`
 
-Object, the styles to apply to the link element when its route is active.
+The styles to apply to the link element when its route is active.
 
 ### `onClick`
 

docs/api/components/NotFoundRoute.md

@@ -1,14 +1,14 @@
 API: `NotFoundRoute` (component)
 ===============================
 
-When a parent's URL partially matches, but none of the children do, a
-`NotFoundRoute` will be matched and its handler activated at any level
-of your route hierarchy.
+A `<NotFoundRoute>` is active when the beginning of its parent's path
+matches the URL but none of its siblings do. It can be found at any level
+of your hierarchy, allowing you to have a context-aware "not found" page.
 
 Props
 -----
 
-See [Route::props][routeProps]
+See [<Route props>][routeProps]
 
 Example
 -------

docs/api/components/Redirect.md

@@ -1,7 +1,7 @@
 API: `Redirect` (component)
 ===========================
 
-Configures a redirect for a path in your route declarations.
+A `<Redirect>` sets up a redirect to another route in your application. 
 
 Props
 -----

docs/api/components/Route.md

@@ -1,16 +1,14 @@
 API: `Route` (component)
 =========================
 
-Configuration component to declare your application's routes and entry
-view hierarchy.
+A `<Route>` is used to declare your application's routes and entry view hierarchy.
 
 Props
 -----
 
 ### `name`
 
-The name of the route, used in the `Link` component and the router's
-transition methods.
+The name of the route, used in the `Link` component and the router's transition methods.
 
 ### `path`
 

docs/api/components/RouteHandler.md

@@ -1,15 +1,14 @@
 API: `RouteHandler` (component)
 ===============================
 
-The component supplied to a route is called a "Route Handler". They can
-be rendered by the parent handler with `<RouteHandler/>`.  There are
-some special static methods available to these components.
+A `<RouteHandler>` renders the handler of the route at the level of the
+route hierarchy in which it is used.
 
 Static Lifecycle Methods
 ------------------------
 
-You can define static methods on your route handlers that will be called
-during route transitions.
+You can define some static methods on your route handlers that will be
+called during route transitions.
 
 ### `willTransitionTo(transition, params, query, callback)`
 
@@ -18,7 +17,7 @@ abort or redirect the transition. You can pause the transition while you
 do some asynchonous work and call `callback(error)` when you're done, or
 omit the callback in your argument list and it will be called for you.
 
-See also: [transition](/docs/api/misc/transition.md)
+See also: [Transition](/docs/api/Transition.md)
 
 ### `willTransitionFrom(transition, component, callback)`
 
@@ -27,7 +26,7 @@ opportunity to abort the transition. The `component` is the current
 component, you'll probably need it to check its state to decide if you
 want to allow the transition (like form fields).
 
-See also: [transition](/docs/api/misc/transition.md)
+See also: [Transition](/docs/api/Transition.md)
 
 #### Example