docs(*): organize docs modules; update some docs to typedoc

Author: christopherthielen

src/common/common.ts

@@ -1,4 +1,8 @@
-/** @module common */ /** for typedoc */
+/**
+ * Random utility functions used in the UI-Router code
+ *
+ * @preferred @module common
+ */ /** for typedoc */
 
 import {isFunction, isString, isArray, isRegExp, isDate} from "./predicates";
 import { all, any, not, prop, curry } from "./hof";

src/common/hof.ts

@@ -1,7 +1,7 @@
 /**
  * Higher order functions
  *
- * @module common
+ * @module common_hof
  */
 
 /**

src/common/predicates.ts

@@ -1,4 +1,4 @@
-/** Predicates @module common */ /** */
+/** Predicates @module common_predicates */ /** */
 import {and, not, pipe, prop} from "./hof";
 
 const toStr = Object.prototype.toString;

src/common/strings.ts

@@ -1,4 +1,4 @@
-/** @module common */ /** */
+/** @module common_strings */ /** */
 
 import {isString, isArray, isDefined, isNull, isPromise, isInjectable, isObject} from "./predicates";
 import {TransitionRejection} from "../transition/rejectFactory";

src/common/trace.ts

@@ -1,36 +1,87 @@
-/** @module common */ /** for typedoc */
+/**
+ * UI-Router Transition Tracing
+ *
+ * Enable transition tracing to print transition information to the console, in order to help debug your application.
+ * Tracing logs detailed information about each Transition to your console.
+ *
+ * To enable tracing, import the [[trace]] singleton and enable one or more categories.
+ *
+ * ES6
+ * ```
+ *
+ * import {trace} from "ui-router-ng2"; // or "angular-ui-router"
+ * trace.enable(1, 5); // TRANSITION and VIEWCONFIG
+ * ```
+ *
+ * CJS
+ * ```
+ *
+ * let trace = require("angular-ui-router").trace; // or "ui-router-ng2"
+ * trace.enable("TRANSITION", "VIEWCONFIG");
+ * ```
+ *
+ * Globals
+ * ```
+ *
+ * let trace = window["angular-ui-router"].trace; // or "ui-router-ng2"
+ * trace.enable(); // Trace everything (very verbose)
+ * ```
+ *
+ * @module trace
+ */ /** for typedoc */
 import {parse} from "../common/hof";
 import {isNumber} from "../common/predicates";
 import {Transition}  from "../transition/transition";
 import {ActiveUIView, ViewConfig}  from "../view/interface";
 import {stringify, functionToString, maxLength, padString} from "./strings";
 
+/** @hidden */
 function uiViewString (viewData) {
     if (!viewData) return 'ui-view (defunct)';
     return `ui-view id#${viewData.id}, contextual name '${viewData.name}@${viewData.creationContext}', fqn: '${viewData.fqn}'`;
 }
 
+/** @hidden */
 const viewConfigString = (viewConfig: ViewConfig) =>
     `ViewConfig targeting ui-view: '${viewConfig.viewDecl.$uiViewName}@${viewConfig.viewDecl.$uiViewContextAnchor}', context: '${viewConfig.viewDecl.$context.name}'`;
 
+/** @hidden */
 function normalizedCat(input: Category): string {
   return isNumber(input) ? Category[input] : Category[Category[input]];
 }
 
 
+/**
+ * Trace categories
+ *
+ * [[Trace.enable]] or [[Trace.disable]] a category
+ *
+ * `trace.enable(Category.TRANSITION)`
+ *
+ * These can also be provided using a matching string, or position ordinal
+ *
+ * `trace.enable("TRANSITION")`
+ *
+ * `trace.enable(1)`
+ */
 export enum Category {
   RESOLVE, TRANSITION, HOOK, INVOKE, UIVIEW, VIEWCONFIG
 }
 
