add docs and more deprecations

packages/@ember/-internals/routing/lib/services/router.ts

@@ -38,6 +38,79 @@ import { extractRouteArgs, resemblesURL, shallowEqual } from '../utils';
 export default class RouterService extends Service {
   _router!: EmberRouter;
 
+  init() {
+    this._super(...arguments);
+    this._router.on('routeWillChange', (transition: Transition) => {
+      this.trigger('routeWillChange', transition);
+    });
+
+    this._router.on('routeDidChange', (transition: Transition) => {
+      this.trigger('routeDidChange', transition);
+    });
+  }
+
+  /**
+    The `routeWillChange` event is fired at the beginning of any
+    attempted transition with a `Transition` object as the sole
+    argument. This action can be used for aborting, redirecting,
+    or decorating the transition from the currently active routes.
+
+    A good example is preventing navigation when a form is
+    half-filled out:
+
+    ```app/routes/contact-form.js
+    import {inject as service} from '@ember/service';
+
+    export default Route.extend({
+      router: service('router'),
+      init() {
+        this._super(...arguments);
+        this.router.on('routeWillUpdate', (transition) => {
+          if (!transition.to.find(route => route.name === this.routeName)) {
+            alert("Please save or cancel your changes.");
+            transition.abort();
+          }
+        })
+      }
+    });
+    ```
+
+  The `routeWillChange` event fires whenever a new route is chosen as the desired target of a transition. This includes `transitionTo`, `replaceWith`, all redirection for any reason including error handling, and abort. Aborting implies changing the desired target back to where you already were. Once a transition has completed, `routeDidChange` fires.
+
+    @event routeWillChange
+    @param {Transition} transition
+    @public
+  */
+
+  /**
+    The `routeDidChange` event only fires once a transition has settled.
+    This includes aborts and error substates. Like the `routeWillChange` event
+    it recieves a Transition as the sole argument.
+
+    A good example is sending some analytics when the route has transitioned:
+
+    ```app/routes/contact-form.js
+    import {inject as service} from '@ember/service';
+
+    export default Route.extend({
+      router: service('router'),
+      init() {
+        this._super(...arguments);
+        this.router.on('routeDidUpdate', (transition) => {
+          ga.send('pageView', {
+            current: transition.to.name,
+            from: transition.from.name
+          });
+        })
+      }
+    });
+    ```
+
+    @event routeDidChange
+    @param {Transition} transition
+    @public
+  */
+
   /**
      Transition the application into another route. The route may
      be either a single route or route path:
@@ -151,16 +224,6 @@ export default class RouterService extends Service {
 }
 
 RouterService.reopen(Evented, {
-  init() {
-    this._super(...arguments);
-    this._router.on('routeWillChange', (transition: Transition) => {
-      this.trigger('routeWillChange', transition);
-    });
-
-    this._router.on('routeDidChange', (transition: Transition) => {
-      this.trigger('routeDidChange', transition);
-    });
-  },
   /**
      Name of the current route.
 

packages/@ember/-internals/routing/lib/system/route.ts

@@ -7,8 +7,9 @@ import {
   Object as EmberObject,
   typeOf,
 } from '@ember/-internals/runtime';
+import { EMBER_ROUTING_ROUTER_SERVICE } from '@ember/canary-features';
 import { assert, deprecate, info, isTesting } from '@ember/debug';
-import { ROUTER_ROUTER } from '@ember/deprecated-features';
+import { ROUTER_EVENTS, ROUTER_ROUTER } from '@ember/deprecated-features';
 import { assign } from '@ember/polyfills';
 import { once } from '@ember/runloop';
 import { classify } from '@ember/string';
@@ -330,7 +331,7 @@ class Route extends EmberObject implements IRoute {
     @private
 
     @method _internalReset
-    @since 1.7.0
+    @since 3.6.0
   */
   _internalReset(isExiting: boolean, transition: Transition) {
     let controller = this.controller;
@@ -2511,4 +2512,39 @@ Route.reopen(ActionHandler, Evented, {
   },
 });
 
+export let ROUTER_EVENT_DEPRECATIONS: any;
+if (EMBER_ROUTING_ROUTER_SERVICE && ROUTER_EVENTS) {
+  ROUTER_EVENT_DEPRECATIONS = {
+    on(name: string) {
+      this._super(...arguments);
+      let hasDidTransition = name === 'didTransition';
+      let hasWillTransition = name === 'willTransition';
+
+      if (hasDidTransition) {
+        deprecate(
+          'You attempted to listen to the "didTransition" event which is deprecated. Please inject the router service and listen to the "routeDidChange" event.',
+          false,
+          {
+            id: 'deprecate-router-events',
+            until: '4.0.0',
+          }
+        );
+      }
+
+      if (hasWillTransition) {
+        deprecate(
+          'You attempted to listen to the "willTransition" event which is deprecated. Please inject the router service and listen to the "routeWillChange" event.',
+          false,
+          {
+            id: 'deprecate-router-events',
+            until: '4.0.0',
+          }
+        );
+      }
+    },
+  };
+
+  Route.reopen(ROUTER_EVENT_DEPRECATIONS);
+}
+
 export default Route;