docs(*): Update docs fixing broken [[foo]] refs and improving subsystem headings

Author: christopherthielen

src/common/trace.ts

@@ -1,5 +1,5 @@
 /**
- * UI-Router Transition Tracing
+ * # Transition tracing (debug)
  *
  * Enable transition tracing to print transition information to the console,
  * in order to help debug your application.

src/globals.ts

@@ -11,7 +11,7 @@ import {TransitionService} from "./transition/transitionService";
 import {copy} from "./common/common";
 
 /**
- * Global mutable state
+ * Global router state
  *
  * This is where we hold the global mutable state such as current state, current
  * params, current transition, etc.
@@ -43,17 +43,30 @@ export interface UIRouterGlobals {
 
 
 /**
- * Global mutable state
+ * Global router state
+ *
+ * This is where we hold the global mutable state such as current state, current
+ * params, current transition, etc.
  */
 export class Globals implements UIRouterGlobals {
+  /** @inheritdoc */
   params: StateParams = new StateParams();
+  /** @inheritdoc */
   current: StateDeclaration;
+  /** @inheritdoc */
   $current: State;
+  /** @inheritdoc */
   transition: Transition;
+
+  /** @internalapi */
   transitionHistory = new Queue<Transition>([], 1);
+
+  /** @internalapi */
   successfulTransitions = new Queue<Transition>([], 1);
 
+  /** @hidden */
   constructor(transitionService: TransitionService) {
+    // TODO: This probably belongs in a hooks/globals.ts
     const beforeNewTransition = ($transition$: Transition) => {
 
       this.transition = $transition$;

src/interface.ts

@@ -1,5 +1,5 @@
 /**
- * Core classes and interfaces
+ * # Core classes and interfaces
  *
  * The classes and interfaces that are core to ui-router and do not belong
  * to a more specific subsystem (such as resolve).
@@ -16,16 +16,23 @@ import {UIRouter} from "./router";
 /**
  * An interface for getting values from dependency injection.
  *
- * This injector primarily returns resolve values (using a [[ResolveContext]]) that match the given token.
+ * This is primarily used to get resolve values for a given token.
+ * An instance of the `UIInjector` can be retrieved from the current transition using [[Transition.injector]].
+ *
+ * ---
+ *
  * If no resolve is found for a token, then it will delegate to the native injector.
- * The native injector may be Angular 1 `$injector`, Angular 2 `Injector`, or a naive polyfill.
+ * The native injector may be Angular 1 `$injector`, Angular 2 `Injector`, or a simple polyfill.
  *
  * In Angular 2, the native injector might be the root Injector,
  * or it might be a lazy loaded `NgModule` injector scoped to a lazy load state tree.
  */
 export interface UIInjector {
   /**
-   * Gets a value from the injector
+   * Gets a value from the injector.
+   *
+   * For a given token, returns the value from the injector that matches the token.
+   * If the token is for a resolve that has not yet been fetched, this throws an error.
    *
    * #### Example:
    * ```js
@@ -34,7 +41,7 @@ export interface UIInjector {
    *
    * #### ng1 Example:
    * ```js
-   * // Fetch $state service
+   * // Fetch StateService
    * injector.get('$state').go('home');
    * ```
    *
@@ -50,26 +57,23 @@ export interface UIInjector {
    * var stringArray = injector.get<string[]>('myStringArray');
    * ```
    *
-   * ---
-   *
    * ### `NOWAIT` policy
    *
    * When using [[ResolvePolicy.async]] === `NOWAIT`, the value returned from `get()` is a promise for the result.
+   * The promise is not automatically unwrapped.
    *
-   * @param token the key for the value to get.  May be a string or arbitrary object.
+   * @param token the key for the value to get.  May be a string, a class, or any arbitrary object.
    * @return the Dependency Injection value that matches the token
    */
   get(token: any): any;
+  /** Gets a value as type `T` (generics parameter) */
   get<T>(token: any): T;
 
   /**
    * Asynchronously gets a value from the injector
    *
-   * If the [[ResolveContext]] has a [[Resolvable]] matching the token, it will be
-   * asynchronously resolved.
-   *
-   * Returns a promise for a value from the injector.
-   * Returns resolve values and/or values from the native injector (ng1/ng2).
+   * For a given token, returns a promise for the value from the injector that matches the token.
+   * If the token is for a resolve that has not yet been fetched, this triggers the resolve to load.
    *
    * #### Example:
    * ```js
@@ -82,6 +86,7 @@ export interface UIInjector {
    * @return a Promise for the Dependency Injection value that matches the token
    */
   getAsync(token: any): Promise<any>;
+  /** Asynchronously gets a value as type `T` (generics parameter) */
   getAsync<T>(token: any): Promise<T>;
 
   /**
@@ -101,15 +106,19 @@ export interface UIInjector {
   getNative<T>(token: any): T;
 }
 
+/** @internalapi */
 export interface UIRouterPlugin extends Disposable {
   name: string;
 }
 
-export abstract class UIRouterPluginBase implements UIRouterPlugin {
+/** @internalapi */
+export abstract class UIRouterPluginBase implements UIRouterPlugin, Disposable {
   abstract name: string;
   dispose(router: UIRouter) { }
 }
 
+/** @internalapi */
 export interface Disposable {
+  /** Instructs the Disposable to clean up any resources */
   dispose(router?: UIRouter);
 }

src/resolve/interface.ts

@@ -1,5 +1,5 @@
 /**
- * The Resolve subsystem
+ * # The Resolve subsystem
  *
  * This subsystem is an asynchronous, hierarchical Dependency Injection system.
  *

src/router.ts

@@ -21,34 +21,53 @@ let _routerInstance = 0;
 /**
  * The master class used to instantiate an instance of UI-Router.
  *
- * UI-Router (for a specific framework) will create an instance of this class during bootstrap.
+ * UI-Router (for each specific framework) will create an instance of this class during bootstrap.
  * This class instantiates and wires the UI-Router services together.
  *
  * After a new instance of the UIRouter class is created, it should be configured for your app.
- * For instance, app states should be registered with the [[stateRegistry]].
+ * For instance, app states should be registered with the [[UIRouter.stateRegistry]].
  *
- * Tell UI-Router to monitor the URL by calling `uiRouter.urlRouter.listen()` ([[UrlRouter.listen]])
+ * ---
+ *
+ * Normally the framework code will bootstrap UI-Router.
+ * If you are bootstrapping UIRouter manually, tell it to monitor the URL by calling
+ * [[UrlService.listen]] then [[UrlService.sync]].
  */
 export class UIRouter {
   /** @hidden */
   $id: number = _routerInstance++;
 
+  /** Provides services related to ui-view synchronization */
   viewService = new ViewService();
 
+  /** Provides services related to Transitions */
   transitionService: TransitionService = new TransitionService(this);
 
+  /** Global router state */
   globals: UIRouterGlobals = new Globals(this.transitionService);
 
+  /**
+   * Deprecated for public use. Use [[urlService]] instead.
+   * @deprecated
+   */
   urlMatcherFactory: UrlMatcherFactory = new UrlMatcherFactory();
 
+  /**
+   * Deprecated for public use. Use [[urlService]] instead.
+   * @deprecated
+   */
   urlRouter: UrlRouter = new UrlRouter(this);
 
+  /** Provides a registry for states, and related registration services */
   stateRegistry: StateRegistry = new StateRegistry(this);
 
+  /** Provides services related to states */
   stateService = new StateService(this);
 
+  /** Provides services related to the URL */
   urlService: UrlService = new UrlService(this);
 
+  /** @hidden */
   private _disposables: Disposable[] = [];
 
   /** Registers an object to be notified when the router is disposed */
@@ -80,6 +99,13 @@ export class UIRouter {
     });
   }
 
+  /**
+   * Creates a new `UIRouter` object
+   *
+   * @param locationService a [[LocationServices]] implementation
+   * @param locationConfig a [[LocationConfig]] implementation
+   * @internalapi
+   */
   constructor(
       public locationService: LocationServices = UrlService.locationServiceStub,
       public locationConfig: LocationConfig = UrlService.locationConfigStub
@@ -99,6 +125,12 @@ export class UIRouter {
   /** @hidden */
   private _plugins: { [key: string]: UIRouterPlugin } = {};
 
+  /** Add plugin (as ES6 class) */
+  plugin<T extends UIRouterPlugin>(plugin: { new(router: UIRouter, options?: any): T }, options?: any): T;
+  /** Add plugin (as javascript constructor function) */
+  plugin<T extends UIRouterPlugin>(plugin: { (router: UIRouter, options?: any): void }, options?: any): T;
+  /** Add plugin (as javascript factory function) */
+  plugin<T extends UIRouterPlugin>(plugin: PluginFactory<T>, options?: any): T;
   /**
    * Adds a plugin to UI-Router
    *
@@ -152,12 +184,6 @@ export class UIRouter {
    * @param options options to pass to the plugin class/factory
    * @returns the registered plugin instance
    */
-  plugin<T extends UIRouterPlugin>(plugin: { new(router: UIRouter, options?: any): T }, options?: any): T;
-  /** Allow javascript constructor function */
-  plugin<T extends UIRouterPlugin>(plugin: { (router: UIRouter, options?: any): void }, options?: any): T;
-  /** Allow javascript factory function */
-  plugin<T extends UIRouterPlugin>(plugin: PluginFactory<T>, options?: any): T;
-  /** Allow javascript factory function */
   plugin<T extends UIRouterPlugin>(plugin: any, options: any = {}): T {
     let pluginInstance = new plugin(this, options);
     if (!pluginInstance.name) throw new Error("Required property `name` missing on plugin: " + pluginInstance);
@@ -181,4 +207,5 @@ export class UIRouter {
   }
 }
 
+/** @internalapi */
 export type PluginFactory<T> = (router: UIRouter, options?: any) => T;

src/state/index.ts

@@ -1,5 +1,5 @@
 /**
- * The state subsystem
+ * # The state subsystem
  *
  * This subsystem implements the ui-router state tree
  *

src/state/interface.ts

@@ -27,10 +27,10 @@ export interface TargetStateDef {
 
 export type ResolveTypes = Resolvable | ResolvableLiteral | ProviderLike;
 /**
- * Base interface for [[Ng1ViewDeclaration]] and [[Ng2ViewDeclaration]]
+ * Base interface for declaring a view
  *
  * This interface defines the basic data that a normalized view declaration will have on it.
- * Framework-specific implementations may add additional fields (to their interfaces which extend this interface).
+ * Framework-specific implementations should add additional fields (to their interfaces which extend this interface).
  *
  * @internalapi
  */
@@ -107,22 +107,21 @@ export type RedirectToResult = string | TargetState | { state?: string, params?:
  */
 export interface StateDeclaration {
   /**
-   * The state name
+   * The state name (required)
    *
    * A unique state name, e.g. `"home"`, `"about"`, `"contacts"`.
    * To create a parent/child state use a dot, e.g. `"about.sales"`, `"home.newest"`.
    *
-   *
-   * Note: States require unique names.  If you omit this property, you must provide
-   * the state name when you register it with the [[$stateProvider]].
+   * Note: [State] objects require unique names.
+   * The name is used like an id.
    */
   name?: string;
 
   /**
-   * abstract state indicator
+   * Abstract state indicator
    *
-   * An abstract state can never be directly activated.  Use an abstract state to provide inherited
-   * properties (url, resolve, data, etc) to children states.
+   * An abstract state can never be directly activated.
+   * Use an abstract state to provide inherited properties (url, resolve, data, etc) to children states.
    */
   abstract?: boolean;
 
@@ -131,8 +130,9 @@ export interface StateDeclaration {
    *
    * Normally, a state's parent is implied from the state's [[name]], e.g., `"parentstate.childstate"`.
    *
-   * Alternatively, you can explicitly set the parent state using this property.  This allows shorter state
-   * names, e.g., `<a ui-sref="childstate">Child</a>` instead of `<a ui-sref="parentstate.childstate">Child</a>
+   * Alternatively, you can explicitly set the parent state using this property.
+   * This allows shorter state names, e.g., `<a ui-sref="childstate">Child</a>`
+   * instead of `<a ui-sref="parentstate.childstate">Child</a>
    *
    * When using this property, the state's name should not have any dots in it.
    *
@@ -152,7 +152,7 @@ export interface StateDeclaration {
   parent?: (string|StateDeclaration);
 
   /**
-   * Gets the internal API
+   * Gets the internal State object API
    *
    * Gets the *internal API* for a registered state.
    *
@@ -408,7 +408,7 @@ export interface StateDeclaration {
    * - If the property is a function:
    *   - The function is called with two parameters:
    *     - The current [[Transition]]
-   *     - An injector which can be used to get dependencies using [[UIRInjector.get]]
+   *     - An [[UIInjector]] which can be used to get dependencies using [[UIInjector.get]] or resolves using [[UIInjector.getAsync]]
    *   - The return value is processed using the previously mentioned rules.
    *   - If the return value is a promise, the promise is waited for, then the resolved async value is processed using the same rules.
    *