cleanup(docs): Edited API docs

naomiblack · naomiblack · commit e29594083399 · 2015-04-10T18:02:10.000-07:00
diff --git a/modules/angular2/angular2.js b/modules/angular2/angular2.js
@@ -1,9 +1,3 @@
-/**
- * @module
- * @public
- * @description
- * Define public API for Angular here.
- */
 export * from './change_detection';
 export * from './core';
 export * from './annotations';
diff --git a/modules/angular2/annotations.js b/modules/angular2/annotations.js
@@ -2,6 +2,10 @@
  * @module
  * @public
  * @description
- * Define public API for Angular here.
+ *
+ * Annotations provide the additional information that Angular requires in order to run your application. This module
+ * contains [Component], [Decorator], and [View] annotations, as well as [Parent] and [Ancestor] annotations that are
+ * used by Angular to resolve dependencies.
+ *
  */
 export * from './src/core/annotations/annotations';
diff --git a/modules/angular2/core.js b/modules/angular2/core.js
@@ -1,3 +1,9 @@
+/**
+ * @module
+ * @public
+ * @description
+ * Define public API for Angular here.
+ */
 export * from './src/core/annotations/visibility';
 export * from './src/core/compiler/interfaces';
 export * from './src/core/annotations/view';
diff --git a/modules/angular2/forms.js b/modules/angular2/forms.js
@@ -2,11 +2,14 @@
  * @module
  * @public
  * @description
- * Describe the forms module here
+ * This module is used for handling complex input, by defining and building a [FormObject] that consists of [Control]
+ * objects, and mapping them onto the DOM. [Control] objects can then be used to read information from the form DOM
+ * elements.
+ *
  */
 
 export * from './src/forms/model';
 export * from './src/forms/directives';
 export * from './src/forms/validators';
 export * from './src/forms/validator_directives';
-export * from './src/forms/form_builder';
+export * from './src/forms/form_builder';
diff --git a/modules/angular2/pipes.js b/modules/angular2/pipes.js
@@ -2,5 +2,5 @@
  * @module
  * @public
  * @description
- * Define public API for Angular here.
+ * This module provides advanced support for extending change detection.
  */
