docs(ngRoute): clarify when gets updated

Author: petebacondarwin

src/ngRoute/route.js

@@ -35,9 +35,9 @@ function $RouteProvider(){
    *
    *      * `path` can contain named groups starting with a colon (`:name`). All characters up
    *        to the next slash are matched and stored in `$routeParams` under the given `name`
-   *        when the route matches.
+   *        after the route is resolved.
    *      * `path` can contain named groups starting with a star (`*name`). All characters are
-   *        eagerly stored in `$routeParams` under the given `name` when the route matches.
+   *        eagerly stored in `$routeParams` under the given `name` after the route is resolved.
    *
    *    For example, routes like `/color/:color/largecode/*largecode/edit` will match
    *    `/color/brown/largecode/code/with/slashs/edit` and extract:
@@ -83,7 +83,9 @@ function $RouteProvider(){
    *      - `factory` - `{string|function}`: If `string` then it is an alias for a service.
    *        Otherwise if function, then it is {@link api/AUTO.$injector#invoke injected}
    *        and the return value is treated as the dependency. If the result is a promise, it is resolved
-   *        before its value is injected into the controller.
+   *        before its value is injected into the controller. Be aware that `ngRoute.$routeParams` will
+   *        still refer to the previous route within these resolve functions.  Use `$route.current.params`
+   *        to access the new route parameters, instead.
    *
    *    - `redirectTo` – {(string|function())=} – value to update
    *      {@link ng.$location $location} path with and trigger route redirection.

src/ngRoute/routeParams.js

@@ -18,6 +18,10 @@ ngRouteModule.provider('$routeParams', $RouteParamsProvider);
  * The service guarantees that the identity of the `$routeParams` object will remain unchanged
  * (but its properties will likely change) even when a route change occurs.
  *
+ * Note that the `$routeParams` are only updated *after* a route change completes successfully.
+ * This means that you cannot rely on `$routeParams` being correct in route resolve functions.
+ * Instead you can use `$route.current.params` to access the new route's parameters.
+ *
  * @example
  * <pre>
  *  // Given: