docs(vanilla): Added docs for vanilla code

Author: christopherthielen

src/router.ts

@@ -69,9 +69,9 @@ export class UIRouter {
     this.disposable(this.urlRouterProvider);
     this.disposable(this.urlRouter);
     this.disposable(this.stateRegistry);
-
   }
 
+  /** @hidden */
   private _plugins: { [key: string]: UIRouterPlugin } = {};
 
   /**

src/vanilla/$injector.ts

@@ -1,18 +1,74 @@
+/** @internalapi @module vanilla */ /** */
 import {
     extend, assertPredicate, isFunction, isArray, isInjectable, $InjectorLike, IInjectable
 } from "../common/module";
 
-/** angular1-like injector api */
 // globally available injectables
 let globals = {};
 let STRIP_COMMENTS = /((\/\/.*$)|(\/\*[\s\S]*?\*\/))/mg;
 let ARGUMENT_NAMES = /([^\s,]+)/g;
 
+/**
+ * A basic angular1-like injector api
+ *
+ * This object implements four methods similar to the
+ * [angular 1 dependency injector](https://docs.angularjs.org/api/auto/service/$injector)
+ *
+ * UI-Router evolved from an angular 1 library to a framework agnostic library.
+ * However, some of the `ui-router-core` code uses these ng1 style APIs to support ng1 style dependency injection.
+ *
+ * This object provides a naive implementation of a globally scoped dependency injection system.
+ * It supports the following DI approaches:
+ *
+ * ### Function parameter names
+ *
+ * A function's `.toString()` is called, and the parameter names are parsed.
+ * This only works when the parameter names aren't "mangled" by a minifier such as UglifyJS.
+ *
+ * ```js
+ * function injectedFunction(FooService, BarService) {
+ *   // FooService and BarService are injected
+ * }
+ * ```
+ *
+ * ### Function annotation
+ *
+ * A function may be annotated with an array of dependency names as the `$inject` property.
+ *
+ * ```js
+ * injectedFunction.$inject = [ 'FooService', 'BarService' ];
+ * function injectedFunction(fs, bs) {
+ *   // FooService and BarService are injected as fs and bs parameters
+ * }
+ * ```
+ *
+ * ### Array notation
+ *
+ * An array provides the names of the dependencies to inject (as strings).
+ * The function is the last element of the array.
+ *
+ * ```js
+ * [ 'FooService', 'BarService', function (fs, bs) {
+ *   // FooService and BarService are injected as fs and bs parameters
+ * }]
+ * ```
+ *
+ * @type {$InjectorLike}
+ */
 export const $injector = {
+  /** Gets an object from DI based on a string token */
   get: name => globals[name],
 
+  /** Returns true if an object named `name` exists in global DI */
   has: (name) => $injector.get(name) != null,
 
+  /**
+   * Injects a function
+   *
+   * @param fn the function to inject
+   * @param context the function's `this` binding
+   * @param locals An object with additional DI tokens and values, such as `{ someToken: { foo: 1 } }`
+   */
   invoke: (fn: IInjectable, context?, locals?) => {
     let all = extend({}, globals, locals || {});
     let params = $injector.annotate(fn);
@@ -22,6 +78,12 @@ export const $injector = {
     else return (fn as any[]).slice(-1)[0].apply(context, args);
   },
 
+  /**
+   * Returns a function's dependencies
+   *
+   * Analyzes a function (or array) and returns an array of DI tokens that the function requires.
+   * @return an array of `string`s
+   */
   annotate: (fn: IInjectable): any[] => {
     if (!isInjectable(fn)) throw new Error(`Not an injectable function: ${fn}`);
     if (fn && (fn as any).$inject) return (fn as any).$inject;

src/vanilla/$q.ts

@@ -1,11 +1,29 @@
+/** @internalapi @module vanilla */ /** */
 import { isArray, isObject, $QLike } from "../common/module";
 
-/** $q-like promise api */
+/**
+ * An angular1-like promise api
+ *
+ * This object implements four methods similar to the
+ * [angular 1 promise api](https://docs.angularjs.org/api/ng/service/$q)
+ *
+ * UI-Router evolved from an angular 1 library to a framework agnostic library.
+ * However, some of the `ui-router-core` code uses these ng1 style APIs to support ng1 style dependency injection.
+ *
+ * This API provides native ES6 promise support wrapped as a $q-like API.
+ * Internally, UI-Router uses this $q object to perform promise operations.
+ * The `angular-ui-router` (ui-router for angular 1) uses the $q API provided by angular.
+ *
+ * $q-like promise api
+ */
 export const $q = {
+  /** Normalizes a value as a promise */
   when: (val) => new Promise((resolve, reject) => resolve(val)),
 
+  /** Normalizes a value as a promise rejection */
   reject: (val) => new Promise((resolve, reject) => { reject(val); }),
 
+  /** @returns a deferred object, which has `resolve` and `reject` functions */
   defer: () => {
     let deferred: any = {};
     deferred.promise = new Promise((resolve, reject) => {
@@ -15,6 +33,7 @@ export const $q = {
     return deferred;
   },
 
+  /** Like Promise.all(), but also supports object key/promise notation like $q */
   all: (promises: { [key: string]: Promise<any> } | Promise<any>[]) => {
     if (isArray(promises)) {
       return new Promise((resolve, reject) => {

src/vanilla/hashLocation.ts

@@ -1,3 +1,4 @@
+/** @internalapi @module vanilla */ /** */
 import { isDefined } from '../common/module';
 import { LocationConfig, LocationServices } from '../common/coreservices';
 import { splitHash, splitQuery, trimHashVal, getParams, locationPluginFactory } from './utils';
@@ -7,6 +8,7 @@ import { LocationPlugin } from "./interface";
 let hashPrefix: string = '';
 let baseHref: string = '';
 
+/** A `LocationConfig` that delegates to the browser's `location` object */
 export const hashLocationConfig: LocationConfig = {
   port: () =>
     parseInt(location.port),
@@ -26,6 +28,7 @@ export const hashLocationConfig: LocationConfig = {
   }
 };
 
+/** A `LocationServices` that uses the browser hash "#" to get/set the current location */
 export const hashLocationService: LocationServices = {
   hash: () =>
       splitHash(trimHashVal(location.hash))[1],
@@ -42,5 +45,6 @@ export const hashLocationService: LocationServices = {
   }
 };
 
+/** A `UIRouterPlugin` uses the browser hash to get/set the current location */
 export const hashLocationPlugin: (router: UIRouter) => LocationPlugin =
     locationPluginFactory('vanilla.hashBangLocation', hashLocationService, hashLocationConfig);

src/vanilla/interface.ts

@@ -1,3 +1,4 @@
+/** @internalapi @module vanilla */ /** */
 import { LocationConfig, LocationServices } from '../common/coreservices';
 import { UIRouterPlugin } from "../interface";
 import { $InjectorLike, $QLike } from "../common/module";

src/vanilla/memoryLocation.ts

@@ -1,3 +1,4 @@
+/** @internalapi @module vanilla */ /** */
 import { services, isDefined } from '../common/module';
 import { LocationConfig, LocationServices } from '../common/coreservices';
 import { splitQuery, trimHashVal, getParams, splitHash, locationPluginFactory } from './utils';
@@ -7,6 +8,7 @@ import { LocationPlugin } from "./interface";
 import { isArray } from "../common/predicates";
 
 var mlc;
+/** A `LocationConfig` mock that gets/sets all config from an in-memory object */
 export const memoryLocationConfig: LocationConfig = mlc = {
   _hashPrefix: '',
   _baseHref: '',
@@ -28,6 +30,7 @@ export const memoryLocationConfig: LocationConfig = mlc = {
 };
 
 var mls;
+/** A `LocationServices` that gets/sets the current location from an in-memory object */
 export const memoryLocationService: LocationServices = mls = {
   _listeners: [],
   _url: {
@@ -71,5 +74,6 @@ export const memoryLocationService: LocationServices = mls = {
   onChange: (cb: EventListener) => (mls._listeners.push(cb), () => removeFrom(mls._listeners, cb))
 };
 
+/** A `UIRouterPlugin` that gets/sets the current location from an in-memory object */
 export const memoryLocationPlugin: (router: UIRouter) => LocationPlugin =
     locationPluginFactory("vanilla.memoryLocation", memoryLocationService, memoryLocationConfig);

src/vanilla/pushStateLocation.ts

@@ -1,3 +1,4 @@
+/** @internalapi @module vanilla */ /** */
 import { services, isDefined } from '../common/module';
 import { LocationConfig, LocationServices } from '../common/coreservices';
 import { splitQuery, trimHashVal, getParams, locationPluginFactory } from './utils';
@@ -7,6 +8,8 @@ import { UIRouter } from "../router";
 let hashPrefix: string = '';
 let baseHref: string = '';
 
+/** A `LocationConfig` mock that gets/sets all config from the location
+ * TODO: Merge with LocationConfig impl in hasLocation.ts */
 export const pushStateLocationConfig: LocationConfig = {
   port: () =>
       parseInt(location.port),
@@ -26,6 +29,11 @@ export const pushStateLocationConfig: LocationConfig = {
   }
 };
 
+/**
+ * A `LocationServices` that gets/sets the current location using the browser's `location` and `history` apis
+ *
+ * Uses `history.pushState` and `history.replaceState`
+ */
 export const pushStateLocationService: LocationServices = {
   hash: () =>
       trimHashVal(location.hash),
@@ -50,6 +58,7 @@ export const pushStateLocationService: LocationServices = {
   }
 };
 
+/** A `UIRouterPlugin` that gets/sets the current location using the browser's `location` and `history` apis */
 export const pushStateLocationPlugin: (router: UIRouter) => LocationPlugin =
     locationPluginFactory("vanilla.pushStateLocation", pushStateLocationService, pushStateLocationConfig);
 

src/vanilla/utils.ts

@@ -1,3 +1,4 @@
+/** @internalapi @module vanilla */ /** */
 import {isArray} from "../common/module";
 import { LocationServices, LocationConfig, services } from "../common/coreservices";
 import { UIRouter } from "../router";