Skip to content

Commit

Permalink
docs(*): organize docs modules; update some docs to typedoc
Browse files Browse the repository at this point in the history
  • Loading branch information
christopherthielen committed Apr 3, 2016
1 parent 46cdf4c commit b8412da
Show file tree
Hide file tree
Showing 22 changed files with 481 additions and 134 deletions.
6 changes: 5 additions & 1 deletion src/common/common.ts
Original file line number Diff line number Diff line change
@@ -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";
Expand Down
2 changes: 1 addition & 1 deletion src/common/hof.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
/**
* Higher order functions
*
* @module common
* @module common_hof
*/

/**
Expand Down
2 changes: 1 addition & 1 deletion src/common/predicates.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/** Predicates @module common */ /** */
/** Predicates @module common_predicates */ /** */
import {and, not, pipe, prop} from "./hof";

const toStr = Object.prototype.toString;
Expand Down
2 changes: 1 addition & 1 deletion src/common/strings.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/** @module common */ /** */
/** @module common_strings */ /** */

import {isString, isArray, isDefined, isNull, isPromise, isInjectable, isObject} from "./predicates";
import {TransitionRejection} from "../transition/rejectFactory";
Expand Down
118 changes: 111 additions & 7 deletions src/common/trace.ts
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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),
Expand All @@ -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),
Expand All @@ -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),
Expand All @@ -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;
Expand All @@ -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),
Expand All @@ -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),
Expand All @@ -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),
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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};
2 changes: 1 addition & 1 deletion src/core.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/** @module core */ /** */
/** @module common */ /** */

export * from "./common/module";
export * from "./params/module";
Expand Down
5 changes: 4 additions & 1 deletion src/globals.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/** @module common */ /** */
/** @module core */ /** */
import {StateParams} from "./params/stateParams";
import {StateDeclaration} from "./state/interface";
import {State} from "./state/stateObject";
Expand All @@ -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 {
/**
Expand Down
43 changes: 43 additions & 0 deletions src/ng1/interface.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
/**
Expand Down
2 changes: 1 addition & 1 deletion src/ng1/services.ts
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
Loading

0 comments on commit b8412da

Please sign in to comment.