docs(*): Document a lot more symbols that are missing comments in our generated docs.

modules/angular2/src/core/change_detection/change_detection_util.ts

@@ -54,10 +54,15 @@ var _wrappedValues = [
 
 var _wrappedIndex = 0;
 
-
+/**
+ * Represents a basic change from a previous to a new value.
+ */
 export class SimpleChange {
   constructor(public previousValue: any, public currentValue: any) {}
 
+  /**
+   * Check whether the new value is the first value assigned.
+   */
   isFirstChange(): boolean { return this.previousValue === ChangeDetectionUtil.uninitialized; }
 }
 

modules/angular2/src/core/change_detection/change_detector_ref.ts

@@ -122,7 +122,7 @@ export abstract class ChangeDetectorRef {
    * check
    * every five seconds.
    *
-   * See {@link detach} for more information.
+   * See {@link ChangeDetectorRef#detach} for more information.
    */
   abstract detectChanges(): void;
 

modules/angular2/src/core/change_detection/constants.ts

@@ -1,5 +1,8 @@
 import {StringWrapper, normalizeBool, isBlank} from 'angular2/src/facade/lang';
 
+/**
+ * Describes the current state of the change detector.
+ */
 export enum ChangeDetectorState {
   /**
    * `NeverChecked` means that the change detector has not been checked yet, and
@@ -21,6 +24,10 @@ export enum ChangeDetectorState {
   Errored
 }
 
+/**
+ * Describes within the change detector which strategy will be used the next time change
+ * detection is triggered.
+ */
 export enum ChangeDetectionStrategy {
   /**
    * `CheckedOnce` means that after calling detectChanges the mode of the change detector
@@ -62,6 +69,9 @@ export enum ChangeDetectionStrategy {
   OnPushObserve
 }
 
+/**
+ * List of possible {@link ChangeDetectionStrategy} values.
+ */
 export var CHANGE_DETECTION_STRATEGY_VALUES = [
   ChangeDetectionStrategy.CheckOnce,
   ChangeDetectionStrategy.Checked,
@@ -72,6 +82,9 @@ export var CHANGE_DETECTION_STRATEGY_VALUES = [
   ChangeDetectionStrategy.OnPushObserve
 ];
 
+/**
+ * List of possible {@link ChangeDetectorState} values.
+ */
 export var CHANGE_DETECTOR_STATE_VALUES = [
   ChangeDetectorState.NeverChecked,
   ChangeDetectorState.CheckedBefore,

modules/angular2/src/core/change_detection/differs/iterable_differs.ts

@@ -4,6 +4,10 @@ import {ListWrapper} from 'angular2/src/facade/collection';
 import {ChangeDetectorRef} from '../change_detector_ref';
 import {Provider, SkipSelfMetadata, OptionalMetadata, Injectable} from 'angular2/src/core/di';
 
+/**
+ * A strategy for tracking changes over time to an iterable. Used for {@link NgFor} to
+ * respond to changes in an iterable by effecting equivalent changes in the DOM.
+ */
 export interface IterableDiffer {
   diff(object: Object): any;
   onDestroy();

modules/angular2/src/core/change_detection/differs/keyvalue_differs.ts

@@ -4,6 +4,9 @@ import {ListWrapper} from 'angular2/src/facade/collection';
 import {ChangeDetectorRef} from '../change_detector_ref';
 import {Provider, SkipSelfMetadata, OptionalMetadata, Injectable} from 'angular2/src/core/di';
 
+/**
+ * A differ that tracks changes made to an object over time.
+ */
 export interface KeyValueDiffer {
   diff(object: Object);
   onDestroy();

modules/angular2/src/core/debug/debug_element.ts

@@ -11,16 +11,28 @@ import {ElementRef, ElementRef_} from 'angular2/src/core/linker/element_ref';
  * element and provides access to the corresponding ElementInjector and
  * underlying DOM Element, as well as a way to query for children.
  *
- * A DebugElement can be obtained from a {@link ComponentFixture} or
- * {@link RootTestComponent}.
+ * A DebugElement can be obtained from a {@link ComponentFixture} or from an
+ * {@link ElementRef} via {@link inspectElement}.
  */
 export abstract class DebugElement {
+  /**
+   * Return the instance of the component associated with this element, if any.
+   */
   get componentInstance(): any { return unimplemented(); };
 
+  /**
+   * Return the native HTML element for this DebugElement.
+   */
   get nativeElement(): any { return unimplemented(); };
 
+  /**
+   * Return an Angular {@link ElementRef} for this element.
+   */
   get elementRef(): ElementRef { return unimplemented(); };
 
+  /**
+   * Get the directive active for this element with the given index, if any.
+   */
   abstract getDirectiveInstance(directiveIndex: number): any;
 
   /**
@@ -38,12 +50,26 @@ export abstract class DebugElement {
    */
   get componentViewChildren(): DebugElement[] { return unimplemented(); };
 
+  /**
+   * Simulate an event from this element as if the user had caused
+   * this event to fire from the page.
+   */
   abstract triggerEventHandler(eventName: string, eventObj: Event): void;
 
+  /**
+   * Check whether the element has a directive with the given type.
+   */
   abstract hasDirective(type: Type): boolean;
 
+  /**
+   * Inject the given type from the element injector.
+   */
   abstract inject(type: Type): any;
 
+
+  /**
+   * Read a local variable from the element (e.g. one defined with `#variable`).
+   */
   abstract getLocal(name: string): any;
 
   /**
@@ -169,11 +195,25 @@ export function inspectElement(elementRef: ElementRef): DebugElement {
                            (<ElementRef_>elementRef).boundElementIndex);
 }
 
+/**
+ * Maps an array of {@link DebugElement}s to an array of native DOM elements.
+ */
 export function asNativeElements(arr: DebugElement[]): any[] {
   return arr.map((debugEl) => debugEl.nativeElement);
 }
 
+/**
+ * Set of scope functions used with {@link DebugElement}'s query functionality.
+ */
 export class Scope {
+  /**
+   * Scope queries to both the light dom and view of an element and its
+   * children.
+   *
+   * ## Example
+   *
+   * {@example core/debug/ts/debug_element/debug_element.ts region='scope_all'}
+   */
   static all(debugElement: DebugElement): DebugElement[] {
     var scope = [];
     scope.push(debugElement);
@@ -184,6 +224,14 @@ export class Scope {
 
     return scope;
   }
+
+  /**
+   * Scope queries to the light dom of an element and its children.
+   *
+   * ## Example
+   *
+   * {@example core/debug/ts/debug_element/debug_element.ts region='scope_light'}
+   */
   static light(debugElement: DebugElement): DebugElement[] {
     var scope = [];
     debugElement.children.forEach(child => {
@@ -193,6 +241,13 @@ export class Scope {
     return scope;
   }
 
+  /**
+   * Scope queries to the view of an element of its children.
+   *
+   * ## Example
+   *
+   * {@example core/debug/ts/debug_element/debug_element.ts region='scope_view'}
+   */
   static view(debugElement: DebugElement): DebugElement[] {
     var scope = [];
 

modules/angular2/src/core/di/provider.ts

@@ -30,6 +30,10 @@ import {
 } from './exceptions';
 import {resolveForwardRef} from './forward_ref';
 
+/**
+ * `Dependency` is used by the framework to extend DI.
+ * This is internal to Angular and should not be used directly.
+ */
 export class Dependency {
   constructor(public key: Key, public optional: boolean, public lowerBoundVisibility: any,
               public upperBoundVisibility: any, public properties: any[]) {}
@@ -236,6 +240,8 @@ export class Provider {
 }
 
 /**
+ * See {@link Provider} instead.
+ *
  * @deprecated
  */
 @CONST()
@@ -311,6 +317,8 @@ export interface ResolvedProvider {
 }
 
 /**
+ * See {@link ResolvedProvider} instead.
+ *
  * @deprecated
  */
 export interface ResolvedBinding extends ResolvedProvider {}
@@ -339,7 +347,6 @@ export class ResolvedFactory {
 }
 
 /**
- * @deprecated
  * Creates a {@link Provider}.
  *
  * To construct a {@link Provider}, bind a `token` to either a class, a value, a factory function,
@@ -348,6 +355,8 @@ export class ResolvedFactory {
  * See {@link ProviderBuilder} for more details.
  *
  * The `token` is most commonly a class or {@link angular2/di/OpaqueToken}.
+ *
+ * @deprecated
  */
 export function bind(token): ProviderBuilder {
   return new ProviderBuilder(token);

modules/angular2/src/core/linker/component_url_mapper.ts

@@ -8,7 +8,7 @@ import {reflector} from 'angular2/src/core/reflection/reflection';
  *
  * This interface can be overridden by the application developer to create custom behavior.
  *
- * See {@link Compiler}
+ * See {@link Compiler}.
  */
 @Injectable()
 export class ComponentUrlMapper {
@@ -23,12 +23,18 @@ export class ComponentUrlMapper {
   }
 }
 
+/**
+ * A {@link ComponentUrlMapper} that maintains an internal map of types to URLs.
+ */
 export class RuntimeComponentUrlMapper extends ComponentUrlMapper {
   /** @internal */
   _componentUrls = new Map<Type, string>();
 
   constructor() { super(); }
 
+  /**
+   * Add a mapping from component type to url to the resolver.
+   */
   setComponentUrl(component: Type, url: string) { this._componentUrls.set(component, url); }
 
   getUrl(component: Type): string {

modules/angular2/src/core/linker/view_ref.ts

@@ -40,7 +40,7 @@ export interface HostViewRef {
  *
  * Properties of elements in a View can change, but the structure (number and order) of elements in
  * a View cannot. Changing the structure of Elements can only be done by inserting, moving or
- * removing nested Views via a {@link ViewContainer}. Each View can contain many View Containers.
+ * removing nested Views via a {@link ViewContainerRef}. Each View can contain many View Containers.
  * <!-- /TODO -->
  *
  * ### Example

modules/angular2/src/core/linker/view_resolver.ts

@@ -9,6 +9,9 @@ import {Map} from 'angular2/src/facade/collection';
 import {reflector} from 'angular2/src/core/reflection/reflection';
 
 
+/**
+ * Resolves types to {@link ViewMetadata}.
+ */
 @Injectable()
 export class ViewResolver {
   /** @internal */

modules/angular2/src/core/metadata.ts

@@ -396,21 +396,33 @@ export interface QueryFactory {
   new (selector: Type | string, {descendants}?: {descendants?: boolean}): QueryMetadata;
 }
 
+/**
+ * Factory for {@link ContentChildren}.
+ */
 export interface ContentChildrenFactory {
   (selector: Type | string, {descendants}?: {descendants?: boolean}): any;
   new (selector: Type | string, {descendants}?: {descendants?: boolean}): ContentChildrenMetadata;
 }
 
+/**
+ * Factory for {@link ContentChild}.
+ */
 export interface ContentChildFactory {
   (selector: Type | string): any;
   new (selector: Type | string): ContentChildFactory;
 }
 
+/**
+ * Factory for {@link ViewChildren}.
+ */
 export interface ViewChildrenFactory {
   (selector: Type | string): any;
   new (selector: Type | string): ViewChildrenMetadata;
 }
 
+/**
+ * Factory for {@link ViewChild}.
+ */
 export interface ViewChildFactory {
   (selector: Type | string): any;
   new (selector: Type | string): ViewChildFactory;

modules/angular2/src/core/profile/wtf_impl.ts

@@ -1,5 +1,8 @@
 import {global} from 'angular2/src/facade/lang';
 
+/**
+ * A scope function for the Web Tracing Framework (WTF).
+ */
 export interface WtfScopeFn { (arg0?: any, arg1?: any): any; }
 
 interface WTF {

modules/angular2/src/core/reflection/reflection.ts

@@ -4,4 +4,8 @@ import {Reflector} from './reflector';
 export {Reflector, ReflectionInfo} from './reflector';
 import {ReflectionCapabilities} from './reflection_capabilities';
 
+/**
+ * The {@link Reflector} used internally in Angular to access metadata
+ * about symbols.
+ */
 export var reflector = new Reflector(new ReflectionCapabilities());

modules/angular2/src/core/reflection/reflector.ts

@@ -13,11 +13,18 @@ import {PlatformReflectionCapabilities} from './platform_reflection_capabilities
 export {SetterFn, GetterFn, MethodFn} from './types';
 export {PlatformReflectionCapabilities} from './platform_reflection_capabilities';
 
+/**
+ * Reflective information about a symbol, including annotations, interfaces, and other metadata.
+ */
 export class ReflectionInfo {
   constructor(public annotations?: any[], public parameters?: any[][], public factory?: Function,
               public interfaces?: any[], public propMetadata?: {[key: string]: any[]}) {}
 }
 
+/**
+ * Provides access to reflection data about symbols. Used internally by Angular
+ * to power dependency injection and compilation.
+ */
 export class Reflector {
   /** @internal */
   _injectableInfo = new Map<any, ReflectionInfo>();

modules/angular2/src/core/render/api.ts

@@ -21,9 +21,9 @@ export class RenderProtoViewRef {}
  * Represents a list of sibling Nodes that can be moved by the {@link Renderer} independently of
  * other Render Fragments.
  *
- * Any {@link RenderView} has one Render Fragment.
+ * Any {@link RenderViewRef} has one Render Fragment.
  *
- * Additionally any View with an Embedded View that contains a {@link NgContent View Projection}
+ * Additionally any View with an Embedded View that contains a {@link NgContentAst View Projection}
  * results in additional Render Fragment.
  */
 /*
@@ -71,19 +71,31 @@ export class RenderFragmentRef {}
 // TODO(i): refactor into an interface
 export class RenderViewRef {}
 
+/**
+ * Abstract base class for commands to the Angular renderer, using the visitor pattern.
+ */
 export abstract class RenderTemplateCmd {
   abstract visit(visitor: RenderCommandVisitor, context: any): any;
 }
 
+/**
+ * Command to begin rendering.
+ */
 export abstract class RenderBeginCmd extends RenderTemplateCmd {
   get ngContentIndex(): number { return unimplemented(); };
   get isBound(): boolean { return unimplemented(); };
 }
 
+/**
+ * Command to render text.
+ */
 export abstract class RenderTextCmd extends RenderBeginCmd {
   get value(): string { return unimplemented(); };
 }
 
+/**
+ * Command to render projected content.
+ */
 export abstract class RenderNgContentCmd extends RenderTemplateCmd {
   // The index of this NgContent element
   get index(): number { return unimplemented(); };
@@ -92,21 +104,33 @@ export abstract class RenderNgContentCmd extends RenderTemplateCmd {
   get ngContentIndex(): number { return unimplemented(); };
 }
 
+/**
+ * Command to begin rendering an element.
+ */
 export abstract class RenderBeginElementCmd extends RenderBeginCmd {
   get name(): string { return unimplemented(); };
   get attrNameAndValues(): string[] { return unimplemented(); };
   get eventTargetAndNames(): string[] { return unimplemented(); };
 }
 
+/**
+ * Command to begin rendering a component.
+ */
 export abstract class RenderBeginComponentCmd extends RenderBeginElementCmd {
   get templateId(): string { return unimplemented(); };
 }
 
+/**
+ * Command to render a component's template.
+ */
 export abstract class RenderEmbeddedTemplateCmd extends RenderBeginElementCmd {
   get isMerged(): boolean { return unimplemented(); };
   get children(): RenderTemplateCmd[] { return unimplemented(); };
 }
 
+/**
+ * Visitor for a {@link RenderTemplateCmd}.
+ */
 export interface RenderCommandVisitor {
   visitText(cmd: RenderTextCmd, context: any): any;
   visitNgContent(cmd: RenderNgContentCmd, context: any): any;
@@ -161,6 +185,9 @@ export interface RenderElementRef {
   boundElementIndex: number;
 }
 
+/**
+ * Template for rendering a component, including commands and styles.
+ */
 export class RenderComponentTemplate {
   constructor(public id: string, public shortId: string, public encapsulation: ViewEncapsulation,
               public commands: RenderTemplateCmd[], public styles: string[]) {}
@@ -176,7 +203,7 @@ export class RenderComponentTemplate {
  *
  * If you are implementing a custom renderer, you must implement this interface.
  *
- * The default Renderer implementation is {@link DomRenderer}. Also see {@link WebWorkerRenderer}.
+ * The default Renderer implementation is `DomRenderer`. Also available is `WebWorkerRenderer`.
  */
 export abstract class Renderer {
   /**

modules/angular2/src/core/testability/testability.ts

@@ -88,6 +88,9 @@ export class Testability {
   }
 }
 
+/**
+ * A global registry of {@link Testability} instances for specific elements.
+ */
 @Injectable()
 export class TestabilityRegistry {
   /** @internal */
@@ -108,6 +111,10 @@ export class TestabilityRegistry {
   }
 }
 
+/**
+ * Adapter interface for retrieving the `Testability` service associated for a
+ * particular context.
+ */
 export interface GetTestability {
   addToWindow(registry: TestabilityRegistry): void;
   findTestabilityInTree(registry: TestabilityRegistry, elem: any,
@@ -123,6 +130,9 @@ class _NoopGetTestability implements GetTestability {
   }
 }
 
+/**
+ * Set the {@link GetTestability} implementation used by the Angular testing framework.
+ */
 export function setTestabilityGetter(getter: GetTestability): void {
   _testabilityGetter = getter;
 }

modules/angular2/src/core/zone/ng_zone.ts

@@ -8,8 +8,14 @@ export interface NgZoneZone extends Zone {
   _innerZone: boolean;
 }
 
+/**
+ * Interface for a function with zero arguments.
+ */
 export interface ZeroArgFunction { (): void; }
 
+/**
+ * Function type for an error handler, which takes an error and a stack trace.
+ */
 export interface ErrorHandlingFn { (error: any, stackTrace: any): void; }
 
 /**