fix(UrlRouter): Use { location: 'replace' } whenever a url redirect h…

…appens

- This eliminates extra entries in the browser history.

src/url/interface.ts

@@ -389,10 +389,10 @@ export interface MatchResult {
 /**
  * A function that matches the URL for a [[UrlRule]]
  *
- * Implementations should match against the current
- * [[UrlService.path]], [[UrlService.search]], and [[UrlService.hash]]
+ * Implementations should match against the provided [[UrlParts]] and return the matched value (truthy) if the rule matches.
+ * If this rule is selected, the matched value is passed to the [[UrlRuleHandlerFn]].
  *
- * @return truthy or falsey
+ * @return the matched value, either truthy or falsey
  */
 export interface UrlRuleMatchFn {
   (url?: UrlParts, router?: UIRouter): any;
@@ -402,7 +402,10 @@ export interface UrlRuleMatchFn {
  * Handler invoked when a rule is matched
  *
  * The matched value from the rule's [[UrlRuleMatchFn]] is passed as the first argument
- * The handler should return a string (to redirect), or void
+ * The handler should return a string (to redirect), a [[TargetState]]/[[TargetStateDef]], or void
+ *
+ * If the handler returns a string, the url is replaced with the string.
+ * If the handler returns a [[TargetState]], the target state is activated.
  */
 export interface UrlRuleHandlerFn {
   (matchValue?: any, url?: UrlParts, router?: UIRouter): (string|TargetState|TargetStateDef|void);
@@ -447,13 +450,17 @@ export interface UrlRule {
   type: UrlRuleType;
 
   /**
-   * This function should match the url and return match details
+   * This function should match the url and return the match details
+   *
+   * See [[UrlRuleMatchFn]] for details
    */
   match: UrlRuleMatchFn;
 
   /**
-   * This function is called after the rule matched the url.
+   * This function is called if the rule matched, and was selected as the "best match".
    * This function handles the rule match event.
+   *
+   * See [[UrlRuleHandlerFn]] for details
    */
   handler: UrlRuleHandlerFn;
 }

src/url/urlRouter.ts

@@ -135,7 +135,7 @@ export class UrlRouter implements UrlRulesApi, UrlSyncApi, Disposable {
     let best = this.match(url);
 
     let applyResult = pattern([
-      [isString, (newurl: string) => $url.url(newurl)],
+      [isString, (newurl: string) => $url.url(newurl, true)],
       [TargetState.isDef, (def: TargetStateDef) => $state.go(def.state, def.params, def.options)],
       [is(TargetState), (target: TargetState) => $state.go(target.state(), target.params(), target.options())],
     ]);
@@ -233,6 +233,9 @@ export class UrlRouter implements UrlRulesApi, UrlSyncApi, Disposable {
    * This api can be used directly for more control (to register [[RawUrlRule]], for example).
    * Rules can be created using [[UrlRouter.ruleFactory]], or create manually as simple objects.
    *
+   * A rule should have a `match` function which returns truthy if the rule matched.
+   * It should also have a `handler` function which is invoked if the rule is the best match.
+   *
    * @return a function that deregisters the rule
    */
   rule(rule: UrlRule): Function {
@@ -256,7 +259,7 @@ export class UrlRouter implements UrlRulesApi, UrlSyncApi, Disposable {
   /** @inheritdoc */
   otherwise(handler: string|UrlRuleHandlerFn|TargetState|TargetStateDef) {
     if (!isFunction(handler) && !isString(handler) && !is(TargetState)(handler) && !TargetState.isDef(handler)) {
-      throw new Error("'redirectTo' must be a string, function, TargetState, or have a state: 'newtarget' property");
+      throw new Error("'handler' must be a string, function, TargetState, or have a state: 'newtarget' property");
     }
 
     let handlerFn: UrlRuleHandlerFn = isFunction(handler) ? handler as UrlRuleHandlerFn : val(handler);