docs update for new api changes

Author: ryanflorence

README.md

@@ -70,17 +70,23 @@ What's it look like?
 ```js
 React.renderComponent((
   <Routes location="history">
-    <Route handler={App}>
-      <Route name="about" handler={About}/>
+    <Route path="/" handler={App}>
+      <DefaultRoute handler={Home} />
+      <Route name="about" handler={About} />
       <Route name="users" handler={Users}>
-        <Route name="user" path="/user/:userId" handler={User}/>
+        <Route name="recent-users" path="recent" handler={User} />
+        <Route name="user" path="/user/:userId" handler={User} />
+        <NotFoundRoute handler={UserRouteNotFound}/>
       </Route>
     </Route>
-    <Route path="*" handler={NotFound}/>
+    <NotFoundRoute handler={NotFound}/>
+    <Redirect path="company" to="about" />
   </Routes>
 ), document.body);
 ```
 
+All of the `handler`s will render inside their parent route `handler`.
+
 See more in the [overview guide](/docs/guides/overview.md).
 
 Benefits of This Approach

UPGRADE_GUIDE.md

@@ -8,6 +8,59 @@ they refer to.
 0.5.x -> master
 ---------------
 
+### Path Matching
+
+Paths that start with `/` are absolute and work exactly as they used to.
+Paths that don't start with `/` are now relative, meaning they extend
+their parent route.
+
+Simply add `/` in front of all your paths to keep things working.
+
+```xml
+<!-- 0.5.x -->
+<Route path="/foo">
+  <Route path="bar"/>
+</Route>
+
+<!-- 0.6.x -->
+<Route path="/foo">
+  <Route path="/bar"/>
+</Route>
+```
+
+Though, you may want to embrace this new feature:
+
+```js
+<!-- 0.5.x -->
+<Route path="/course/:courseId">
+  <Route path="/course/:courseId/assignments"/>
+  <Route path="/course/:courseId/announcements"/>
+</Route>
+
+<!-- 0.6.x -->
+<Route path="/course/:courseId">
+  <Route path="assignments"/>
+  <Route path="announcements"/>
+</Route>
+```
+
+Also `.` is no longer matched in dynamic segments.
+
+```js
+<!-- 0.5.x -->
+<Route path="/file/:filename" />
+
+<!-- 0.6.x -->
+<Route path="/file/:filename.:ext?" />
+
+<!--
+  or for a looser match to allow for multiple `.` note that the data
+  will be available on `this.props.params.splat` instead of
+  `this.props.params.filename`
+-->
+<Route path="/file/*" />
+```
+
 ### Link params
 
 Links should now pass their params in the `params` property, though the

docs/api/README.md

@@ -6,6 +6,7 @@ React Router API
 - Components
   - [`DefaultRoute`](/docs/api/components/DefaultRoute.md)
   - [`Link`](/docs/api/components/Link.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)

docs/api/components/DefaultRoute.md

@@ -10,15 +10,7 @@ route path is matched exactly.
 Props
 -----
 
-### `handler`
-
-The component to be rendered when the route is active.
-
-### `preserveScrollPosition`
-
-If `true`, the router will not scroll the window up when the route is
-transitioned to. Defaults to `false`. Ignored if the parent `<Routes/>`
-has been set to `true`.
+See [Route::props][routeProps]
 
 Example
 -------
@@ -60,3 +52,4 @@ same functionality:
 `DefaultRoute` feels more natural, so you can name and transition to the
 parent route.
 
+  [routeProps]:/docs/api/components/Route.md#props

docs/api/components/NotFoundRoute.md

@@ -0,0 +1,35 @@
+API: `NotFoundRoute` (component)
+===============================
+
+When a parent's url partially matches, but none of the children do, a
+`NotFoundRoute` will be matched and its handler rendered at any level of
+your route/view hierarchy.
+
+Props
+-----
+
+See [Route::props][routeProps]
+
+Example
+-------
+
+```xml
+<Routes>
+  <Route path="/" handler={App}>
+    <Route name="course" path="course/:courseId" handler={Course}>
+      <Route name="course-dashboard" path="dashboard" />
+
+      <!-- ie: `/course/123/foo` -->
+      <NotFoundRoute handler={CourseRouteNotFound} />
+    </Route>
+
+    <!-- ie: `/flkjasdf` -->
+    <NotFoundRoute handler={NotFound} />
+  </Route>
+</Routes>
+```
+
+The last `NotFoundRoute` will render inside the `App`, the first 
+
+  [routeProps]:/docs/api/components/Route.md#props
+

docs/api/components/Redirect.md

@@ -8,7 +8,8 @@ Props
 
 ### `from`
 
-The path you want to redirect from, including dynamic segments.
+The path you want to redirect from, including dynamic segments. Defaults
+to `*` so you can redirect anything not found to somewhere else.
 
 ### `to`
 
@@ -26,9 +27,20 @@ Example
   <Route handler={App}>
     <Route name="contact" handler={Contact}/>
     <Route name="about-user" path="about/:userId" handler={UserProfile}/>
+    <Route name="course" path="course/:courseId">
+      <Route name="course-dashboard" path="dashboard" handler={Dashboard}/>
+      <Route name="course-assignments" path="assignments" handler={Assignments}/>
+      <!--
+        anything like `/course/123/invalid` redirects to
+        `/course/123/dashboard`
+      -->
+      <Redirect to="course-dashboard" />
+    </Route>
   </Route>
 
+  <!-- `/get-in-touch` -> `/contact` -->
   <Redirect from="get-in-touch" to="contact" />
