docs(*): replace javascript with js

docs(IHookRegistry): Start improving docs for hooks

Author: christopherthielen

src/state/interface.ts

@@ -55,7 +55,7 @@ export interface ViewDeclaration {
    * Injectable provider function that returns the actual controller function or name of a registered controller.
    *
    * @example 
-   * ```javascript
+   * ```js
    * 
    * controllerProvider: function(MyResolveData) {
    *   if (MyResolveData.foo) {
@@ -83,13 +83,13 @@ export interface ViewDeclaration {
    * If `template` is a function, it will be called with the State Parameters as the first argument.
    *
    * @example
-   * ```javascript
+   * ```js
    *
    * template: "<h1>inline template definition</h1><div ui-view></div>"
    * ```
    *
    * @example
-   * ```javascript
+   * ```js
    *
    * template: function(params) {
    *   return "<h1>generated template</h1>";
@@ -107,13 +107,13 @@ export interface ViewDeclaration {
    * If `templateUrl` is a function, it will be called with the State Parameters as the first argument.
    *
    * @example
-   * ```javascript
+   * ```js
    *
    * templateUrl: "/templates/home.html"
    * ```
    *
    * @example
-   * ```javascript
+   * ```js
    *
    * templateUrl: function(params) {
    *   return myTemplates[params.pageId];
@@ -128,7 +128,7 @@ export interface ViewDeclaration {
    * The template will be used to render the corresponding [[ui-view]] directive.
    *
    * @example
-   * ```javascript
+   * ```js
    *
    * templateProvider: function(MyTemplateService, params) {
    *   return MyTemplateService.getTemplate(params.pageId);
@@ -143,7 +143,7 @@ export interface ViewDeclaration {
  * It should be registered with the [[$stateProvider]].
  *
  * @example
- * ```javascript
+ * ```js
  *
  * // StateDeclaration object
  * var foldersState = {
@@ -184,7 +184,7 @@ export interface StateDeclaration extends ViewDeclaration {
    * names, e.g., `<a ui-sref="childstate">Child</a>` instead of `<a ui-sref="parentstate.childstate">Child</a>
    *
    * @example
-   * ```javascript
+   * ```js
    *
    * var parentstate = {
    *   name: 'parentstate'
@@ -210,7 +210,7 @@ export interface StateDeclaration extends ViewDeclaration {
    * - The value (function) is an injectable function which returns the dependency, or a promise for the dependency.
    *
    * @example
-   * ```javascript
+   * ```js
    *
    * resolve: {
    *   // If you inject `myStateDependency` into a controller, you'll get "abc"
@@ -258,7 +258,7 @@ export interface StateDeclaration extends ViewDeclaration {
    * - `$stateParams`: (deprecated) The parameters for the current state (Note: these parameter values are
    *
    * @example
-   * ```javascript
+   * ```js
    *
    * resolve: {
    *   // Define a resolve 'allusers' which delegates to the UserService
@@ -288,7 +288,7 @@ export interface StateDeclaration extends ViewDeclaration {
    * See [[UrlMatcher]] for details on acceptable patterns.
    *
    * @examples
-   * ```javascript
+   * ```js
    *
    * url: "/home"
    * // Define a parameter named 'userid'
@@ -316,7 +316,7 @@ export interface StateDeclaration extends ViewDeclaration {
    * parameters. For each parameter being configured, add a [[ParamDeclaration]] keyed to the name of the parameter.
    *
    * @example
-   * ```javascript
+   * ```js
    *
    * params: {
    *   param1: {
@@ -346,7 +346,7 @@ export interface StateDeclaration extends ViewDeclaration {
    *  Targets three named ui-views in the parent state's template
    *
    * @example
-   * ```javascript
+   * ```js
    *
    * views: {
    *   header: {
@@ -363,7 +363,7 @@ export interface StateDeclaration extends ViewDeclaration {
    * ```
    *
    * @example
-   * ```javascript
+   * ```js
    * // Targets named ui-view="header" from ancestor state 'top''s template, and
    * // named `ui-view="body" from parent state's template.
    * views: {

src/transition/hookRegistry.ts

@@ -75,68 +75,7 @@ export class HookRegistry implements IHookRegistry {
 
   getHooks = (name: string) => this._transitionEvents[name];
 
-  /**
-   * @ngdoc function
-   * @name ui.router.state.$transitionsProvider#onBefore
-   * @methodOf ui.router.state.$transitionsProvider
-   *
-   * @description
-   * Registers a function to be injected and invoked before a Transition begins.
-   *
-   * This function can be injected with one additional special value:
-   * - **`$transition$`**: The current transition
-   *
-   * @param {object} matchObject An object that specifies which transitions to invoke the callback for (typically this
-   * value will be {} for this callback, to match all invalid transitions)
-   *
-   * - **`to`** - {string|function=} - A glob string that matches the 'to' state's name.
-   *    Or, a function with the signature `function(state) {}` which should return a boolean to indicate if the state matches.
-   * - **`from`** - {string|function=} - A glob string that matches the 'from' state's name.
-   *    Or, a function with the signature `function(state) {}` which should return a boolean to indicate if the state matches.
-   *
-   * @param {function} callback
-   *   The function which will be injected and invoked, before a matching transition is started.
-   *   The function may optionally return a {boolean|Transition|object} value which will affect the current transition:
-   *
-   * @return
-   *     - **`false`** to abort the current transition
-   *     - **{Transition}** A Transition object from the $transition$.redirect() factory. If returned, the
-   *        current transition will be aborted and the returned Transition will supersede it.
-   *     - **{object}** A map of resolve functions to be added to the current transition. These resolves will be made
-   *        available for injection to further steps in the transition.  The object should have {string}s for keys and
-   *        {function}s for values, like the `resolve` object in {@link ui.router.state.$stateProvider#state $stateProvider.state}.
-   */
   onBefore = makeHookRegistrationFn(this._transitionEvents, "onBefore");
-
-  /**
-   * @ngdoc function
-   * @name ui.router.state.$transitionsProvider#onStart
-   * @methodOf ui.router.state.$transitionsProvider
-   *
-   * @description
-   * Registers a function to be injected and invoked when a transition has begun.  The function is injected in the
-   * destination state's ResolveContext. This function can be injected with one additional special value:
-   *
-   *  - **`$transition$`**: The current transition
-   *
-   * @param {object} matchObject An object that specifies which transitions to invoke the callback for
-   *
-   * - **`to`** - {string|function=} - A glob string that matches the 'to' state's name.
-   *    Or, a function with the signature `function(state) {}` which should return a boolean to indicate if the state matches.
-   * - **`from`** - {string|function=} - A glob string that matches the 'from' state's name.
-   *    Or, a function with the signature `function(state) {}` which should return a boolean to indicate if the state matches.
-   *
-   * @param {function} callback
-   *   The function which will be injected and invoked, when a matching transition is started.
-   *   The function may optionally return a {boolean|Transition|object} value which will affect the current transition:
-   *
-   *     - **`false`** to abort the current transition
-   *     - **{Transition}** A Transition object from the $transition$.redirect() factory. If returned, the
-   *        current transition will be aborted and the returned Transition will supersede it.
-   *     - **{object}** A map of resolve functions to be added to the current transition. These resolves will be made
-   *        available for injection to further steps in the transition.  The object should have {string}s for keys and
-   *        {function}s for values, like the `resolve` object in {@link ui.router.state.$stateProvider#state $stateProvider.state}.
-   */
   onStart = makeHookRegistrationFn(this._transitionEvents, "onStart");
 
   /**

src/transition/interface.ts

@@ -68,7 +68,7 @@ export interface TransitionOptions {
    */
   reload      ?: (boolean|string|StateDeclaration|State);
   /**
-   * You can define your own Transition Options inside this property and use them, e.g., from a [[TransitionHook]]
+   * You can define your own Transition Options inside this property and use them, e.g., from a Transition Hook
    */
   custom      ?: any;
   /** @internal */
@@ -153,22 +153,130 @@ export interface ITransitionService extends IHookRegistry {
 export type IHookGetter = (hookName: string) => IEventHook[];
 export type IHookRegistration = (matchObject: IMatchCriteria, callback: IInjectable, options?) => Function;
 
+/**
+ * This interface has the registration functions for Transition Hook instances.  Both the
+ * [[TransitionService]] and also the [[Transition]] object itself implement this interface.
+ */
 export interface IHookRegistry {
-  onBefore:   IHookRegistration;
-  onStart:    IHookRegistration;
-  onEnter:    IHookRegistration;
-  onRetain:   IHookRegistration;
-  onExit:     IHookRegistration;
-  onFinish:   IHookRegistration;
-  onSuccess:  IHookRegistration;
-  onError:    IHookRegistration;
-
-  getHooks:   IHookGetter;
+  /**
+   * Registers a function as an `onBefore` Transition Hook.
+   *
+   * `onBefore` hooks are injected and invoked *before* a Transition starts.
+   *
+   * They are invoked synchronously, in priority order, and are typically within the same call stack as
+   * [[StateService.transitionTo]].
+   *
+   * The current [[Transition]] can be injected as `$transition$`
+   *
+   * The callback function may return one of three things
+   *     - `false` to abort the current transition
+   *     - A [[TargetState]] object from the $state.target() factory. This will redirect the current transition
+   *     to the target state.
+   *     - A promise
+   *
+   * @param matchObject An [[IMatchCriteria]] which defines which Transitions the Hook should be invoked for.
+   * @param callback The function which will be injected and invoked.
+   * @returns A function which deregisters the hook.
+   */
+  onBefore(matchObject: IMatchCriteria, callback: IInjectable, options?): Function;
+
+  /**
+   * Registers a function to be injected and invoked when a transition has started.
+   *
+   * The function is injected in the destination state's ResolveContext. This function can be injected
+   * with one additional special value:
+   *
+   *  -`$transition$`: The current [[Transition]]
+   *
+   * @param {object} matchObject An object that specifies which transitions to invoke the callback for
+   *
+   * - **`to`** - {string|function=} - A glob string that matches the 'to' state's name.
+   *    Or, a function with the signature `function(state) {}` which should return a boolean to indicate if the state matches.
+   * - **`from`** - {string|function=} - A glob string that matches the 'from' state's name.
+   *    Or, a function with the signature `function(state) {}` which should return a boolean to indicate if the state matches.
+   *
+   * @param {function} callback
+   *   The function which will be injected and invoked, when a matching transition is started.
+   *   The function may optionally return a {boolean|Transition|object} value which will affect the current transition:
+   *
+   *     - **`false`** to abort the current transition
+   *     - **{Transition}** A Transition object from the $transition$.redirect() factory. If returned, the
+   *        current transition will be aborted and the returned Transition will supersede it.
+   *     - **{object}** A map of resolve functions to be added to the current transition. These resolves will be made
+   *        available for injection to further steps in the transition.  The object should have {string}s for keys and
+   *        {function}s for values, like the `resolve` object in {@link ui.router.state.$stateProvider#state $stateProvider.state}.
+   */
+  onStart(matchObjectIMatchCriteria, callbackIInjectable, options?): Function;
+  onEnter(matchObjectIMatchCriteria, callbackIInjectable, options?): Function;
+  onRetain(matchObjectIMatchCriteria, callbackIInjectable, options?): Function;
+  onExit(matchObjectIMatchCriteria, callbackIInjectable, options?): Function;
+  onFinish(matchObjectIMatchCriteria, callbackIInjectable, options?): Function;
+  onSuccess(matchObjectIMatchCriteria, callbackIInjectable, options?): Function;
+  onError(matchObjectIMatchCriteria, callbackIInjectable, options?): Function;
+
+  getHooks(hookNamestring): IEventHook[];
 }
 
 export type IStateMatch = Predicate<State>
+/**
+ * This object is used to configure whether or not a Transition Hook is invoked for a particular transition,
+ * based on the Transition's "to state" and "from state".
+ *
+ * The `to` and `from` can be state globs, or a function that takes a state.
+ * Both `to` and `from` are optional.  If one of these is omitted, it is replaced with the
+ * function: `function() { return true; }`, which effectively matches any state.
+ *
+ * @example
+ * ```js
+ *
+ * // This matches a transition coming from the `parent` state and going to the `parent.child` state.
+ * var match = {
+ *   to: 'parent',
+ *   from: 'parent.child'
+ * }
+ * ```
+ *
+ * @example
+ * ```js
+ *
+ * // This matches a transition coming from any substate of `parent` and going directly to the `parent` state.
+ * var match = {
+ *   to: 'parent',
+ *   from: 'parent.**'
+ * }
+ * ```
+ *
+ * @example
+ * ```js
+ *
+ * // This matches a transition coming from any state and going to any substate of `mymodule`
+ * var match = {
+ *   to: 'mymodule.**'
+ * }
+ * ```
+ *
+ * @example
+ * ```js
+ *
+ * // This matches a transition coming from any state and going to any state that has `data.authRequired`
+ * // set to a truthy value.
+ * var match = {
+ *   to: function(state) { return !!state.data.authRequired; }
+ * }
+ * ```
+ */
 export interface IMatchCriteria {
+  /**
+   * A glob string that matches the 'to' state's name.
+   * Or, a function with the signature `function(state) {}` which should return a boolean to indicate if the state matches.
+   */
   to?: (string|IStateMatch);
+
+  /**
+   *  A glob string that matches the 'from' state's name.
+   *  Or, a function with the signature `function(State) { return boolean; }` which should return a boolean to
+   *  indicate if the state matches.
+   */
   from?: (string|IStateMatch);
 }
 

src/transition/transitionService.ts

@@ -9,6 +9,9 @@ import {Transition} from "./transition";
 import {HookRegistry} from "./hookRegistry";
 import {TargetState} from "../state/module";
 import {Node} from "../path/module";
+import {IMatchCriteria} from "./interface";
+import {IInjectable} from "../common/common";
+import {IEventHook} from "./interface";
 
 /**
  * The default transition options.
@@ -31,16 +34,17 @@ class TransitionService implements ITransitionService, IHookRegistry {
     this._reinit();
   }
 
-  onBefore  : IHookRegistration;
-  onStart   : IHookRegistration;
-  onEnter   : IHookRegistration;
-  onRetain  : IHookRegistration;
-  onExit    : IHookRegistration;
-  onFinish  : IHookRegistration;
-  onSuccess : IHookRegistration;
-  onError   : IHookRegistration;
-
-  getHooks  : IHookGetter;
+  /** @inheritdoc */
+  onBefore  : (matchObject: IMatchCriteria, callback: IInjectable, options?) => Function;
+  onStart   : (matchObject: IMatchCriteria, callback: IInjectable, options?) => Function;
+  onEnter   : (matchObject: IMatchCriteria, callback: IInjectable, options?) => Function;
+  onRetain  : (matchObject: IMatchCriteria, callback: IInjectable, options?) => Function;
+  onExit    : (matchObject: IMatchCriteria, callback: IInjectable, options?) => Function;
+  onFinish  : (matchObject: IMatchCriteria, callback: IInjectable, options?) => Function;
+  onSuccess : (matchObject: IMatchCriteria, callback: IInjectable, options?) => Function;
+  onError   : (matchObject: IMatchCriteria, callback: IInjectable, options?) => Function;
+
+  getHooks  : (hookName: string) => IEventHook[];
 
   private _defaultErrorHandler: ((_error) => void) = function $defaultErrorHandler($error$) {
     if ($error$ instanceof Error) console.log($error$);