+/**
+ * Prints UI-Router Transition trace information to the console.
+ */
 export class Trace {
   approximateDigests: number;
 
   constructor() {
     this.approximateDigests = 0;
   }
 
+  /** @hidden */
   private _enabled: { [key: string]: boolean } = {};
 
+   /** @hidden */
   private _set(enabled: boolean, categories: Category[]) {
     if (!categories.length) {
       categories = Object.keys(Category)
@@ -40,16 +91,43 @@ export class Trace {
     categories.map(normalizedCat).forEach(category => this._enabled[category] = enabled);
   }
 
-  // TODO: Document enable(categories)
-  enable = (...categories: Category[]) => this._set(true, categories);
-  // TODO: Document disable(categories)
-  disable = (...categories: Category[]) => this._set(false, categories);
+  /**
+   * Enables a trace [[Category]]
+   *
+   * ```
+   * trace.enable("TRANSITION");
+   * ```
+   *
+   * @param categories categories to enable. If `categories` is omitted, all categories are enabled.
+   *        Also takes strings (category name) or ordinal (category position)
+   */
+  enable(...categories: Category[]) { this._set(true, categories) }
+  /**
+   * Disables a trace [[Category]]
+   *
+   * ```
+   * trace.disable("VIEWCONFIG");
+   * ```
+   *
+   * @param categories categories to disable. If `categories` is omitted, all categories are disabled.
+   *        Also takes strings (category name) or ordinal (category position)
+   */
+  disable(...categories: Category[]) { this._set(false, categories) }
 
-  // TODO: Document enabled(category)
-  enabled(category: Category) {
+  /**
+   * Retrieves the enabled stateus of a [[Category]]
+   *
+   * ```
+   * trace.enabled("VIEWCONFIG"); // true or false
+   * ```
+   *
+   * @returns boolean true if the category is enabled
+   */
+  enabled(category: Category): boolean {
     return !!this._enabled[normalizedCat(category)];
   }
 
+  /** called by ui-router code */
   traceTransitionStart(transition: Transition) {
     if (!this.enabled(Category.TRANSITION)) return;
     let tid = transition.$id,
@@ -58,6 +136,7 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}: Started  -> ${transitionStr}`);
   }
 
+  /** called by ui-router code */
   traceTransitionIgnored(transition: Transition) {
     if (!this.enabled(Category.TRANSITION)) return;
     let tid = transition.$id,
@@ -66,6 +145,7 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}: Ignored  <> ${transitionStr}`);
   }
 
+  /** called by ui-router code */
   traceHookInvocation(step, options) {
     if (!this.enabled(Category.HOOK)) return;
     let tid = parse("transition.$id")(options),
@@ -76,6 +156,7 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}:   Hook -> ${event} context: ${context}, ${maxLength(200, name)}`);
   }
 
+  /** called by ui-router code */
   traceHookResult(hookResult, transitionResult, transitionOptions) {
     if (!this.enabled(Category.HOOK)) return;
     let tid = parse("transition.$id")(transitionOptions),
@@ -85,6 +166,7 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}:   <- Hook returned: ${maxLength(200, hookResultStr)}, transition result: ${maxLength(200, transitionResultStr)}`);
   }
 
+  /** called by ui-router code */
   traceResolvePath(path, options) {
     if (!this.enabled(Category.RESOLVE)) return;
     let tid = parse("transition.$id")(options),
@@ -94,6 +176,7 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}:         Resolving ${pathStr} (${policyStr})`);
   }
 
+  /** called by ui-router code */
   traceResolvePathElement(pathElement, resolvablePromises, options) {
     if (!this.enabled(Category.RESOLVE)) return;
     if (!resolvablePromises.length) return;
@@ -105,6 +188,7 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}:         Resolve ${pathElementStr} resolvables: [${resolvablePromisesStr}] (${policyStr})`);
   }
 
+  /** called by ui-router code */
   traceResolveResolvable(resolvable, options) {
     if (!this.enabled(Category.RESOLVE)) return;
     let tid = parse("transition.$id")(options),
@@ -113,6 +197,7 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}:               Resolving -> ${resolvableStr}`);
   }
 
+  /** called by ui-router code */
   traceResolvableResolved(resolvable, options) {
     if (!this.enabled(Category.RESOLVE)) return;
     let tid = parse("transition.$id")(options),
@@ -122,6 +207,7 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}:               <- Resolved  ${resolvableStr} to: ${maxLength(200, result)}`);
   }
 
+  /** called by ui-router code */
   tracePathElementInvoke(node, fn, deps, options) {
     if (!this.enabled(Category.INVOKE)) return;
     let tid = parse("transition.$id")(options),
@@ -131,6 +217,7 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}:         Invoke ${options.when}: context: ${stateName} ${maxLength(200, fnName)}`);
   }
 
+  /** called by ui-router code */
   traceError(error, transition: Transition) {
     if (!this.enabled(Category.TRANSITION)) return;
     let tid = transition.$id,
@@ -139,6 +226,7 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}: <- Rejected ${transitionStr}, reason: ${error}`);
   }
 
