Started adding some typedoc documentation

Author: christopherthielen

README.md

@@ -29,7 +29,7 @@ The transition lifecycle hooks are currently:
 When registering a hook, you can provide criteria (a state name, a glob, or a function), and you can modify the transition by returning something from the hook (an abort, a redirect, a promise, or some new resolves to add to the transition).
 
 This enables lots of fun stuff!  Here are a couple of possibilities to get your imagination started:
-```
+```javascript
 $transitionsProvider.onBefore({ to: 'my.state', from: '*' }, function(AsyncService) {
   return AsyncService.doSomeAsyncThing();
 });

src/common/angular1.ts

@@ -1,3 +1,4 @@
+/** @module common */ /** for typedoc */
 /// <reference path='../../typings/angularjs/angular.d.ts' />
 import {IQService} from "angular";
 

src/common/common.ts

@@ -1,3 +1,4 @@
+/** @module common */ /** for typedoc */
 /// <reference path='../../typings/angularjs/angular.d.ts' />
 let { isDefined, isFunction, isNumber, isString, isObject, isArray, forEach, extend, copy, noop, toJson, fromJson, equals, identity } = angular;
 export { isDefined, isFunction, isNumber, isString, isObject, isArray, forEach, extend, copy, noop, toJson, fromJson, equals, identity };

src/common/module.ts

@@ -1,3 +1,4 @@
+/** @module common */ /** for typedoc */
 export * from "./angular1";
 export * from "./common";
 export * from "./queue";

src/common/queue.ts

