docs(ng2): Mark internal docs as @internalapi to reduce clutter

Author: christopherthielen

src/ng2.ts

@@ -1,9 +1,4 @@
-/**
- * Main entry point for angular 2.x build
- * @module ng2
- */
-/** for typedoc */
-
+/** @module ng2 */ /** for typedoc */
 export * from "ui-router-core";
 import "ui-router-core/lib/justjs";
 

src/ng2/directives/directives.ts

@@ -5,7 +5,7 @@
  * - [[UISref]]: A state ref to a target state; navigates when clicked
  * - [[UISrefActive]]: (and `UISrefActiveEq`) Adds a css class when a UISref's target state (or a child state) is active
  *
- * @preferred @module ng2_directives
+ * @preferred @module directives
  */ /** */
 import {UISref, AnchorUISref} from "./uiSref";
 import {UISrefActive} from "./uiSrefActive";
@@ -17,10 +17,12 @@ export * from "./uiSref";
 export * from "./uiSrefStatus";
 export * from "./uiSrefActive";
 
+/** @internalapi */
 export const _UIROUTER_DIRECTIVES = [UISref, AnchorUISref, UIView, UISrefActive, UISrefStatus];
 
 /**
  * References to the UI-Router directive classes, for use within a @Component's `directives:` property
  * @deprecated use [[UIRouterModule]]
+ * @internalapi
  */
 export const UIROUTER_DIRECTIVES = _UIROUTER_DIRECTIVES;

src/ng2/directives/uiSref.ts

@@ -1,4 +1,4 @@
-/** @module ng2_directives */ /** */
+/** @module directives */ /** */
 import {UIRouter, UIRouterGlobals} from "ui-router-core";
 import {Directive, Inject, Input} from "@angular/core";
 import {Optional} from "@angular/core";
@@ -12,7 +12,10 @@ import {Subscription, ReplaySubject} from "rxjs/Rx";
 import {TargetState} from "ui-router-core";
 import "../rx";
 