+  /** called by ui-router code */
   traceSuccess(finalState, transition: Transition) {
     if (!this.enabled(Category.TRANSITION)) return;
     let tid = transition.$id,
@@ -148,36 +236,52 @@ export class Trace {
     console.log(`Transition #${tid} Digest #${digest}: <- Success  ${transitionStr}, final state: ${state}`);
   }
 
+  /** called by ui-router code */
   traceUiViewEvent(event: string, viewData: ActiveUIView, extra = "") {
     if (!this.enabled(Category.UIVIEW)) return;
     console.log(`ui-view: ${padString(30, event)} ${uiViewString(viewData)}${extra}`);
   }
 
+  /** called by ui-router code */
   traceUiViewConfigUpdated(viewData: ActiveUIView, context) {
     if (!this.enabled(Category.UIVIEW)) return;
     this.traceUiViewEvent("Updating", viewData, ` with ViewConfig from context='${context}'`);
   }
 
+  /** called by ui-router code */
   traceUiViewScopeCreated(viewData: ActiveUIView, newScope) {
     if (!this.enabled(Category.UIVIEW)) return;
     this.traceUiViewEvent("Created scope for", viewData, `, scope #${newScope.$id}`);
   }
 
+  /** called by ui-router code */
   traceUiViewFill(viewData: ActiveUIView, html) {
     if (!this.enabled(Category.UIVIEW)) return;
     this.traceUiViewEvent("Fill", viewData, ` with: ${maxLength(200, html)}`);
   }
 
+  /** called by ui-router code */
   traceViewServiceEvent(event: string, viewConfig: ViewConfig) {
     if (!this.enabled(Category.VIEWCONFIG)) return;
     console.log(`$view.ViewConfig: ${event} ${viewConfigString(viewConfig)}`);
   }
 
+  /** called by ui-router code */
   traceViewServiceUiViewEvent(event: string, viewData: ActiveUIView) {
     if (!this.enabled(Category.VIEWCONFIG)) return;
     console.log(`$view.ViewConfig: ${event} ${uiViewString(viewData)}`);
   }
 }
 
+/**
+ * The [[Trace]] singleton
+ *
+ * @example
+ * ```js
+ *
+ * import {trace} from "angular-ui-router";
+ * trace.enable(1, 5);
+ * ```
+ */
 let trace = new Trace();
 export {trace};

src/core.ts

@@ -1,4 +1,4 @@
-/** @module core */ /** */
+/** @module common */ /** */
 
 export * from "./common/module";
 export * from "./params/module";

src/globals.ts

@@ -1,4 +1,4 @@
-/** @module common */ /** */
+/** @module core */ /** */
 import {StateParams} from "./params/stateParams";
 import {StateDeclaration} from "./state/interface";
 import {State} from "./state/stateObject";
@@ -9,6 +9,9 @@ import {copy} from "./common/common";
 
 /**
  * Global mutable state
+ *
+ * This is where we hold the global mutable state such as current state, current
+ * params, current transition, last successful transition, last attempted transition, etc.
  */
 export class UIRouterGlobals {
   /**

src/ng1/interface.ts

@@ -26,6 +26,49 @@ import {Transition} from "../transition/transition";
  *   }
  * }
  * ```
+ *
+ * Since this interface extends [[Ng1ViewDeclaration]], any view declaration properties can be set directly
+ * on the state declaration and they will be applied to the view with the name `$default`.  For example:
+ *
+ * ```js
+ * var state = {
+ *   name: 'foo',
+ *   url: '/foo',
+ *   template: '<h1>foo</h1>',
+ *   controller: 'FooController'
+ * }
+ * ```
+ *
+ * is simply syntactic sugar for:
+ *
+ * ```js
+ * var state = {
+ *   name: 'foo',
+ *   url: '/foo',
+ *   views: {
+ *     $default: {
+ *       template: '<h1>foo</h1>',
+ *       controller: 'FooController
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * If a state definition contains a `views:` object, any view properties set directly on the state are ignored.
+ * Thus, this is an invalid state defintion:
+ *
+ * ```js
+ * var state = {
+ *   name: 'foo',
+ *   url: '/foo',
+ *   controller: 'FooController, // invalid because views: exists
+ *   views: {
+ *     header: {
+ *       template: '<h1>header</h1>'
+ *     }
+ *   }
+ * }
+ * ```
  */
 export interface Ng1StateDeclaration extends StateDeclaration, Ng1ViewDeclaration {
   /**

src/ng1/services.ts

@@ -1,5 +1,5 @@
 /**
- * Angular 1 plugin:
+ * # UI-Router for Angular 1
  *
  * - Provides an implementation for the [[CoreServices]] API, based on angular 1 services.
  * - Also registers some services with the angular 1 injector.