diff --git a/modules/angular2/angular2.js b/modules/angular2/angular2.js index 86a7965ec7..4304148b5b 100644 --- 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 index 6673bcdd6b..30114765ce 100644 --- 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 index dda0bbf525..6c8cad046b 100644 --- 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 index 80309a3789..1fa877cd5e 100644 --- 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'; \ No newline at end of file +export * from './src/forms/form_builder'; diff --git a/modules/angular2/pipes.js b/modules/angular2/pipes.js index 6492c1f35c..95a1822031 100644 --- 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 index da3f189319..0ff1114648 100644 --- 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;} -} \ No newline at end of file +} diff --git a/modules/angular2/src/core/annotations/annotations.js b/modules/angular2/src/core/annotations/annotations.js index c2a32d038b..106895f16c 100644 --- 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 `
` or any other element with the `tooltip` selector, * like so: * - * ``` + * ``` *
* ``` * diff --git a/modules/angular2/src/core/annotations/view.js b/modules/angular2/src/core/annotations/view.js index b42f7eed77..68fcea319e 100644 --- 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 index b8ba991fc4..e8facc307e 100644 --- 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 = null, diff --git a/modules/angular2/src/core/compiler/ng_element.js b/modules/angular2/src/core/compiler/ng_element.js index 5c8f6d3e86..354e0b5f9e 100644 --- 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 index 1d74b28b17..3a0272d3b1 100644 --- 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 index 0bfdeabfac..c803f54280 100644 --- 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 index e1e63b77cc..494caa652e 100644 --- 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 + * ``` + * + * ``` + * * @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 + * ``` + * + * ``` + * * @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: "" + * }) + * 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: "
" + + * "Login " + + * "Password " + + * "" + + * "
" + * }) + * 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 index fa83a9a0de..005aa37e7e 100644 --- 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); } } -} \ No newline at end of file +} diff --git a/modules/angular2/src/forms/model.js b/modules/angular2/src/forms/model.js index c14120c458..cece2670ee 100644 --- 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 index 39dd6e8cc3..ac08b56412 100644 --- 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 index 350361205f..2d6c2802a2 100644 --- a/modules/angular2/src/render/dom/compiler/template_loader.js +++ b/modules/angular2/src/render/dom/compiler/template_loader.js @@ -11,7 +11,7 @@ import {UrlResolver} from 'angular2/src/services/url_resolver'; /** * Strategy to load component templates. - * @exportedAs angular2/angular2 + * @exportedAs angular2/core */ @Injectable() export class TemplateLoader {