-/** @hidden */
+/**
+ * @internalapi
+ * # blah blah blah
+ */
 @Directive({ selector: 'a[uiSref]' })
 export class AnchorUISref {
   constructor(public _el: ElementRef, public _renderer: Renderer) { }
@@ -67,26 +70,58 @@ export class AnchorUISref {
   host: { '(click)': 'go()' }
 })
 export class UISref {
+  /**
+   * `@Input('uiSref')` The name of the state to link to
+   *
+   * ```html
+   * <a uiSref="hoome">Home</a>
+   * ```
+   */
   @Input('uiSref') state: string;
+
+  /**
+   * `@Input('uiParams')` The parameter values to use (as key/values)
+   *
+   * ```html
+   * <a uiSref="book" [uiParams]="{ bookId: book.id }">Book {{ book.name }}</a>
+   * ```
+   */
   @Input('uiParams') params: any;
-  @Input('uiOptions') options: any;
 
+  /**
+   * `@Input('uiOptions')` The transition options
+   *
+   * ```html
+   * <a uiSref="books" [uiOptions]="{ reload: true }">Book {{ book.name }}</a>
+   * ```
+   */
+  @Input('uiOptions') options: TransitionOptions;
+
+  /**
+   * An observable (ReplaySubject) of the state this UISref is targeting.
+   * When the UISref is clicked, it will transition to this [[TargetState]].
+   */
   public targetState$ = new ReplaySubject<TargetState>(1);
-  private _emit: boolean = false;
 
+  /** @internalapi */
+  private _emit: boolean = false;
+  /** @internalapi */
   private _statesSub: Subscription;
 
   constructor(
-      private _router: UIRouter,
-      @Inject(UIView.PARENT_INJECT) public parent: ParentUIViewInject,
-      @Optional() private _anchorUISref: AnchorUISref,
+      /** @internalapi */ private _router: UIRouter,
+      /** @internalapi */ @Inject(UIView.PARENT_INJECT) public parent: ParentUIViewInject,
+      /** @internalapi */ @Optional() private _anchorUISref: AnchorUISref,
       @Inject(Globals) _globals: UIRouterGlobals
   ) {
     this._statesSub = _globals.states$.subscribe(() => this.update())
   }
 
+  /** @internalapi */
   set "uiSref"(val: string) { this.state = val; this.update(); }
+  /** @internalapi */
   set "uiParams"(val: Obj) { this.params = val; this.update(); }
+  /** @internalapi */
   set "uiOptions"(val: TransitionOptions) { this.options = val; this.update(); }
 
   ngOnInit() {
@@ -122,6 +157,7 @@ export class UISref {
     return extend(defaultOpts, this.options || {});
   }
 
+  /** When triggered by a (click) event, this function transitions to the UISref's target state */
   go() {
     this._router.stateService.go(this.state, this.params, this.getOptions());
     return false;

src/ng2/directives/uiSrefActive.ts

@@ -1,4 +1,4 @@
-/** @module ng2_directives */ /** */
+/** @module directives */ /** */
 import {Directive, Input, ElementRef, Host, Renderer} from "@angular/core";
 import {UISrefStatus, SrefStatus} from "./uiSrefStatus";
 import {Subscription} from "rxjs/Rx";
@@ -80,10 +80,6 @@ import {Subscription} from "rxjs/Rx";
  *   </li>
  * </ul>
  * ```
- *
- * ---
- *
- * As
  */
 @Directive({
   selector: '[uiSrefActive],[uiSrefActiveEq]'

src/ng2/directives/uiSrefStatus.ts

@@ -1,4 +1,4 @@
-/** @module ng2_directives */ /** */
+/** @module directives */ /** */
 import {Directive, Output, EventEmitter, ContentChildren, QueryList, Inject} from "@angular/core";
 import {UISref} from "./uiSref";
 import {PathNode} from "ui-router-core";
@@ -11,10 +11,11 @@ import {Param} from "ui-router-core";
 import {PathFactory} from "ui-router-core";
 import {Subscription, Observable, BehaviorSubject} from "rxjs/Rx";
 
+/** @internalapi */
 interface TransEvt { evt: string, trans: Transition }
 
 /**
- * uiSref status booleans 
+ * UISref status emitted from [[UISrefStatus]]
  */
 export interface SrefStatus {
   /** The sref's target state (or one of its children) is currently active */
@@ -27,6 +28,7 @@ export interface SrefStatus {
   exiting: boolean;
 }
 
+/** @internalapi */
 const inactiveStatus: SrefStatus = {
   active: false,
   exact: false,
@@ -39,6 +41,8 @@ const inactiveStatus: SrefStatus = {
  *
  * The predicate returns true when the target state (and param values)
  * match the (tail of) the path, and the path's param values
+ *
+ * @internalapi
  */
 const pathMatches = (target: TargetState): Predicate<PathNode[]> => {
   if (!target.exists()) return () => false;
@@ -61,6 +65,8 @@ const pathMatches = (target: TargetState): Predicate<PathNode[]> => {
  * Given basePath: [a, b], appendPath: [c, d]),
  * Expands the path to [c], [c, d]
  * Then appends each to [a,b,] and returns: [a, b, c], [a, b, c, d]
+ *
+ * @internalapi
  */
 function spreadToSubPaths(basePath: PathNode[], appendPath: PathNode[]): PathNode[][] {
   return appendPath.map(node => basePath.concat(PathFactory.subPath(appendPath, n => n.state === node.state)));
@@ -71,6 +77,8 @@ function spreadToSubPaths(basePath: PathNode[], appendPath: PathNode[]): PathNod
  * and a UISref Target State, return a SrefStatus object
  * which represents the current status of that Sref: 
  * active, activeEq (exact match), entering, exiting
+ *
+ * @internalapi
  */
 function getSrefStatus(event: TransEvt, srefTarget: TargetState): SrefStatus {
   const pathMatchesTarget = pathMatches(srefTarget);
@@ -106,6 +114,7 @@ function getSrefStatus(event: TransEvt, srefTarget: TargetState): SrefStatus {
   } as SrefStatus;
 }
 
+/** @internalapi */
 function mergeSrefStatus(left: SrefStatus, right: SrefStatus) {
   return {
     active:   left.active   || right.active,
@@ -118,11 +127,17 @@ function mergeSrefStatus(left: SrefStatus, right: SrefStatus) {
 /**
  * A directive which emits events when a paired [[UISref]] status changes.
  *
- * This directive is primarily used by the [[UISrefActive]]/[[UISrefActiveEq]] directives to monitor `UISref`(s).
- * This directive shares the same attribute selectors as `UISrefActive/Eq`, so it is created whenever a `UISrefActive/Eq` is created.
+ * This directive is primarily used by the [[UISrefActive]] directives to monitor `UISref`(s).
+ *
+ * This directive shares two attribute selectors with `UISrefActive`:
+ *
+ * - `[uiSrefActive]`
+ * - `[uiSrefActiveEq]`.
+ *
+ * Thus, whenever a `UISrefActive` directive is created, a `UISrefStatus` directive is also created.
  *
- * Most apps should simply use [[UISrefActive]], but some advanced components may want to process the
- * `uiSrefStatus` events directly.
+ * Most apps should simply use `UISrefActive`, but some advanced components may want to process the
+ * [[SrefStatus]] events directly.
  *
  * ```js
  * <li (uiSrefStatus)="onSrefStatusChanged($event)">

src/ng2/directives/uiView.ts

@@ -1,4 +1,4 @@
-/** @module ng2_directives */ /** */
+/** @module directives */ /** */
 import {
     Component, ComponentFactoryResolver, ViewContainerRef, Input, ComponentRef, Type,
     ReflectiveInjector, ViewChild, Injector, Inject
@@ -16,18 +16,26 @@ import {MergeInjector} from "../mergeInjector";
 /** @hidden */
 let id = 0;
 
-// These are provide()d as the string UIView.PARENT_INJECT
+/** @internalapi These are provide()d as the string UIView.PARENT_INJECT */
 export interface ParentUIViewInject {
   context: ViewContext;
   fqn: string;
 }
 
+/** @internalapi */
 interface InputMapping {
   token: string;
   prop: string;
 }
 
-/** @hidden */
+/**
+ * Given a component class, gets the inputs of styles:
+ *
+ * - @Input('foo') _foo
+ * - `inputs: ['foo']`
+ *
+ * @internalapi
+ */
 const ng2ComponentInputs = (ng2CompClass: Type<any>) => {
   /** Get "@Input('foo') _foo" inputs */
   let props = reflector.propMetadata(ng2CompClass);
@@ -66,9 +74,8 @@ const ng2ComponentInputs = (ng2CompClass: Type<any>) => {
  * is filled in by a view (as defined by a [[Ng2ViewDeclaration]] inside a [[Ng2StateDeclaration]]) when the view's
  * state has been activated.
  *
- * @example
+ * #### Example:
  * ```js
- *
  * // This app has two states, 'foo' and 'bar'
  * stateRegistry.register({ name: 'foo', url: '/foo', component: FooComponent });
  * stateRegistry.register({ name: 'bar', url: '/bar', component: BarComponent });
@@ -85,9 +92,8 @@ const ng2ComponentInputs = (ng2CompClass: Type<any>) => {
  * an unnamed `ui-view` is internally named `$default`*.   When a `ui-view` has a name, it will be filled in
  * by a matching named view.
  *
- * @example
+ * #### Example:
  * ```js
- *
  * stateRegistry.register({
  *   name: 'foo',
  *   url: '/foo',

src/ng2/interface.ts

@@ -1,4 +1,4 @@
-/** @module ng2 */ /** */
+/** @module state */ /** */
 import {StateDeclaration, _ViewDeclaration} from "ui-router-core";
 import {Transition} from "ui-router-core";
 import {Type, OpaqueToken} from "@angular/core";
@@ -8,9 +8,8 @@ import {HookResult} from "ui-router-core";
  * The StateDeclaration object is used to define a state or nested state.
  * It should be registered with the [[StateRegistry]].
  *
- * @example
+ * #### Example:
  * ```js
- *
  * import {FoldersComponent} from "./folders";
  *
  * // StateDeclaration object
@@ -44,19 +43,17 @@ export interface Ng2StateDeclaration extends StateDeclaration, Ng2ViewDeclaratio
    *
    *  Targets three named ui-views in the parent state's template
    *
-   * @example
+   * #### Example:
    * ```js
-   *
    * views: {
    *   header: {component: HeaderComponent},
    *   body: {component: BodyComponent},
    *   footer: {component: FooterComponent}
    * }
    * ```
    *
-   * @example
+   * #### Example:
    * ```js
-   *
    * // Targets named ui-view="header" in the template of the ancestor state 'top'
    * // and the named `ui-view="body" from the parent state's template.
    * views: {
@@ -74,9 +71,8 @@ export interface Ng2StateDeclaration extends StateDeclaration, Ng2ViewDeclaratio
    *
    * Addresses without an `@` are anchored to the parent state.
    *
-   * @example
+   * #### Example:
    * ```js
-   *
    * // target the `<div ui-view='foo'></div>` created in the parent state's view
    * views: { foo: {...} }
    * ```
@@ -99,9 +95,8 @@ export interface Ng2StateDeclaration extends StateDeclaration, Ng2ViewDeclaratio
    * You can address a `ui-view` absolutely, using dotted notation, by prefixing the address with a `!`.  Dotted
    * addresses map to the hierarchy of `ui-view`s active in the DOM:
    *
-   * @example
+   * #### Example:
    * ```js
-   *
    * // absolutely target the `<div ui-view='nested'></div>`... which was created
    * // in the unnamed/$default root `<ui-view></ui-view>`
    * views: { '!$default.nested': {...} }
@@ -112,18 +107,16 @@ export interface Ng2StateDeclaration extends StateDeclaration, Ng2ViewDeclaratio
    * Absolute addressing is actually relative addressing, only anchored to the unnamed root state.  You can also use
    * relative addressing anchored to any state, in order to target a target deeply nested `ui-views`:
    *
-   * @example
+   * #### Example:
    * ```js
    *
-   *
    * // target the `<div ui-view='bar'></div>`... which was created inside the
    * // `<div ui-view='bar'></div>`... which was created inside the parent state's template.
    * views: { 'foo.bar': {...} }
    * ```
    *
-   * @example
+   * #### Example:
    * ```js
-   *
    * // target the `<div ui-view='bar'></div>`...  which was created in
    * // `<div ui-view='foo'></div>`... which was created in a template crom the state `baz.qux`
    * views: { 'foo.bar@baz.qux': {...} }
@@ -147,9 +140,8 @@ export interface Ng2ViewDeclaration extends _ViewDeclaration {
    *
    * ### The component class which will be used for this view.
    *
-   * @example
+   * #### Example:
    * ```js
-   *
    * .state('profile', {
    *   // Use the <my-profile></my-profile> component for the Unnamed view
    *   component: MyProfileComponent,
@@ -239,9 +231,8 @@ export interface Ng2ViewDeclaration extends _ViewDeclaration {
    * Any component bindings that are omitted from this map get the default behavior of mapping to a resolve of the
    * same name.
    *
-   * @example
+   * #### Example:
    * ```js
-   *
    * $stateProvider.state('foo', {
    *   resolve: {
    *     foo: function(FooService) { return FooService.get(); },