diff --git a/modules/angular2/src/change_detection/pipes/pipe.js b/modules/angular2/src/change_detection/pipes/pipe.js
@@ -1,10 +1,37 @@
+/**
+ * Indicates that the result of a [Pipe] transformation has not changed since the last time the pipe was called.
+ *
+ * Suppose we have a pipe that computes changes in an array by performing a simple diff operation. If
+ * we call this pipe with the same array twice, it will return `NO_CHANGE` the second time.
+ *
+ * @exportedAs angular2/pipes
+ */
+
 export var NO_CHANGE = new Object();
 
 /**
- * @exportedAs angular2/angular2
+ * An interface for extending the list of pipes known to Angular.
+ *
+ * If you are writing a custom [Pipe], you must extend this interface.
+ *
+ * #Example
+ *
+ * ```
+ * class DoublePipe extends Pipe {
+ *  supports(obj) {
+ *    return true;
+ *  }
+ *
+ *  transform(value) {
+ *    return `${value}${value}`;
+ *  }
+ * }
+ * ```
+ *
+ * @exportedAs angular2/pipes
  */
 export class Pipe {
   supports(obj):boolean {return false;}
   onDestroy() {}
   transform(value:any):any {return null;}
-}
+}
diff --git a/modules/angular2/src/core/annotations/annotations.js b/modules/angular2/src/core/annotations/annotations.js
@@ -702,7 +702,7 @@ export class DynamicComponent extends Directive {
  * In our HTML template, we can then add this behavior to a `<div>` or any other element with the `tooltip` selector,
  * like so:
  *
- *  ```
+ * ```
  * <div tooltip="some text here"></div>
  * ```
  *
diff --git a/modules/angular2/src/core/annotations/view.js b/modules/angular2/src/core/annotations/view.js
@@ -18,7 +18,8 @@ import {ABSTRACT, CONST, Type} from 'angular2/src/facade/lang';
  *   selector: 'greet'
  * })
  * @View({
- *   template: 'Hello {{name}}!'
+ *   template: 'Hello {{name}}!',
+ *   directives: [GreetUser, Bold]
  * })
  * class Greet {
  *   name: string;
diff --git a/modules/angular2/src/core/application.js b/modules/angular2/src/core/application.js
@@ -240,7 +240,7 @@ function _createVmZone(givenReporter:Function): VmTurnZone {
  *
  * Returns a [Promise] with the application`s private [Injector].
  *
- * @exportedAs angular2/angular2
+ * @exportedAs angular2/core
  */
 export function bootstrap(appComponentType: Type,
                           componentInjectableBindings: List<Binding> = null,
diff --git a/modules/angular2/src/core/compiler/ng_element.js b/modules/angular2/src/core/compiler/ng_element.js
@@ -9,7 +9,7 @@ import {DirectDomViewRef} from 'angular2/src/render/dom/direct_dom_renderer';
  * Attention: NgElement will be replaced by a different concept
  * for accessing an element in a way that is compatible with the render layer.
  *
- * @exportedAs angular2/angular2
+ * @exportedAs angular2/core
  */
 export class NgElement {
   _view:viewModule.AppView;
diff --git a/modules/angular2/src/core/exception_handler.js b/modules/angular2/src/core/exception_handler.js
@@ -3,7 +3,7 @@ import {isPresent, print} from 'angular2/src/facade/lang';
 import {ListWrapper, isListLikeIterable} from 'angular2/src/facade/collection';
 
 /**
- * @exportedAs angular2/angular2
+ * @exportedAs angular2/core
  */
 @Injectable()
 export class ExceptionHandler {
diff --git a/modules/angular2/src/directives/if.js b/modules/angular2/src/directives/if.js
@@ -3,8 +3,9 @@ import {ViewContainer} from 'angular2/src/core/compiler/view_container';
 import {isBlank} from 'angular2/src/facade/lang';
 
 /**
- * The `If` directive removes or recreates a portion of the DOM tree based on an {expression}. If
- * the expression assigned to `if` evaluates to a false value then the element is removed from the
+ * Removes or recreates a portion of the DOM tree based on an {expression}.
+ *
+ * If the expression assigned to `if` evaluates to a false value then the element is removed from the
  * DOM, otherwise a clone of the element is reinserted into the DOM.
  *
  * # Example:
diff --git a/modules/angular2/src/forms/directives.js b/modules/angular2/src/forms/directives.js
@@ -11,6 +11,15 @@ import {Validators} from './validators';
 //}
 
 /**
+ * The default accessor for writing a value and listening to changes that is used by a [Control] directive.
+ *
+ * This is the default strategy that Angular uses when no other accessor is applied.
+ *
+ *  # Example
+ *  ```
+ *  <input type="text" [control]="loginControl">
+ *  ```
+ *
  * @exportedAs angular2/forms
  */
 @Decorator({
@@ -35,6 +44,14 @@ export class DefaultValueAccessor {
 }
 
 /**
+ * The accessor for writing a value and listening to changes on a checkbox input element.
+ *
+ *
+ *  # Example
+ *  ```
+ *  <input type="checkbox" [control]="rememberLogin">
+ *  ```
+ *
  * @exportedAs angular2/forms
  */
 @Decorator({
@@ -59,6 +76,33 @@ export class CheckboxControlValueAccessor {
 }
 
 /**
+ * Binds a control to a DOM element.
+ *
+ * # Example
+ *
+ * In this example, we bind the control to an input element. When the value of the input element changes, the value of
+ * the control will reflect that change. Likewise, if the value of the control changes, the input element reflects that
+ * change.
+ *
+ * Here we use [FormDirectives], rather than importing each form directive individually, e.g.
+ * `ControlDirective`, `ControlGroupDirective`. This is just a shorthand for the same end result.
+ *
+ *  ```
+ * @Component({selector: "login-comp"})
+ * @View({
+ *      directives: [FormDirectives],
+ *      inline: "<input type='text' [control]='loginControl'>"
+ *      })
+ * class LoginComp {
+ *  loginControl:Control;
+ *
+ *  constructor() {
+ *    this.loginControl = new Control('');
+ *  }
+ * }
+ *
+ *  ```
+ *
  * @exportedAs angular2/forms
  */
 @Decorator({
@@ -119,6 +163,43 @@ export class ControlDirective {
 }
 
 /**
+ * Binds a control group to a DOM element.
+ *
+ * # Example
+ *
+ * In this example, we bind the control group to the form element, and we bind the login and password controls to the
+ * login and password elements.
+ *
+ * Here we use [FormDirectives], rather than importing each form directive individually, e.g.
+ * `ControlDirective`, `ControlGroupDirective`. This is just a shorthand for the same end result.
+ *
+ *  ```
+ * @Component({selector: "login-comp"})
+ * @View({
+ *      directives: [FormDirectives],
+ *      inline: "<form [control-group]='loginForm'>" +
+ *              "Login <input type='text' control='login'>" +
+ *              "Password <input type='password' control='password'>" +
+ *              "<button (click)="onLogin()">Login</button>" +
+ *              "</form>"
+ *      })
+ * class LoginComp {
+ *  loginForm:ControlGroup;
+ *
+ *  constructor() {
+ *    this.loginForm = new ControlGroup({
+ *      login: new Control(""),
+ *      password: new Control("")
+ *    });
+ *  }
+ *
+ *  onLogin() {
+ *    // this.loginForm.value
+ *  }
+ * }
+ *
+ *  ```
+ *
  * @exportedAs angular2/forms
  */
 @Decorator({
@@ -170,6 +251,11 @@ export class ControlGroupDirective {
 }
 
 /**
+ *
+ * A list of all the form directives used as part of a `@View` annotation.
+ *
+ *  This is a shorthand for importing them each individually.
+ *
  * @exportedAs angular2/forms
  */
 // todo(misko): rename to lover case as it is not a Type but a var.
diff --git a/modules/angular2/src/forms/form_builder.js b/modules/angular2/src/forms/form_builder.js
@@ -4,6 +4,24 @@ import * as modelModule from './model';
 
 
 /**
+ * Creates a form object from a user-specified configuration.
+ *
+ * # Example
+ *
+ * This example creates a [ControlGroup] that consists of a `login` [Control], and a nested [ControlGroup] that defines
+ * a `password` and a `passwordConfirmation` [Control].
+ *
+ * ```
+ *  var loginForm = builder.group({
+ *    login: ["", Validators.required],
+ *
+ *    passwordRetry: builder.group({
+ *      password: ["", Validators.required],
+ *      passwordConfirmation: ["", Validators.required]
+ *    })
+ *  });
+ *
+ *  ```
  * @exportedAs angular2/forms
  */
 export class FormBuilder {
@@ -59,4 +77,4 @@ export class FormBuilder {
       return this.control(controlConfig);
     }
   }
-}
+}
diff --git a/modules/angular2/src/forms/model.js b/modules/angular2/src/forms/model.js
@@ -4,11 +4,15 @@ import {StringMap, StringMapWrapper, ListWrapper, List} from 'angular2/src/facad
 import {Validators} from './validators';
 
 /**
+ * Indicates that a Control is valid, i.e. that no errors exist in the input value.
+ *
  * @exportedAs angular2/forms
  */
 export const VALID = "VALID";
 
 /**
+ * Indicates that a Control is invalid, i.e. that an error exists in the input value.
+ *
  * @exportedAs angular2/forms
  */
 export const INVALID = "INVALID";
@@ -26,7 +30,7 @@ export const INVALID = "INVALID";
 //}
 
 /**
- * @exportedAs angular2/forms
+ * Omitting from external API doc as this is really an abstract internal concept.
  */
 export class AbstractControl {
   _value:any;
@@ -80,6 +84,11 @@ export class AbstractControl {
 }
 
 /**
+ * Defines a part of a form that cannot be divided into other controls.
+ *
+ * `Control` is one of the three fundamental building blocks used to define forms in Angular, along with [ControlGroup]
+ * and [ControlArray].
+ *
  * @exportedAs angular2/forms
  */
 export class Control extends AbstractControl {
@@ -108,6 +117,15 @@ export class Control extends AbstractControl {
 }
 
 /**
+ * Defines a part of a form, of fixed length, that can contain other controls.
+ *
+ * A ControlGroup aggregates the values and errors of each [Control] in the group. Thus, if one of the controls in a
+ * group is invalid, the entire group is invalid. Similarly, if a control changes its value, the entire group changes
+ * as well.
+ *
+ * `ControlGroup` is one of the three fundamental building blocks used to define forms in Angular, along with [Control]
+ * and [ControlArray]. [ControlArray] can also contain other controls, but is of variable length.
+ *
  * @exportedAs angular2/forms
  */
 export class ControlGroup extends AbstractControl {
@@ -186,6 +204,15 @@ export class ControlGroup extends AbstractControl {
 }
 
 /**
+ * Defines a part of a form, of variable length, that can contain other controls.
+ *
+ * A `ControlArray` aggregates the values and errors of each [Control] in the group. Thus, if one of the controls in a
+ * group is invalid, the entire group is invalid. Similarly, if a control changes its value, the entire group changes
+ * as well.
+ *
+ * `ControlArray` is one of the three fundamental building blocks used to define forms in Angular, along with [Control]
+ * and [ControlGroup]. [ControlGroup] can also contain other controls, but is of fixed length.
+ *
  * @exportedAs angular2/forms
  */
 export class ControlArray extends AbstractControl {
diff --git a/modules/angular2/src/forms/validators.js b/modules/angular2/src/forms/validators.js
@@ -4,6 +4,14 @@ import {List, ListWrapper, StringMapWrapper} from 'angular2/src/facade/collectio
 import * as modelModule from './model';
 
 /**
+ * Provides a set of validators used by form controls.
+ *
+ * # Example
+ *
+ * ```
+ * var loginControl = new Control("", Validators.required)
+ * ```
+ *
  * @exportedAs angular2/forms
  */
 export class Validators {
diff --git a/modules/angular2/src/render/dom/compiler/template_loader.js b/modules/angular2/src/render/dom/compiler/template_loader.js

Original file line number	Diff line number	Diff line change
`@@ -702,7 +702,7 @@ export class DynamicComponent extends Directive {`
`702`	`702`	* In our HTML template, we can then add this behavior to a `<div>` or any other element with the `tooltip` selector,
`703`	`703`	`* like so:`
`704`	`704`	`*`
`705`		- * ```
	`705`	+ * ```
`706`	`706`	`* <div tooltip="some text here"></div>`
`707`	`707`	* ```
`708`	`708`	`*`
Original file line number	Diff line number	Diff line change
`@@ -240,7 +240,7 @@ function _createVmZone(givenReporter:Function): VmTurnZone {`
`240`	`240`	`*`
`241`	`241`	* Returns a [Promise] with the application`s private [Injector].
`242`	`242`	`*`
`243`		`- * @exportedAs angular2/angular2`
	`243`	`+ * @exportedAs angular2/core`
`244`	`244`	`*/`
`245`	`245`	`export function bootstrap(appComponentType: Type,`
`246`	`246`	`componentInjectableBindings: List<Binding> = null,`
Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ import {DirectDomViewRef} from 'angular2/src/render/dom/direct_dom_renderer';`
`9`	`9`	`* Attention: NgElement will be replaced by a different concept`
`10`	`10`	`* for accessing an element in a way that is compatible with the render layer.`
`11`	`11`	`*`
`12`		`- * @exportedAs angular2/angular2`
	`12`	`+ * @exportedAs angular2/core`
`13`	`13`	`*/`
`14`	`14`	`export class NgElement {`
`15`	`15`	`_view:viewModule.AppView;`