@@ -1,3 +1,4 @@
+/** @module common */ /** for typedoc */
 import {map} from "./common"
 
 export class Queue<T> {

src/common/trace.ts

@@ -1,8 +1,9 @@
+/** @module common */ /** for typedoc */
 import {isNull, isPromise, isNumber, fnToString, maxLength, padString, isInjectable, is, invoke, not, val, pattern, parse, isDefined, identity} from "../common/common";
 import {Resolvable}  from "../resolve/resolvable";
 import {Transition}  from "../transition/transition";
 import {TransitionRejection}  from "../transition/rejectFactory";
-import {IUiViewData}  from "../view/interface";
+import {UIViewData}  from "../view/interface";
 import {ViewConfig}  from "../view/view";
 
 function promiseToString(p) {
@@ -170,22 +171,22 @@ class Trace {
     console.log(`Transition #${tid} Digest #${digest}: <- Success  ${transitionStr}, final state: ${state}`);
   }
 
-  traceUiViewEvent(event: string, viewData: IUiViewData, extra = "") {
+  traceUiViewEvent(event: string, viewData: UIViewData, extra = "") {
     if (!this.enabled(Category.UIVIEW)) return;
     console.log(`ui-view: ${padString(30, event)} ${uiViewString(viewData)}${extra}`);
   }
 
-  traceUiViewConfigUpdated(viewData: IUiViewData, context) {
+  traceUiViewConfigUpdated(viewData: UIViewData, context) {
     if (!this.enabled(Category.UIVIEW)) return;
     this.traceUiViewEvent("Updating", viewData, ` with ViewConfig from context='${context}'`);
   }
 
-  traceUiViewScopeCreated(viewData: IUiViewData, newScope) {
+  traceUiViewScopeCreated(viewData: UIViewData, newScope) {
     if (!this.enabled(Category.UIVIEW)) return;
     this.traceUiViewEvent("Created scope for", viewData, `, scope #${newScope.$id}`);
   }
 
-  traceUiViewFill(viewData: IUiViewData, html) {
+  traceUiViewFill(viewData: UIViewData, html) {
     if (!this.enabled(Category.UIVIEW)) return;
     this.traceUiViewEvent("Fill", viewData, ` with: ${maxLength(200, html)}`);
   }
@@ -195,7 +196,7 @@ class Trace {
     console.log(`$view.ViewConfig: ${event} ${viewConfigString(viewConfig)}`);
   }
 
-  traceViewServiceUiViewEvent(event: string, viewData: IUiViewData) {
+  traceViewServiceUiViewEvent(event: string, viewData: UIViewData) {
     if (!this.enabled(Category.VIEWCONFIG)) return;
     console.log(`$view.ViewConfig: ${event} ${uiViewString(viewData)}`);
   }

src/params/interface.ts

@@ -1,4 +1,111 @@
-export interface IRawParams {
-    [key: string]: any
+/** @module params */ /** for typedoc */
+import {Type} from "./type";
+
+export interface RawParams {
+  [key: string]: any
 }
-export type IParamsOrArray = (IRawParams|IRawParams[]);
+
+export type ParamsOrArray = (RawParams|RawParams[]);
+
+/**
+ * Inside the [[StateDeclaration.params]] object of a [[StateDeclaration]]:
+ * A ParamDeclaration object defines how a single State Parameter should work.
+ *
+ * @example ---
+ *
+ * ```
+ * var mystate = {
+ *   template: '<div ui-view/>',
+ *   controller: function() {}
+ *   url: '/mystate/:param1',
+ *   params: {
+ *     param1: "index",         // Default value for 'param1'
+ *
+ *     nonUrlParam: {           // ParamDeclaration for 'nonUrlParam' starts
+ *      type: "int",            // non
+ *      array: true,
+ *      value: []
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface ParamDeclaration {
+  /**
+   * Specifies the default value for this parameter. This implicitly sets this parameter as optional.
+   *
+   * When UI-Router routes to a state and no value is specified for this parameter in the URL or transition,
+   * the default value will be used instead. If value is a function, it will be injected and invoked, and the
+   * return value used.
+   *
+   * Note:  `value: undefined` is treated as though no default value was specified, while `value: null` is treated
+   * as "the default value is null".
+   *
+   * ```
+   * // define default values for param1 and param2
+   * params: {
+   *   param1: {
+   *     value: "defaultValue"
+   *   },
+   *   param2: {
+   *     value: "param2Default;
+   *   }
+   * }
+   *```
+   *
+   * Shorthand: If you only need to configure the default value of the parameter, you may use a shorthand syntax.
+   * In the params map, instead mapping the param name to a full parameter configuration object, simply set map it
+   * to the default parameter value, e.g.:
+   * ```
+   * // define a parameter's default value
+   * params: {
+   *   param1: {
+   *     value: "defaultValue"
+   *   },
+   *   param2: {
+   *     value: "param2Default;
+   *   }
+   * }
+   *
+   * // shorthand default values
+   * params: {
+   *   param1: "defaultValue",
+   *   param2: "param2Default"
+   * }
+   ```
+   *
+   * This defines a default value for the parameter.  If the parameter value is `undefined`, this value will be used instead
+   */
+  value?: any;
+
+  /**
+   * Specifies the parameter type.
+   *
+   * Supplying a parameter type
+   */
+  type: (string|Type);
+  array: boolean;
+  squash: (boolean|string);
+  replace: any;
+  /** @internal */
+  isOptional: boolean;
+  dynamic: boolean;
+}
+
+/**
+ * Inside a state definition:
+ * A nested object named `params` which defines state parameter customizations.
+ *
+ * The ParamDeclaration contains configuration for state parameter declarations.
+ * Keys should be the name of the parameter and values are treated as [[ParamDeclaration]] objects.
+ *
+ * #### example:
+ * ```
+ * params: {
+ *   folder: {
+ *     value: "index",
+ *     squash: true
+ *   }
+ * }```
+ */
+export interface ParamsConfig { [key: string]: ParamDeclaration }

src/params/module.ts

@@ -1,3 +1,11 @@
+/**
+ * This module contains code for State Parameters.
+ *
+ * See [[ParamDeclaration]]
+ * @module params
+ * @preferred doc
+ */
+/**!*/
 export * from "./param";
 export * from "./paramTypes";
 export * from "./type";

src/params/param.ts

@@ -1,5 +1,6 @@
+/** @module params */ /** for typedoc */
 import {isInjectable, extend, isDefined, isString, isArray, filter, map, pick, prop, propEq, curry, applyPairs} from "../common/common";
-import {IRawParams} from "../params/interface";
+import {RawParams} from "../params/interface";
 import {runtime} from "../common/angular1";
 import {matcherConfig} from "../url/urlMatcherConfig";
 import {paramTypes} from "./paramTypes";
@@ -145,9 +146,9 @@ export class Param {
     return new Param(id, type, config, DefType.SEARCH);
   }
 
-  static values(params: Param[], values): IRawParams {
+  static values(params: Param[], values): RawParams {
     values = values || {};
-    return <IRawParams> params.map(param => [param.id, param.value(values[param.id])]).reduce(applyPairs, {});
+    return <RawParams> params.map(param => [param.id, param.value(values[param.id])]).reduce(applyPairs, {});
   }
 
   static equals(params: Param[], values1, values2): boolean {

src/params/paramTypes.ts

@@ -1,3 +1,4 @@
+/** @module params */ /** for typedoc */
 import {isDefined, fromJson, toJson, is, identity, equals, inherit, map, extend, val} from "../common/common";
 import {Type} from "./type";
 import {runtime} from "../common/angular1";