iSharkFly-Docs/angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(core): Myriad of documentation changes including lots of new example code.

Browse Source
This commit is contained in:
Alex Rickabaugh
2015-11-30 08:28:54 -08:00
committed by vsavkin
parent f0d876a873
commit 778677ba75
16 changed files with 306 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files
modules/angular2/src/common/forms/validators.ts
+10 -4
View File
@@ -13,13 +13,19 @@ import * as modelModule from './model';
*
* ### Example
*
* ```typescript
* var providers = [
* new Provider(NG_VALIDATORS, {useValue: myValidator, multi: true})
* ];
* {@example core/forms/ts/ng_validators/ng_validators.ts region='ng_validators'}
* ```
*/
export const NG_VALIDATORS: OpaqueToken = CONST_EXPR(new OpaqueToken("NgValidators"));
/**
* Providers for asynchronous validators to be used for {@link Control}s
* in a form.
*
* Provide this using `multi: true` to add validators.
*
* See {@link NG_VALIDATORS} for more details.
*/
export const NG_ASYNC_VALIDATORS: OpaqueToken = CONST_EXPR(new OpaqueToken("NgAsyncValidators"));
/**
modules/angular2/src/core/application_ref.ts
+2 -11
View File
@@ -173,13 +173,8 @@ export abstract class PlatformRef {
* typical providers, as shown in the example below.
*
* ### Example
* ```
* var myAppProviders = [MyAppService];
*
* platform()
* .application([myAppProviders])
* .bootstrap(MyTopLevelComponent);
* ```
* {@example core/ts/platform/platform.ts region='longform'}
* ### See Also
*
* See the {@link bootstrap} documentation for more details.
@@ -315,11 +310,7 @@ export abstract class ApplicationRef {
* child components under it.
*
* ### Example
* ```
* var app = platform.application([appProviders];
* app.bootstrap(FirstRootComponent);
* app.bootstrap(SecondRootComponent, [provide(OverrideBinding, {useClass: OverriddenBinding})]);
* ```
* {@example core/ts/platform/platform.ts region='longform'}
*/
abstract bootstrap(componentType: Type,
providers?: Array<Type | Provider | any[]>): Promise<ComponentRef>;
modules/angular2/src/core/debug/debug_element.ts
+4 -1
View File
@@ -10,6 +10,9 @@ import {ElementRef, ElementRef_} from 'angular2/src/core/linker/element_ref';
* A DebugElement contains information from the Angular compiler about an
* 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}.
*/
export abstract class DebugElement {
get componentInstance(): any { return unimplemented(); };
@@ -156,7 +159,7 @@ export class DebugElement_ extends DebugElement {
}
/**
* Returns a DebugElement for a ElementRef.
* Returns a {@link DebugElement} for an {@link ElementRef}.
*
* @param {ElementRef}: elementRef
* @return {DebugElement}
modules/angular2/src/core/di/forward_ref.ts
+3 -22
View File
@@ -5,9 +5,7 @@ import {Type, stringify, isFunction} from 'angular2/src/facade/lang';
*
* ### Example
*
* ```typescript
* var fn:ForwardRefFn = forwardRef(() => Lock);
* ```
* {@example core/di/ts/forward_ref/forward_ref.ts region='forward_ref_fn'}
*/
export interface ForwardRefFn { (): any; }
@@ -19,25 +17,8 @@ export interface ForwardRefFn { (): any; }
* but not yet defined. It is also used when the `token` which we use when creating a query is not
* yet defined.
*
* ### Example ([live demo](http://plnkr.co/edit/bRs0SX2OTQiJzqvjgl8P?p=preview))
*
* ```typescript
* class Door {
* lock: Lock;
* constructor(@Inject(forwardRef(() => Lock)) lock:Lock) {
* this.lock = lock;
* }
* }
*
* // Only at this point Lock is defined.
* class Lock {
* }
*
* var injector = Injector.resolveAndCreate([Door, Lock]);
* var door = injector.get(Door);
* expect(door instanceof Door).toBe(true);
* expect(door.lock instanceof Lock).toBe(true);
* ```
* ### Example
* {@example core/di/ts/forward_ref/forward_ref.ts region='forward_ref'}
*/
export function forwardRef(forwardRefFn: ForwardRefFn): Type {
(<any>forwardRefFn).__forward_ref__ = forwardRef;
modules/angular2/src/core/metadata.ts
+16 -87
View File
@@ -109,16 +109,7 @@ export interface ViewDecorator extends TypeDecorator {
*
* ### Example as TypeScript Decorator
*
* ```
* import {Directive} from "angular2/angular2";
*
* @Directive({...})
* class MyDirective {
* constructor() {
* ...
* }
* }
* ```
* {@example core/ts/metadata/metadata.ts region='directive'}
*
* ### Example as ES5 DSL
*
@@ -178,16 +169,7 @@ export interface DirectiveFactory {
*
* ### Example as TypeScript Decorator
*
* ```
* import {Component} from "angular2/angular2";
*
* @Component({...})
* class MyComponent {
* constructor() {
* ...
* }
* }
* ```
* {@example core/ts/metadata/metadata.ts region='component'}
*
* ### Example as ES5 DSL
*
@@ -334,16 +316,7 @@ export interface ViewFactory {
*
* ### Example as TypeScript Decorator
*
* ```
* import {Attribute, Component} from "angular2/angular2";
*
* @Component({...})
* class MyComponent {
* constructor(@Attribute('title') title: string) {
* ...
* }
* }
* ```
* {@example core/ts/metadata/metadata.ts region='attributeFactory'}
*
* ### Example as ES5 DSL
*
@@ -449,20 +422,9 @@ export interface ViewChildFactory {
/**
* {@link PipeMetadata} factory for creating decorators.
*
* ### Example as TypeScript Decorator
* ### Example
*
* ```
* import {Pipe} from "angular2/angular2";
*
* @Pipe({...})
* class MyPipe {
* constructor() {
* ...
* }
*
* transform(v, args) {}
* }
* ```
* {@example core/ts/metadata/metadata.ts region='pipe'}
*/
export interface PipeFactory {
(obj: {name: string, pure?: boolean}): any;
@@ -530,20 +492,7 @@ export interface HostListenerFactory {
*
* ### Example
*
* ```
* @Component({
* selector: 'greet',
* template: 'Hello {{name}}!'
* })
* class Greet {
* name: string;
*
* constructor() {
* this.name = 'World';
* }
* }
* ```
*
* {@example core/ts/metadata/metadata.ts region='component'}
*/
export var Component: ComponentFactory =
<ComponentFactory>makeDecorator(ComponentMetadata, (fn: any) => fn.View = View);
@@ -962,35 +911,22 @@ export var Directive: DirectiveFactory = <DirectiveFactory>makeDecorator(Directi
export var View: ViewFactory =
<ViewFactory>makeDecorator(ViewMetadata, (fn: any) => fn.View = View);
// TODO(alexeagle): remove the duplication of this doc. It is copied from AttributeMetadata.
/**
* Metadata properties available for configuring Views.
* Specifies that a constant attribute value should be injected.
*
* Each Angular component requires a single `@Component` and at least one `@View` annotation. The
* `@View` annotation specifies the HTML template to use, and lists the directives that are active
* within the template.
*
* When a component is instantiated, the template is loaded into the component's shadow root, and
* the expressions and statements in the template are evaluated against the component.
*
* For details on the `@Component` annotation, see {@link ComponentMetadata}.
* The directive can inject constant string literals of host element attributes.
*
* ### Example
*
* ```
* @Component({
* selector: 'greet',
* template: 'Hello {{name}}!',
* directives: [GreetUser, Bold]
* })
* class Greet {
* name: string;
* Suppose we have an `<input>` element and want to know its `type`.
*
* constructor() {
* this.name = 'World';
* }
* }
* ```html
* <input type="text">
* ```
*
* A decorator can inject string literal `text` like so:
*
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
*/
export var Attribute: AttributeFactory = makeParamDecorator(AttributeMetadata);
@@ -1244,14 +1180,7 @@ export var ViewQuery: QueryFactory = makeParamDecorator(ViewQueryMetadata);
*
* ### Example
*
* ```
* @Pipe({
* name: 'lowercase'
* })
* class Lowercase {
* transform(v, args) { return v.toLowerCase(); }
* }
* ```
* {@example core/ts/metadata/metadata.ts region='pipe'}
*/
export var Pipe: PipeFactory = <PipeFactory>makeDecorator(PipeMetadata);
modules/angular2/src/core/metadata/di.ts
+1 -10
View File
@@ -17,16 +17,7 @@ import {DependencyMetadata} from 'angular2/src/core/di/metadata';
*
* A decorator can inject string literal `text` like so:
*
* ```javascript
* @Directive({
* selector: `input'
* })
* class InputDirective {
* constructor(@Attribute('type') type) {
* // type would be `text` in this example
* }
* }
* ```
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
*/
@CONST()
export class AttributeMetadata extends DependencyMetadata {
modules/angular2/src/core/metadata/directives.ts
+2 -20
View File
@@ -804,20 +804,7 @@ export class DirectiveMetadata extends InjectableMetadata {
*
* ### Example
*
* ```
* @Component({
* selector: 'greet',
* template: 'Hello {{name}}!'
* })
* class Greet {
* name: string;
*
* constructor() {
* this.name = 'World';
* }
* }
* ```
*
* {@example core/ts/metadata/metadata.ts region='component'}
*/
@CONST()
export class ComponentMetadata extends DirectiveMetadata {
@@ -954,12 +941,7 @@ export class ComponentMetadata extends DirectiveMetadata {
*
* ### Example
*
* ```
* @Pipe({name: 'lowercase'})
* class Lowercase {
* transform(v, args) { return v.toLowerCase(); }
* }
* ```
* {@example core/ts/metadata/metadata.ts region='pipe'}
*/
@CONST()
export class PipeMetadata extends InjectableMetadata {
modules/angular2/src/platform/dom/debug/debug_element_view_listener.ts
+5
View File
@@ -33,6 +33,11 @@ function _getElementId(element): number[] {
}
}
/**
* Returns a {@link DebugElement} for the given native DOM element, or
* null if the given native element does not have an Angular view associated
* with it.
*/
export function inspectNativeElement(element): DebugElement {
var elId = _getElementId(element);
if (isPresent(elId)) {
modules/angular2/src/testing/testing.ts
+67 -34
View File
@@ -20,27 +20,54 @@ export {expect, NgMatchers} from './matchers';
var _global: jasmine.GlobalPolluter = <any>(typeof window === 'undefined' ? global : window);
/**
* See http://jasmine.github.io/
* Run a function (with an optional asynchronous callback) after each test case.
*
* See http://jasmine.github.io/ for more details.
*
* ## Example:
*
* {@example testing/ts/testing.ts region='afterEach'}
*/
export var afterEach: Function = _global.afterEach;
/**
* See http://jasmine.github.io/
* Group test cases together under a common description prefix.
*
* See http://jasmine.github.io/ for more details.
*
* ## Example:
*
* {@example testing/ts/testing.ts region='describeIt'}
*/
export var describe: Function = _global.describe;
/**
* See http://jasmine.github.io/
* See {@link fdescribe}.
*/
export var ddescribe: Function = _global.fdescribe;
/**
* See http://jasmine.github.io/
* Like {@link describe}, but instructs the test runner to only run
* the test cases in this group. This is useful for debugging.
*
* See http://jasmine.github.io/ for more details.
*
* ## Example:
*
* {@example testing/ts/testing.ts region='fdescribe'}
*/
export var fdescribe: Function = _global.fdescribe;
/**
* See http://jasmine.github.io/
* Like {@link describe}, but instructs the test runner to exclude
* this group of test cases from execution. This is useful for
* debugging, or for excluding broken tests until they can be fixed.
*
* See http://jasmine.github.io/ for more details.
*
* ## Example:
*
* {@example testing/ts/testing.ts region='xdescribe'}
*/
export var xdescribe: Function = _global.xdescribe;
@@ -68,14 +95,9 @@ jsmBeforeEach(() => {
*
* The given function must return a list of DI providers.
*
* Example:
* ## Example:
*
* ```
* beforeEachProviders(() => [
* bind(Compiler).toClass(MockCompiler),
* bind(SomeToken).toValue(myValue),
* ]);
* ```
* {@example testing/ts/testing.ts region='beforeEachProviders'}
*/
export function beforeEachProviders(fn): void {
jsmBeforeEach(() => {
@@ -171,11 +193,16 @@ function _it(jsmFn: Function, name: string, testFn: FunctionWithParamTokens | An
/**
* Wrapper around Jasmine beforeEach function.
* See http://jasmine.github.io/
*
* beforeEach may be used with the `inject` function to fetch dependencies.
* The test will automatically wait for any asynchronous calls inside the
* injected test function to complete.
*
* See http://jasmine.github.io/ for more details.
*
* ## Example:
*
* {@example testing/ts/testing.ts region='beforeEach'}
*/
export function beforeEach(fn: FunctionWithParamTokens | AnyTestFn): void {
if (fn instanceof FunctionWithParamTokens) {
@@ -200,12 +227,18 @@ export function beforeEach(fn: FunctionWithParamTokens | AnyTestFn): void {
}
/**
* Wrapper around Jasmine it function.
* See http://jasmine.github.io/
* Define a single test case with the given test name and execution function.
*
* it may be used with the `inject` function to fetch dependencies.
* The test will automatically wait for any asynchronous calls inside the
* injected test function to complete.
* The test function can be either a synchronous function, an asynchronous function
* that takes a completion callback, or an injected function created via {@link inject}
* or {@link injectAsync}. The test will automatically wait for any asynchronous calls
* inside the injected test function to complete.
*
* Wrapper around Jasmine it function. See http://jasmine.github.io/ for more details.
*
* ## Example:
*
* {@example testing/ts/testing.ts region='it'}
*/
export function it(name: string, fn: FunctionWithParamTokens | AnyTestFn,
timeOut: number = null): void {
@@ -213,12 +246,15 @@ export function it(name: string, fn: FunctionWithParamTokens | AnyTestFn,
}
/**
* Wrapper around Jasmine xit (skipped it) function.
* See http://jasmine.github.io/
* Like {@link it}, but instructs the test runner to exclude this test
* entirely. Useful for debugging or for excluding broken tests until
* they can be fixed.
*
* it may be used with the `inject` function to fetch dependencies.
* The test will automatically wait for any asynchronous calls inside the
* injected test function to complete.
* Wrapper around Jasmine xit function. See http://jasmine.github.io/ for more details.
*
* ## Example:
*
* {@example testing/ts/testing.ts region='xit'}
*/
export function xit(name: string, fn: FunctionWithParamTokens | AnyTestFn,
timeOut: number = null): void {
@@ -226,12 +262,7 @@ export function xit(name: string, fn: FunctionWithParamTokens | AnyTestFn,
}
/**
* Wrapper around Jasmine iit (focused it) function.
* See http://jasmine.github.io/
*
* it may be used with the `inject` function to fetch dependencies.
* The test will automatically wait for any asynchronous calls inside the
* injected test function to complete.
* See {@link fit}.
*/
export function iit(name: string, fn: FunctionWithParamTokens | AnyTestFn,
timeOut: number = null): void {
@@ -239,12 +270,14 @@ export function iit(name: string, fn: FunctionWithParamTokens | AnyTestFn,
}
/**
* Wrapper around Jasmine fit (focused it) function.
* See http://jasmine.github.io/
* Like {@link it}, but instructs the test runner to only run this test.
* Useful for debugging.
*
* it may be used with the `inject` function to fetch dependencies.
* The test will automatically wait for any asynchronous calls inside the
* injected test function to complete.
* Wrapper around Jasmine fit function. See http://jasmine.github.io/ for more details.
*
* ## Example:
*
* {@example testing/ts/testing.ts region='fit'}
*/
export function fit(name: string, fn: FunctionWithParamTokens | AnyTestFn,
timeOut: number = null): void {