docs(TransitionHook): Document the built-in transition hooks.

Author: christopherthielen

src/common/hof.ts

@@ -2,7 +2,7 @@
  * Higher order functions
  *
  * @module common_hof
- */
+ */ /** */
 
 import {Predicate} from "./common";
 /**

src/common/interface.ts

@@ -1,3 +1,5 @@
+/** @module common */ /** */
+
 /**
  * An interface for getting values from dependency injection.
  */
@@ -47,4 +49,4 @@ export interface UiInjector {
    * @return a Promise for the Dependency Injection value that matches the key
    */
   getAsync(key: any): any;
-}
+}

src/hooks/onEnterExitRetain.ts

@@ -1,9 +1,44 @@
-/** @module state */ /** for typedoc */
+/** @module hooks */ /** for typedoc */
 import {TransitionStateHookFn} from "../transition/interface";
 import {State} from "../state/stateObject";
 import {Transition} from "../transition/transition";
 
-export function makeEnterExitRetainHook(hookName: string): TransitionStateHookFn {
+/**
+ * A factory which creates an onEnter, onExit or onRetain transition hook function
+ *
+ * The returned function invokes the (for instance) state.onEnter hook when the
+ * state is being entered.
+ *
+ * @hidden
+ */
+function makeEnterExitRetainHook(hookName: string): TransitionStateHookFn {
     return (transition: Transition, state: State) =>
         state[hookName](transition, state);
 }
+
+/**
+ * The [[TransitionStateHookFn]] for onExit
+ *
+ * When the state is being exited, the state's .onExit function is invoked.
+ *
+ * Registered using `transitionService.onExit({ exiting: (state) => !!state.onExit }, onExitHook);`
+ */
+export const onExitHook: TransitionStateHookFn      = makeEnterExitRetainHook('onExit');
+
+/**
+ * The [[TransitionStateHookFn]] for onRetain
+ *
+ * When the state is being exited, the state's .onRetain function is invoked.
+ *
+ * Registered using `transitionService.onRetain({ retained: (state) => !!state.onRetain }, onRetainHook);`
+ */
+export const onRetainHook: TransitionStateHookFn    = makeEnterExitRetainHook('onRetain');
+
+/**
+ * The [[TransitionStateHookFn]] for onEnter
+ *
+ * When the state is being exited, the state's .onEnter function is invoked.
+ *
+ * Registered using `transitionService.onEnter({ entering: (state) => !!state.onEnter }, onEnterHook);`
+ */
+export const onEnterHook: TransitionStateHookFn     = makeEnterExitRetainHook('onEnter');

src/hooks/redirectTo.ts

@@ -1,11 +1,14 @@
+/** @module hooks */ /** */
 import {isString, isFunction} from "../common/predicates"
 import {Transition} from "../transition/transition";
 import {services} from "../common/coreservices";
 import {TargetState} from "../state/targetState";
 
 /**
- * A hook that redirects to a different state or params
+ * A [[TransitionHookFn]] that redirects to a different state or params
  *
+ * Registered using `transitionService.onStart({ to: (state) => !!state.redirectTo }, redirectHook);`
+ * 
  * See [[StateDeclaration.redirectTo]]
  */
 export const redirectToHook = (trans: Transition) => {

src/hooks/resolve.ts

@@ -1,17 +1,34 @@
-/** @module state */ /** for typedoc */
+/** @module hooks */ /** for typedoc */
 import {noop} from "../common/common";
 import {Transition} from "../transition/transition";
 import {State} from "../state/stateObject";
 import {ResolveContext} from "../resolve/resolveContext";
+import {TransitionStateHookFn, TransitionHookFn} from "../transition/interface";
 
-/** A function which resolves all EAGER Resolvables in the To Path */
-export const $eagerResolvePath = (trans: Transition) =>
+/**
+ * A [[TransitionHookFn]] which resolves all EAGER Resolvables in the To Path
+ *
+ * Registered using `transitionService.onStart({}, eagerResolvePath);`
+ *
+ * When a Transition starts, this hook resolves all the EAGER Resolvables, which the transition then waits for.
+ *
+ * See [[StateDeclaration.resolve]]
+ */
+export const eagerResolvePath: TransitionHookFn = (trans: Transition) =>
     new ResolveContext(trans.treeChanges().to)
         .resolvePath("EAGER", trans)
         .then(noop);
 
-/** A function which resolves all LAZY Resolvables for the state (and all ancestors) in the To Path */
-export const $lazyResolveState = (trans: Transition, state: State) =>
+/**
+ * A [[TransitionHookFn]] which resolves all LAZY Resolvables for the state (and all its ancestors) in the To Path
+ *
+ * Registered using `transitionService.onEnter({ entering: () => true }, lazyResolveState);`
+ *
+ * When a State is being entered, this hook resolves all the Resolvables for this state, which the transition then waits for.
+ *
+ * See [[StateDeclaration.resolve]]
+ */
+export const lazyResolveState: TransitionStateHookFn = (trans: Transition, state: State) =>
     new ResolveContext(trans.treeChanges().to)
         .subContext(state)
         .resolvePath("LAZY", trans)

src/hooks/transitionManager.ts

@@ -1,9 +1,13 @@
+/** @module hooks */ /** */
 import {UrlRouter} from "../url/urlRouter";
 import {StateService} from "../state/stateService";
 import {Transition} from "../transition/transition";
-import {UiInjector} from "../common/interface";
-import {UiRouter} from "../router";
 
+/** 
+ * A [[TransitionHookFn]] which updates the URL after a successful transition
+ * 
+ * Registered using `transitionService.onSuccess({}, updateUrl);`
+ */
 export function updateUrl(transition: Transition) {
   let options = transition.options();
   let $state: StateService = transition.router.stateService;

src/hooks/url.ts

@@ -1,18 +1,35 @@
-/** @module state */ /** for typedoc */
+/** @module hooks */ /** for typedoc */
 import {noop} from "../common/common";
 import {services} from "../common/coreservices";
 import {Transition} from "../transition/transition";
 import {ViewService} from "../view/view";
 import {ViewConfig} from "../view/interface";
 
 
-/** Allows the views to do async work [.load()] before the transition continues */
+/**
+ * A [[TransitionHookFn]] which waits for the views to load
+ *
+ * Registered using `transitionService.onStart({}, loadEnteringViews);`
+ *
+ * Allows the views to do async work in [[ViewConfig.load]] before the transition continues.
+ * In angular 1, this includes loading the templates.
+ */
 export function loadEnteringViews(transition) {
   let enteringViews = transition.views("entering");
   if (!enteringViews.length) return;
   return services.$q.all(enteringViews.map(view => view.load())).then(noop);
 }
 
+/**
+ * A [[TransitionHookFn]] which activates the new views when a transition is successful.
+ *
+ * Registered using `transitionService.onSuccess({}, activateViews);`
+ *
+ * After a transition is complete, this hook deactivates the old views from the previous state,
+ * and activates the new views from the destination state.
+ *
+ * See [[ViewService]]
+ */
 export function activateViews(transition: Transition) {
   let enteringViews = transition.views("entering");
   let exitingViews = transition.views("exiting");

src/hooks/views.ts

@@ -1,13 +1,40 @@
+/** @module ng1 */ /** */
 import {State} from "../../state/stateObject";
 import {PathNode} from "../../path/node";
 import {ResolveContext} from "../../resolve/resolveContext";
 import {map} from "../../common/common";
 import {resolvablesBuilder} from "../../state/stateBuilder";
 
-export const resolveFactory = () => ({
+/**
+ * Implementation of the legacy `$resolve` service for angular 1.
+ */
+var $resolve = {
   /**
+   * Asynchronously injects a resolve block.
+   *
    * This emulates most of the behavior of the ui-router 0.2.x $resolve.resolve() service API.
-   * @param invocables an object, with keys as resolve names and values as injectable functions
+   *
+   * Given an object `invocables`, where keys are strings and values are injectable functions,
+   * injects each function, and waits for the resulting promise to resolve.
+   * When all resulting promises are resolved, returns the results as an object.
+   *
+   * @example
+   * ```js
+   *
+   * let invocables = {
+   *   foo: [ '$http', ($http) =>
+   *            $http.get('/api/foo').then(resp => resp.data) ],
+   *   bar: [ 'foo', '$http', (foo, $http) =>
+   *            $http.get('/api/bar/' + foo.barId).then(resp => resp.data) ]
+   * }
+   * $resolve.resolve(invocables)
+   *     .then(results => console.log(results.foo, results.bar))
+   * // Logs foo and bar:
+   * // { id: 123, barId: 456, fooData: 'foo data' }
+   * // { id: 456, barData: 'bar data' }
+   * ```
+   *
+   * @param invocables an object which looks like an [[StateDefinition.resolve]] object; keys are resolve names and values are injectable functions
    * @param locals key/value pre-resolved data (locals)
    * @param parent a promise for a "parent resolve"
    */
@@ -32,4 +59,7 @@ export const resolveFactory = () => ({
 
     return parent ? parent.then(resolveData) : resolveData({});
   }
-});
+};
+
+/** @hidden */
+export const resolveFactory = () => $resolve;

src/ng1/legacy/resolveService.ts

@@ -283,8 +283,26 @@ export const getLocals = (ctx: ResolveContext) => {
   return tuples.reduce(applyPairs, {});
 };
 
+/** Adds the angular 1 `$injector` to the `UiInjector` interface */
 declare module "../common/interface" {
+  /**
+   * This enhances the [[common.UiInjector]] interface by adding the `$injector` service as the [[native]] injector.
+   */
   interface UiInjector {
+    /**
+     * The native Angular 1 `$injector` service
+     *
+     * When you have access to a `UiInjector`, this property will contain the native `$injector` Angular 1 service.
+     *
+     * @example:
+     * ```js
+     *
+     * $transition.onStart({}, function(transition) {
+     *   var uiInjector = transition.injector();
+     *   var $injector = uiInjector.native;
+     *   var val = $injector.invoke(someFunction);
+     * });
+     */
     native: IInjectorService;
   }
 }