docs: add api stability indicators for @angular/common

This commit is contained in:
Igor Minar 2016-05-27 11:24:05 -07:00
parent 1c929031a2
commit 7bc2d9a93a
48 changed files with 128 additions and 24 deletions

View File

@ -44,5 +44,7 @@ import {CORE_DIRECTIVES} from './directives';
* ...
* }
* ```
*
* @experimental Contains forms which are experimental.
*/
export const COMMON_DIRECTIVES: Type[][] = /*@ts2dart_const*/[CORE_DIRECTIVES, FORM_DIRECTIVES];

View File

@ -46,6 +46,8 @@ import {NgPlural, NgPluralCase} from './ng_plural';
* ...
* }
* ```
*
* @stable
*/
export const CORE_DIRECTIVES: Type[] = /*@ts2dart_const*/[
NgClass,

View File

@ -72,6 +72,8 @@ import {StringMapWrapper, isListLikeIterable} from '../../src/facade/collection'
* }
* }
* ```
*
* @stable
*/
@Directive({selector: '[ngClass]', inputs: ['rawClass: ngClass', 'initialClasses: class']})
export class NgClass implements DoCheck, OnDestroy {

View File

@ -76,6 +76,8 @@ export class NgForRow {
*
* See a [live demo](http://plnkr.co/edit/KVuXxDp0qinGDyo307QW?p=preview) for a more detailed
* example.
*
* @stable
*/
@Directive({selector: '[ngFor][ngForOf]', inputs: ['ngForTrackBy', 'ngForOf', 'ngForTemplate']})
export class NgFor implements DoCheck {

View File

@ -22,6 +22,8 @@ import {isBlank} from '../../src/facade/lang';
* - `<div *ngIf="condition">...</div>`
* - `<div template="ngIf condition">...</div>`
* - `<template [ngIf]="condition"><div>...</div></template>`
*
* @stable
*/
@Directive({selector: '[ngIf]', inputs: ['ngIf']})
export class NgIf {

View File

@ -15,6 +15,9 @@ import {SwitchView} from './ng_switch';
const _CATEGORY_DEFAULT = 'other';
/**
* @experimental
*/
export abstract class NgLocalization { abstract getPluralCategory(value: any): string; }
/**
@ -71,6 +74,7 @@ export abstract class NgLocalization { abstract getPluralCategory(value: any): s
* }
*
* ```
* @experimental
*/
@Directive({selector: '[ngPluralCase]'})
@ -84,6 +88,9 @@ export class NgPluralCase {
}
/**
* @experimental
*/
@Directive({selector: '[ngPlural]'})
export class NgPlural implements AfterContentInit {
private _switchValue: number;

View File

@ -59,6 +59,8 @@ import {isPresent, isBlank} from '../../src/facade/lang';
*
* In this example the `font-style`, `font-size` and `font-weight` styles will be updated
* based on the `style` property's value changes.
*
* @stable
*/
@Directive({selector: '[ngStyle]', inputs: ['rawStyle: ngStyle']})
export class NgStyle implements DoCheck {

View File

@ -68,6 +68,8 @@ export class SwitchView {
*
* bootstrap(App).catch(err => console.error(err));
* ```
*
* @experimental
*/
@Directive({selector: '[ngSwitch]', inputs: ['ngSwitch']})
export class NgSwitch {
@ -166,6 +168,8 @@ export class NgSwitch {
* If multiple match expression match the switch expression value, all of them are displayed.
*
* See {@link NgSwitch} for more details and example.
*
* @experimental
*/
@Directive({selector: '[ngSwitchWhen]', inputs: ['ngSwitchWhen']})
export class NgSwitchWhen {
@ -193,6 +197,8 @@ export class NgSwitchWhen {
* value.
*
* See {@link NgSwitch} for more details and example.
*
* @experimental
*/
@Directive({selector: '[ngSwitchDefault]'})
export class NgSwitchDefault {

View File

@ -6,6 +6,8 @@ import {isPresent} from '../../src/facade/lang';
*
* ### Syntax
* - `<template [ngTemplateOutlet]="templateRefExpression"></template>`
*
* @experimental
*/
@Directive({selector: '[ngTemplateOutlet]'})
export class NgTemplateOutlet {

View File

@ -52,12 +52,7 @@ import {Type} from '@angular/core';
* ```typescript
* bootstrap(MyApp, [FORM_PROVIDERS]);
* ```
*
* @experimental
*/
export const FORM_PROVIDERS: Type[] = /*@ts2dart_const*/[FormBuilder, RadioControlRegistry];
/**
* See {@link FORM_PROVIDERS} instead.
*
* @deprecated
*/
export const FORM_BINDINGS = /*@ts2dart_const*/ FORM_PROVIDERS;

View File

@ -71,6 +71,7 @@ export {ControlValueAccessor} from './directives/control_value_accessor';
* })
* class MyApp {}
* ```
* @experimental
*/
export const FORM_DIRECTIVES: Type[] = /*@ts2dart_const*/[
NgControlName,

View File

@ -6,6 +6,8 @@ import {unimplemented} from '../../../src/facade/exceptions';
* Base class for control directives.
*
* Only used internally in the forms module.
*
* @experimental
*/
export abstract class AbstractControlDirective {
get control(): AbstractControl { return unimplemented(); }

View File

@ -14,6 +14,8 @@ export const CHECKBOX_VALUE_ACCESSOR: any = /*@ts2dart_const*/ {
* ```
* <input type="checkbox" ngControl="rememberLogin">
* ```
*
* @experimental
*/
@Directive({
selector:

View File

@ -5,6 +5,8 @@ import {AbstractControlDirective} from './abstract_control_directive';
* A directive that contains multiple {@link NgControl}s.
*
* Only used by the forms module.
*
* @experimental
*/
export class ControlContainer extends AbstractControlDirective {
name: string;

View File

@ -7,6 +7,8 @@ import {OpaqueToken} from '@angular/core';
* DOM element representing an input control.
*
* Please see {@link DefaultValueAccessor} for more information.
*
* @experimental
*/
export interface ControlValueAccessor {
/**
@ -29,6 +31,7 @@ export interface ControlValueAccessor {
* Used to provide a {@link ControlValueAccessor} for form controls.
*
* See {@link DefaultValueAccessor} for how to implement one.
* @experimental
*/
export const NG_VALUE_ACCESSOR: OpaqueToken =
/*@ts2dart_const*/ new OpaqueToken("NgValueAccessor");

View File

@ -17,6 +17,8 @@ export const DEFAULT_VALUE_ACCESSOR: any = /*@ts2dart_const*/
* ```
* <input type="text" ngControl="searchQuery">
* ```
*
* @experimental
*/
@Directive({
selector:

View File

@ -6,6 +6,8 @@ import {Control, ControlGroup} from '../model';
* An interface that {@link NgFormModel} and {@link NgForm} implement.
*
* Only used by the forms module.
*
* @experimental
*/
export interface Form {
/**

View File

@ -9,6 +9,8 @@ import {AsyncValidatorFn, ValidatorFn} from './validators';
* It binds a {@link Control} object to a DOM element.
*
* Used internally by Angular forms.
*
* @experimental
*/
export abstract class NgControl extends AbstractControlDirective {
name: string = null;

View File

@ -66,6 +66,8 @@ export const controlGroupProvider: any =
*
* This example declares a control group for a user's name. The value and validation state of
* this group can be accessed separately from the overall form.
*
* @experimental
*/
@Directive({
selector: '[ngControlGroup]',

View File

@ -87,6 +87,8 @@ export const controlNameBinding: any =
* }
* }
* ```
*
* @experimental
*/
@Directive({
selector: '[ngControl]',

View File

@ -5,6 +5,8 @@ import {isPresent} from '../../../src/facade/lang';
/**
* Directive automatically applied to Angular forms that sets CSS classes
* based on control status (valid/invalid/dirty/etc).
*
* @experimental
*/
@Directive({
selector: '[ngControl],[ngModel],[ngFormControl]',

View File

@ -75,6 +75,8 @@ export const formDirectiveProvider: any =
* }
* }
* ```
*
* @experimental
*/
@Directive({
selector: 'form:not([ngNoForm]):not([ngFormModel]),ngForm,[ngForm]',

View File

@ -76,6 +76,8 @@ export const formControlBinding: any =
* login:string;
* }
* ```
*
* @experimental
*/
@Directive({
selector: '[ngFormControl]',

View File

@ -96,6 +96,8 @@ export const formDirectiveProvider: any =
* }
* }
* ```
*
* @experimental
*/
@Directive({
selector: '[ngFormModel]',

View File

@ -47,6 +47,8 @@ export const formControlBinding: any =
* searchQuery: string;
* }
* ```
*
* @experimental
*/
@Directive({
selector: '[ngModel]:not([ngControl]):not([ngFormControl])',

View File

@ -58,6 +58,8 @@ export class RadioControlRegistry {
/**
* The value provided by the forms API for radio buttons.
*
* @experimental
*/
export class RadioButtonState {
constructor(public checked: boolean, public value: string) {}

View File

@ -43,6 +43,7 @@ function _extractId(valueString: string): string {
* https://bugzilla.mozilla.org/show_bug.cgi?id=1024350
* https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/4660045/
*
* @experimental
*/
@Directive({
selector:
@ -104,6 +105,8 @@ export class SelectControlValueAccessor implements ControlValueAccessor {
* <option *ngFor="let c of cities" [value]="c"></option>
* </select>
* ```
*
* @experimental
*/
@Directive({selector: 'option'})
export class NgSelectOption implements OnDestroy {

View File

@ -41,6 +41,8 @@ export const REQUIRED_VALIDATOR: any = /*@ts2dart_const*/ /*@ts2dart_Provider*/
* ```
* <input ngControl="fullName" required>
* ```
*
* @experimental
*/
@Directive({
selector: '[required][ngControl],[required][ngFormControl],[required][ngModel]',
@ -70,6 +72,8 @@ export const MIN_LENGTH_VALIDATOR: any = /*@ts2dart_const*/ /*@ts2dart_Provider*
/**
* A directive which installs the {@link MinLengthValidator} for any `ngControl`,
* `ngFormControl`, or control with `ngModel` that also has a `minlength` attribute.
*
* @experimental
*/
@Directive({
selector: '[minlength][ngControl],[minlength][ngFormControl],[minlength][ngModel]',
@ -101,6 +105,8 @@ export const MAX_LENGTH_VALIDATOR: any = /*@ts2dart_const*/ /*@ts2dart_Provider*
/**
* A directive which installs the {@link MaxLengthValidator} for any `ngControl, `ngFormControl`,
* or control with `ngModel` that also has a `maxlength` attribute.
*
* @experimental
*/
@Directive({
selector: '[maxlength][ngControl],[maxlength][ngFormControl],[maxlength][ngModel]',
@ -117,6 +123,13 @@ export class MaxLengthValidator implements Validator {
}
export const PATTERN_VALIDATOR: any = /*@ts2dart_const*/ /*@ts2dart_Provider*/ {
provide: NG_VALIDATORS,
useExisting: forwardRef(() => PatternValidator),
multi: true
};
/**
* A Directive that adds the `pattern` validator to any controls marked with the
* `pattern` attribute, via the {@link NG_VALIDATORS} binding. Uses attribute value
@ -128,12 +141,8 @@ export class MaxLengthValidator implements Validator {
* ```
* <input [ngControl]="fullName" pattern="[a-zA-Z ]*">
* ```
* @experimental
*/
export const PATTERN_VALIDATOR: any = /*@ts2dart_const*/ /*@ts2dart_Provider*/ {
provide: NG_VALIDATORS,
useExisting: forwardRef(() => PatternValidator),
multi: true
};
@Directive({
selector: '[pattern][ngControl],[pattern][ngFormControl],[pattern][ngModel]',
providers: [PATTERN_VALIDATOR]

View File

@ -45,6 +45,8 @@ import {ValidatorFn, AsyncValidatorFn} from './directives/validators';
* }
* }
* ```
*
* @experimental
*/
@Injectable()
export class FormBuilder {

View File

@ -50,7 +50,7 @@ function toObservable(r: any): Observable<any> {
}
/**
*
* @experimental
*/
export abstract class AbstractControl {
/** @internal */
@ -266,6 +266,8 @@ export abstract class AbstractControl {
* validation function.
*
* ### Example ([live demo](http://plnkr.co/edit/23DESOpbNnBpBHZt1BR4?p=preview))
*
* @experimental
*/
export class Control extends AbstractControl {
/** @internal */
@ -331,6 +333,8 @@ export class Control extends AbstractControl {
* controls, but is of variable length.
*
* ### Example ([live demo](http://plnkr.co/edit/23DESOpbNnBpBHZt1BR4?p=preview))
*
* @experimental
*/
export class ControlGroup extends AbstractControl {
private _optionals: {[key: string]: boolean};
@ -448,6 +452,8 @@ export class ControlGroup extends AbstractControl {
* as broken change detection.
*
* ### Example ([live demo](http://plnkr.co/edit/23DESOpbNnBpBHZt1BR4?p=preview))
*
* @experimental
*/
export class ControlArray extends AbstractControl {
constructor(public controls: AbstractControl[], validator: ValidatorFn = null,

View File

@ -14,6 +14,7 @@ import {ValidatorFn, AsyncValidatorFn} from './directives/validators';
* ### Example
*
* {@example core/forms/ts/ng_validators/ng_validators.ts region='ng_validators'}
* @experimental
*/
export const NG_VALIDATORS: OpaqueToken = /*@ts2dart_const*/ new OpaqueToken("NgValidators");
@ -24,6 +25,8 @@ export const NG_VALIDATORS: OpaqueToken = /*@ts2dart_const*/ new OpaqueToken("Ng
* Provide this using `multi: true` to add validators.
*
* See {@link NG_VALIDATORS} for more details.
*
* @experimental
*/
export const NG_ASYNC_VALIDATORS: OpaqueToken =
/*@ts2dart_const*/ new OpaqueToken("NgAsyncValidators");
@ -39,6 +42,8 @@ export const NG_ASYNC_VALIDATORS: OpaqueToken =
* ```typescript
* var loginControl = new Control("", Validators.required)
* ```
*
* @experimental
*/
export class Validators {
/**

View File

@ -45,6 +45,8 @@ import {UrlChangeListener, PlatformLocation} from './platform_location';
* provide(LocationStrategy, {useClass: HashLocationStrategy})
* ]);
* ```
*
* @stable
*/
@Injectable()
export class HashLocationStrategy extends LocationStrategy {

View File

@ -42,6 +42,8 @@ import {LocationStrategy} from './location_strategy';
*
* bootstrap(AppCmp, [ROUTER_PROVIDERS]);
* ```
*
* @stable
*/
@Injectable()
export class Location {

View File

@ -16,6 +16,8 @@ import {UrlChangeListener} from './platform_location';
* `http://example.com/foo` as an equivalent URL.
*
* See these two classes for more.
*
* @stable
*/
export abstract class LocationStrategy {
abstract path(): string;
@ -57,5 +59,6 @@ export abstract class LocationStrategy {
* provide(APP_BASE_HREF, {useValue: '/my/app'})
* ]);
* ```
* @stable
*/
export const APP_BASE_HREF: OpaqueToken = /*@ts2dart_const*/ new OpaqueToken('appBaseHref');

View File

@ -53,6 +53,8 @@ import {Location} from './location';
* provide(APP_BASE_HREF, {useValue: '/my/app'})
* ]);
* ```
*
* @stable
*/
@Injectable()
export class PathLocationStrategy extends LocationStrategy {

View File

@ -21,6 +21,8 @@
* {@link Location} / {@link LocationStrategy} and DOM apis flow through the `PlatformLocation`
* class
* they are all platform independent.
*
* @stable
*/
export abstract class PlatformLocation {
abstract getBaseHrefFromDOM(): string;
@ -42,6 +44,8 @@ export abstract class PlatformLocation {
/**
* A serializable version of the event from onPopState or onHashChange
*
* @stable
*/
export interface UrlChangeEvent { type: string; }

View File

@ -59,6 +59,8 @@ var __unused: Promise<any>; // avoid unused import when Promise union types are
* to the view. Every 500ms, the `time` Observable updates the view with the current time.
*
* {@example core/pipes/ts/async_pipe/async_pipe_example.ts region='AsyncPipeObservable'}
*
* @stable
*/
@Pipe({name: 'async', pure: false})
@Injectable()

View File

@ -20,6 +20,8 @@ import {I18nSelectPipe} from './i18n_select_pipe';
*
* This collection can be used to quickly enumerate all the built-in pipes in the `pipes`
* property of the `@Component` decorator.
*
* @experimental Contains i18n pipes which are experimental
*/
export const COMMON_PIPES = /*@ts2dart_const*/[
AsyncPipe,

View File

@ -81,6 +81,8 @@ var defaultLocale: string = 'en-US';
* ```
*
* {@example core/pipes/ts/date_pipe/date_pipe_example.ts region='DatePipe'}
*
* @experimental
*/
@Pipe({name: 'date', pure: true})
@Injectable()

View File

@ -34,9 +34,9 @@ var interpolationExp: RegExp = RegExpWrapper.create('#');
* }
* ```
*
* @experimental
*/
@Pipe({name: 'i18nPlural', pure: true})
@Injectable()
export class I18nPluralPipe implements PipeTransform {
transform(value: number, pluralMap: {[count: string]: string}): string {
var key: string;

View File

@ -31,9 +31,10 @@ import {InvalidPipeArgumentException} from './invalid_pipe_argument_exception';
* ...
* }
* ```
*
* @experimental
*/
@Pipe({name: 'i18nSelect', pure: true})
@Injectable()
export class I18nSelectPipe implements PipeTransform {
transform(value: string, mapping: {[key: string]: string}): string {
if (!isStringMap(mapping)) {

View File

@ -7,10 +7,10 @@ import {Json} from '../../src/facade/lang';
*
* ### Example
* {@example core/pipes/ts/json_pipe/json_pipe_example.ts region='JsonPipe'}
*
* @stable
*/
/* @ts2dart_const */
@Pipe({name: 'json', pure: false})
@Injectable()
export class JsonPipe implements PipeTransform {
transform(value: any): string { return Json.stringify(value); }
}

View File

@ -8,10 +8,10 @@ import {InvalidPipeArgumentException} from './invalid_pipe_argument_exception';
* ### Example
*
* {@example core/pipes/ts/lowerupper_pipe/lowerupper_pipe_example.ts region='LowerUpperPipe'}
*
* @experimental
*/
/* @ts2dart_const */
@Pipe({name: 'lowercase'})
@Injectable()
export class LowerCasePipe implements PipeTransform {
transform(value: string): string {
if (isBlank(value)) return value;

View File

@ -35,6 +35,10 @@ import {InvalidPipeArgumentException} from './invalid_pipe_argument_exception';
* --Note--: The 'pattern' parameter will be converted to a RegExp instance. Make sure to escape the
* string properly if you are matching for regular expression special characters like parenthesis,
* brackets etc.
*
* @deprecated The current pipe has limited functionality. The pipe api is not meant to be able
* express complex yet generic value transformations. We recommend that these transformations happen
* in the component logic instead.
*/
@Pipe({name: 'replace'})

View File

@ -58,10 +58,11 @@ import {InvalidPipeArgumentException} from './invalid_pipe_argument_exception';
* ## String Examples
*
* {@example core/pipes/ts/slice_pipe/slice_pipe_example.ts region='SlicePipe_string'}
*
* @stable
*/
@Pipe({name: 'slice', pure: false})
@Injectable()
export class SlicePipe implements PipeTransform {
transform(value: any, start: number, end: number = null): any {
if (isBlank(value)) return value;

View File

@ -8,9 +8,10 @@ import {InvalidPipeArgumentException} from './invalid_pipe_argument_exception';
* ### Example
*
* {@example core/pipes/ts/lowerupper_pipe/lowerupper_pipe_example.ts region='LowerUpperPipe'}
*
* @experimental
*/
@Pipe({name: 'uppercase'})
@Injectable()
export class UpperCasePipe implements PipeTransform {
transform(value: string): string {
if (isBlank(value)) return value;

View File

@ -158,7 +158,7 @@ export class InjectSetupWrapper {
};
}
/** @Deprecated {use async(withProviders().inject())} */
/** @deprecated {use async(withProviders().inject())} */
injectAsync(tokens: any[], fn: Function): Function {
return () => {
this._addProviders();
@ -172,7 +172,7 @@ export function withProviders(providers: () => any) {
}
/**
* @Deprecated {use async(inject())}
* @deprecated {use async(inject())}
*
* Allows injecting dependencies in `beforeEach()` and `it()`. The test must return
* a promise which will resolve when all asynchronous activity is complete.

View File

@ -52,7 +52,6 @@ var COMMON: string[] = [
'DatePipe',
'DecimalPipe',
'DefaultValueAccessor',
'FORM_BINDINGS',
'FORM_DIRECTIVES',
'FORM_PROVIDERS',
'Form:dart',