cleanup(docs): Edited API docs

This commit is contained in:
Naomi Black 2015-04-10 11:15:01 -07:00
parent 2ed7622239
commit e295940833
17 changed files with 197 additions and 22 deletions

View File

@ -1,9 +1,3 @@
/**
* @module
* @public
* @description
* Define public API for Angular here.
*/
export * from './change_detection';
export * from './core';
export * from './annotations';

View File

@ -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';

View File

@ -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';

View File

@ -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';

View File

@ -2,5 +2,5 @@
* @module
* @public
* @description
* Define public API for Angular here.
* This module provides advanced support for extending change detection.
*/

View File

@ -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;}
}
}

View File

@ -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>
* ```
*

View File

@ -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;

View File

@ -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,

View File

@ -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;

View File

@ -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 {

View File

@ -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:

View File

@ -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.

View File

@ -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);
}
}
}
}

View File

@ -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 {

View File

@ -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 {

View File

@ -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 {