+  <!-- `/profile/123` -> `/about/123` -->
   <Redirect from="profile/:userId" to="about-user" />
 </Routes>
 ```

docs/api/components/Route.md

@@ -13,11 +13,11 @@ transition methods.
 
 ### `path`
 
-The path used in the URL, supporting dynamic segments. If left
-undefined, the path will be defined by the `name`, and if there is no
-name, will default to `/`. This path is always absolute from the URL
-"root", even if the leading slash is left off. Nested routes do not
-inherit the path of their parent.
+The path used in the URL. If left undefined, the path will be defined by
+the `name`, and if there is no name, will default to `/`.
+
+Please refer to the [Path Matching Guide][path-matching] to learn more
+about supported path matching syntax.
 
 ### `handler`
 
@@ -102,3 +102,4 @@ Example
 </Routes>
 ```
 
+  [path-matching]:/docs/guides/path-matching.md

docs/api/components/RouteHandler.md

@@ -61,7 +61,7 @@ Static Lifecycle Methods
 You can define static methods on your route handlers that will be called
 during route transitions.
 
-### `willTransitionTo(transition, params)`
+### `willTransitionTo(transition, params, query)`
 
 Called when a route is about to render, giving you the opportunity to
 abort or redirect the transition. You can return a promise and the whole

docs/guides/overview.md

@@ -148,8 +148,8 @@ var App = React.createClass({
 var routes = (
   <Routes location="history">
     <Route name="app" path="/" handler={App}>
-      <Route name="inbox" path="/inbox" handler={Inbox}/>
-      <Route name="calendar" path="/calendar" handler={Calendar}/>
+      <Route name="inbox" handler={Inbox}/>
+      <Route name="calendar" handler={Calendar}/>
       <DefaultRoute handler={Dashboard}/>
     </Route>
   </Routes>
@@ -228,14 +228,14 @@ var Inbox = React.createClass({
 
 var routes = (
   <Routes location="history">
-    <Route path="/" handler={App}>
+    <Route handler={App}>
 
-      <Route name="inbox" path="/inbox" handler={Inbox}>
-        <Route name="message" path="/inbox/:messageId" handler={Message}/>
+      <Route name="inbox" handler={Inbox}>
+        <Route name="message" path=":messageId" handler={Message}/>
         <DefaultRoute handler={InboxStats}/>
       </Route>
 
-      <Route name="calendar" path="/calendar" handler={Calendar}/>
+      <Route name="calendar" handler={Calendar}/>
       <DefaultRoute handler={Dashboard}/>
 
     </Route>
@@ -251,13 +251,6 @@ var routes = (
 Nesting a new level of UI does not increase the complexity of your code.
 You simply nest some routes and render them with `activeRouteHandler`.
 
-**Note**: the paths are not inherited from parent to child. This gives
-you the flexibility to have any url you need. Were the paths to be
-inherited, you'd be forced to couple your urls to your route hierarchy.
-For example, we may want `/inbox` and `/messages/123` instead of `/inbox`
-and `/inbox/123`. We can just change the path on the `message` route and
-still get view nesting even though the urls are not nested.
-
 Dynamic Segments
 ----------------
 
@@ -268,7 +261,7 @@ route handler on `this.props.params`.
 Remember our message route looks like this:
 
 ```xml
-<Route name="message" path="/inbox/:messageId" handler={Message}/>
+<Route name="message" path=":messageId" handler={Message}/>
 ```
 
 Lets look at accessing the `messageId` in `Message`.
@@ -305,15 +298,66 @@ If you'd rather be lazy, you can use the `addHandlerKey` option and set
 it to `true` on your route to opt-out of the performance. See also
 [Route][Route].
 
-Links
------
+Scrolling
+---------
+
+By default, the router will manage the scroll position between route
+transitions. When a user clicks "back" or "forward", it will restore
+their scroll position. If they visit a new route, it will automatically
+scroll the window to the top. You can opt out of this with the
+`preserverScrollPosition` option on [Routes][Routes] or [Route][Route].
+
+Bells and Whistles
+------------------
+
+### `<Link/>`
 
 The `<Link/>` component allows you to conveniently navigate users around
 the application with accessible anchor tags that don't break normal link
 functionality like control/command clicking to open in a new tab. Also,
 when the route a link references is active, you get the `active` css
 class to easily style your UI.
 
+### `<NotFoundRoute/>`
+
+At any level of your UI nesting, you can render a handler if the url
+beyond what was matched isn't recognized.
+
+```xml
+<Routes location="history">
+  <Route path="/" handler={App}>
+    <Route name="inbox" path="/inbox" handler={Inbox}>
+      <!--
+        will render inside the `Inbox` UI for any paths not recognized
+        after the parent route's path `/inbox/*`
+      -->
+      <NotFoundRoute handler={InboxNotFound}
+      <Route name="message" path="/inbox/:messageId" handler={Message}/>
+      <DefaultRoute handler={InboxStats}/>
+    </Route>
+    <Route name="calendar" path="/calendar" handler={Calendar}/>
+    <DefaultRoute handler={Dashboard}/>
+  </Route>
+  <!-- will catch any route that isn't recognized at all -->
+  <NotFoundRoute handler={NotFound}
+</Routes>
+```
+
+### `<Redirect/>`
+
+URLs in an app change, so we made it easy to not break the old ones.
+
+```xml
+<Route name="message" path="/inbox/:messageId" handler={Message} />
+<Redirect path="/messages/:messageId" to="message" />
+```
+
+Path Matching
+-------------
+
+There's a lot more to be said about path matching, check out the [Path
+Matching Guide][path-matching].
+
 API Documentation
 -----------------
 
@@ -323,5 +367,7 @@ redirecting transitions, query parameters and more.
 
   [AsyncState]:../api/mixins/AsyncState.md
   [Route]:../api/components/Route.md
+  [Routes]:../api/components/Routes.md
   [API]:../api/
+  [path-matching]:./path-matching.md