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

docs(di): Edits to DI. 

Closes #1420
This commit is contained in:
Naomi Black 2015-04-17 03:29:05 -07:00 committed by Misko Hevery
parent 97220dd2ba
commit de31aca7a7
13 changed files with 113 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
modules/angular2/di.js vendored
View File

@ -2,7 +2,7 @@
* @module
* @public
* @description
* This is a description
* The `di` module provides dependency injection container services.
*/
export {Inject, InjectPromise, InjectLazy, Injectable, Optional, DependencyAnnotation} from './src/di/annotations';

2
modules/angular2/di_annotations.js vendored
View File

@ -2,6 +2,6 @@
* @module
* @public
* @description
* This is a description
* Annotations which controll how the dependencies are resolved by the [Injector].
*/

2
modules/angular2/di_errors.js vendored
View File

@ -2,6 +2,6 @@
* @module
* @public
* @description
* This is a description
* Errors thrown by the [Injector].
*/

2
modules/angular2/directives.js vendored
View File

@ -2,7 +2,7 @@
* @module
* @public
* @description
* Describe the directives module here
* Common directives shipped with Angualr.
*/
export * from './src/directives/class';

2
modules/angular2/src/core/compiler/compiler.js vendored
View File

@ -41,7 +41,7 @@ export class CompilerCache {
}
/**
* @exportedAs angular2/template
* @exportedAs angular2/view
*/
@Injectable()
export class Compiler {

2
modules/angular2/src/core/compiler/view_container.js vendored
View File

@ -11,7 +11,7 @@ import * as vhModule from './view_hydrator';
import {Renderer} from 'angular2/src/render/api';
/**
* @exportedAs angular2/template
* @exportedAs angular2/view
*/
export class ViewContainer {
viewFactory: vfModule.ViewFactory;

15
modules/angular2/src/di/annotations.js vendored
View File

@ -1,7 +1,7 @@
import {CONST} from "angular2/src/facade/lang";
/**
* A parameter annotation that creates a synchronous eager dependency.
* A parameter annotation that specifies a dependency.
*
* ```
* class AComponent {
@ -20,7 +20,7 @@ export class Inject {
}
/**
* A parameter annotation that creates an asynchronous eager dependency.
* A parameter annotation that specifies a [Promise] of a dependency.
*
* ```
* class AComponent {
@ -62,7 +62,9 @@ export class InjectLazy {
}
/**
* A parameter annotation that marks a dependency as optional. (Injects `null` if not found.)
* A parameter annotation that marks a dependency as optional. [Injector] provides `null` if the dependency is not
* found.
*
* ```
* class AComponent {
* constructor(@Optional() aService:MyService) {
@ -82,8 +84,7 @@ export class Optional {
/**
* `DependencyAnnotation` is used by the framework to extend DI.
*
* Only annotations implementing `DependencyAnnotation` will be added
* to the list of dependency properties.
* Only annotations implementing `DependencyAnnotation` are added to the list of dependency properties.
*
* For example:
*
@ -118,8 +119,8 @@ export class DependencyAnnotation {
}
/**
* A marker annotation that marks a class as available to `Injector`s for creation. Used by tooling for generating
* constructor stubs.
* A marker annotation that marks a class as available to `Injector` for creation. Used by tooling for
* generating constructor stubs.
*
* ```
* class NeedsService {

84
modules/angular2/src/di/binding.js vendored
View File

@ -50,16 +50,16 @@ var _EMPTY_LIST = []; // TODO: make const when supported
export class Binding {
/**
* Token used when retriving this binding. Usually the [Type].
* Token used when retrieving this binding. Usually the [Type].
*/
token;
/**
* Bind an interface to an implementation / subclass.
* Binds an interface to an implementation / subclass.
*
* ## Example
*
* Becuse `toAlias` and `toClass` are often confused the example contains both use cases for easy comparison.
* Becuse `toAlias` and `toClass` are often confused, the example contains both use cases for easy comparison.
*
* ```javascript
*
@ -86,7 +86,7 @@ export class Binding {
toClass:Type;
/**
* Bind a key to a value.
* Binds a key to a value.
*
* ## Example
*
@ -101,10 +101,10 @@ export class Binding {
toValue;
/**
* Bind a key to an alias of an existing key.
* Binds a key to the alias for an existing key.
*
* An alias means that we will return the same instance as if the alias token was used. (This is in contrast to
* `toClass` where a separet instance of `toClass` will be returned.)
* An alias means that [Injector] returns the same instance as if the alias token was used. This is in contrast to
* `toClass` where a separate instance of `toClass` is returned.
*
* ## Example
*
@ -127,7 +127,7 @@ export class Binding {
*
* expect(injectorAlias.get(Vehicle)).toBe(injectorAlias.get(Car));
* expect(injectorAlias.get(Vehicle) instanceof Car).toBe(true);
*
* expect(injectorClass.get(Vehicle)).not.toBe(injectorClass.get(Car));
* expect(injectorClass.get(Vehicle) instanceof Car).toBe(true);
* ```
@ -135,7 +135,7 @@ export class Binding {
toAlias;
/**
* Bind a key to a function which computes the value.
* Binds a key to a function which computes the value.
*
* ## Example
*
@ -153,7 +153,7 @@ export class Binding {
toFactory:Function;
/**
* Bind a key to a function which computes the value asynchronously.
* Binds a key to a function which computes the value asynchronously.
*
* ## Example
*
@ -170,15 +170,17 @@ export class Binding {
* injector.asyncGet(String).then((v) => expect(v).toBe('Value: 3'));
* ```
*
* The interesting thing to note is that event thougt `Numeber` has an async factory, the `String` factory
* function takes the resolved value. This shows that the [Injector] delays executing of the `String` factory
* until after the `Number` is resolved. This can only be done if the `token` is retrive
* The interesting thing to note is that event though `Number` has an async factory, the `String` factory
* function takes the resolved value. This shows that the [Injector] delays executing the `String` factory
* until after the `Number` is resolved. This can only be done if the `token` is retrieved using the
* [Injector.asyncGet] API.
*
*/
toAsyncFactory:Function;
/**
* Used in conjunction with `toFactory` or `toAsyncFactory` and specifies the `token`s which should be injected
* into the factory function.
* Used in conjunction with `toFactory` or `toAsyncFactory` and specifies a set of dependencies (as `token`s) which
* should be injected into the factory function.
*
* ## Example
*
@ -216,7 +218,9 @@ export class Binding {
}
/**
*
* Converts the [Binding] into [ResolvedBinding].
*
* [Injector] internaly only uses [ResolvedBindings], [Binding] contains convenience sugar.
*/
resolve(): ResolvedBinding {
var factoryFn:Function;
@ -250,29 +254,31 @@ export class Binding {
}
/**
* An internal resolved representaion of a [Binding] used by [Injector].
*
* A [Binding] is resolved when it has a factory fonction. Binding to a class, alias, or value, are just convenience
* methods, as [Injector] only operates on calling factory functions.
* An internal resolved representation of a [Binding] used by the [Injector].
*
* A [Binding] is resolved when it has a factory function. Binding to a class, alias, or value, are just convenience
* methods, as [Injector] only operates on calling factory functions.
*
* @exportedAs angular2/di
*/
export class ResolvedBinding {
/**
* A key, usually a [Type].
*/
key:Key;
/**
* Factory function which can return an instance of [key].
* Factory function which can return an instance of represented by a [key].
*/
factory:Function;
/**
* Arguments (dependencies) to the [factory] function.
*/
dependencies:List<Dependency>;
/**
* Specifies if the [factory] function returns an [Promise]
* Specifies whether the [factory] function returns a [Promise].
*/
providedAsPromise:boolean;
@ -285,7 +291,9 @@ export class ResolvedBinding {
}
/**
* Provides fluent API for imperative construction of [Binding] objects. (JavaScript only.)
* Provides an API for imperatively constructing [Binding]s.
*
* This is only relevant for JavaScript.
*
* @exportedAs angular2/di
*/
@ -294,7 +302,8 @@ export function bind(token):BindingBuilder {
}
/**
* Helper class for [bind] function.
* Helper class for the [bind] function.
*
* @exportedAs angular2/di
*/
export class BindingBuilder {
@ -305,11 +314,11 @@ export class BindingBuilder {
}
/**
* Bind an interface to an implementation / subclass.
* Binds an interface to an implementation / subclass.
*
* ## Example
*
* Becuse `toAlias` and `toClass` are often confused the example contains both use cases for easy comparison.
* Because `toAlias` and `toClass` are often confused, the example contains both use cases for easy comparison.
*
* ```javascript
*
@ -338,7 +347,7 @@ export class BindingBuilder {
}
/**
* Bind a key to a value.
* Binds a key to a value.
*
* ## Example
*
@ -355,14 +364,14 @@ export class BindingBuilder {
}
/**
* Bind a key to an alias of an existing key.
* Binds a key to the alias for an existing key.
*
* An alias means that we will return the same instance as if the alias token was used. (This is in contrast to
* `toClass` where a separet instance of `toClass` will be returned.)
*
* ## Example
*
* Becuse `toAlias` and `toClass` are often confused the example contains both use cases for easy comparison.
* Becuse `toAlias` and `toClass` are often confused, the example contains both use cases for easy comparison.
*
* ```javascript
*
@ -381,7 +390,7 @@ export class BindingBuilder {
*
* expect(injectorAlias.get(Vehicle)).toBe(injectorAlias.get(Car));
* expect(injectorAlias.get(Vehicle) instanceof Car).toBe(true);
*
* expect(injectorClass.get(Vehicle)).not.toBe(injectorClass.get(Car));
* expect(injectorClass.get(Vehicle) instanceof Car).toBe(true);
* ```
@ -391,7 +400,7 @@ export class BindingBuilder {
}
/**
* Bind a key to a function which computes the value.
* Binds a key to a function which computes the value.
*
* ## Example
*
@ -413,7 +422,7 @@ export class BindingBuilder {
}
/**
* Bind a key to a function which computes the value asynchronously.
* Binds a key to a function which computes the value asynchronously.
*
* ## Example
*
@ -429,9 +438,10 @@ export class BindingBuilder {
* injector.asyncGet(String).then((v) => expect(v).toBe('Value: 3'));
* ```
*
* The interesting thing to note is that event thougt `Numeber` has an async factory, the `String` factory
* The interesting thing to note is that event though `Number` has an async factory, the `String` factory
* function takes the resolved value. This shows that the [Injector] delays executing of the `String` factory
* until after the `Number` is resolved. This can only be done if the `token` is retrive
* until after the `Number` is resolved. This can only be done if the `token` is retrieved using the
* [Injector.asyncGet] API.
*/
toAsyncFactory(factoryFunction:Function, dependencies:List = null):Binding {
return new Binding(this.token, {

28
modules/angular2/src/di/exceptions.js vendored
View File

@ -26,7 +26,7 @@ function constructResolvingPath(keys:List) {
/**
* Base class for all errors arising from missconfigured bindings.
* Base class for all errors arising from misconfigured bindings.
*
* @exportedAs angular2/di_errors
*/
@ -54,8 +54,8 @@ export class ProviderError extends Error {
}
/**
* Thrown when trying to retrieve a dependency by [Key] from [Injector], but [Injector] does not have a [Binding] for
* said [Key].
* Thrown when trying to retrieve a dependency by [Key] from [Injector], but the [Injector] does not have a [Binding]
* for [Key].
*
* @exportedAs angular2/di_errors
*/
@ -70,7 +70,7 @@ export class NoProviderError extends ProviderError {
}
/**
* Throw when trying to retrieve async [Binding] using sync API.
* Thrown when trying to retrieve an async [Binding] using the sync API.
*
* ## Example
*
@ -88,8 +88,8 @@ export class NoProviderError extends ProviderError {
* }).toThrowError(AsycBindingError);
* ```
*
* The above example throws because `String` dependes no `Numeber` which is async. If any binding in the dependency
* graph is async then the graph can only be retrieved using `asyncGet` API.
* The above example throws because `String` depends on `Number` which is async. If any binding in the dependency
* graph is async then the graph can only be retrieved using the `asyncGet` API.
*
* @exportedAs angular2/di_errors
*/
@ -105,7 +105,7 @@ export class AsyncBindingError extends ProviderError {
}
/**
* Throw when dependencies from a cyle.
* Thrown when dependencies form a cycle.
*
* ## Example:
*
@ -118,7 +118,7 @@ export class AsyncBindingError extends ProviderError {
* }
* ```
*
* Retrieving `A` or `B` will throw `CyclicDependencyError` as such a graph can not be constructed.
* Retrieving `A` or `B` throws a `CyclicDependencyError` as the graph above cannot be constructed.
*
* @exportedAs angular2/di_errors
*/
@ -132,9 +132,9 @@ export class CyclicDependencyError extends ProviderError {
}
/**
* Thrown when constructing type returns with an Error.
* Thrown when a constructing type returns with an Error.
*
* The `InstantiationError` class contains the original error plus dependency graph which caused this object to be
* The `InstantiationError` class contains the original error plus the dependency graph which caused this object to be
* instantiated.
*
* @exportedAs angular2/di_errors
@ -151,7 +151,7 @@ export class InstantiationError extends ProviderError {
}
/**
* Thrown when object other then [Binding] (or [Type]) is passed to [Injector] creation.
* Thrown when an object other then [Binding] (or [Type]) is passed to [Injector] creation.
*
* @exportedAs angular2/di_errors
*/
@ -168,10 +168,10 @@ export class InvalidBindingError extends Error {
}
/**
* Thrown when the class as no annotation information.
* Thrown when the class has no annotation information.
*
* Lack of annotation prevents the [Injector] from determininig what dependencies need to be injected int the
* constructor.
* Lack of annotation information prevents the [Injector] from determining which dependencies need to be injected into
* the constructor.
*
* @exportedAs angular2/di_errors
*/

59
modules/angular2/src/di/injector.js vendored
View File

@ -28,7 +28,7 @@ function _isWaiting(obj):boolean {
* `Injector`.
*
* ## Example:
*
*
* Suppose that we want to inject an `Engine` into class `Car`, we would define it like this:
*
* ```javascript
@ -41,9 +41,9 @@ function _isWaiting(obj):boolean {
* }
*
* ```
*
* Next we need to write the code that creates and instantiates the `Injector`. We then ask for the `root` object,
* `Car`, so that the `Injector` can recursively build all of that object's dependencies.
*
* Next we need to write the code that creates and instantiates the `Injector`. We then ask for the `root` object,
* `Car`, so that the `Injector` can recursively build all of that object's dependencies.
*
* ```javascript
* main() {
@ -53,7 +53,7 @@ function _isWaiting(obj):boolean {
* var car = injector.get(Car);
* }
* ```
* Notice that we don't use the `new` operator because we explicitly want to have the `Injector` resolve all of the
* Notice that we don't use the `new` operator because we explicitly want to have the `Injector` resolve all of the
* object's dependencies automatically.
*
* @exportedAs angular2/di
@ -67,11 +67,12 @@ export class Injector {
_syncStrategy:_SyncInjectorStrategy;
/**
* Turns a list of binding definitions into internal resolved list of resolved bindings.
* Turns a list of binding definitions into an internal resolved list of resolved bindings.
*
* A resolution is a process of flattening multiple nested lists and converting individual bindings into a
* list of [ResolvedBinding]s. The resolution can be cached by [Injector.resolve] for performance-sensitive
* code.
*
* A resolution is a process of flattening multiple nested lists and converting individual bindings into a
* list of [ResolvedBinding]s. The resolution can be cached for performance sensitive code.
*
* @param [bindings] can be a list of [Type], [Binding], [ResolvedBinding], or a recursive list of more bindings.
*
* The returned list is sparse, indexed by [Key.id]. It is generally not useful to application code other than for
@ -87,7 +88,7 @@ export class Injector {
/**
* Resolves bindings and creates an injector based on those bindings. This function is slower than the
* corresponding [fromResolvedBindings] because it needs to resolve bindings first. See [Injector.resolve].
*
*
* Prefer [fromResolvedBindings] in performance-critical code that creates lots of injectors.
*
* @param [bindings] can be a list of [Type], [Binding], [ResolvedBinding], or a recursive list of more bindings.
@ -98,7 +99,7 @@ export class Injector {
}
/**
* Creates an injector from previously resolved bindings. This bypasses resolution and flattening. This API is
* Creates an injector from previously resolved bindings. This bypasses resolution and flattening. This API is the
* recommended way to construct injectors in performance-sensitive parts.
*
* @param [bindings] A sparse list of [ResolvedBinding]s. See [Injector.resolve].
@ -123,21 +124,21 @@ export class Injector {
}
/**
* Used to retrieve an instance from the injector.
*
* @param [token] usually the [Type] of object. (Same as token used while setting up a binding).
* Retrieves an instance from the injector.
*
* @param [token] usually the [Type] of an object. (Same as the token used while setting up a binding).
* @returns an instance represented by the token. Throws if not found.
*/
get(token) {
return this._getByKey(Key.get(token), false, false, false);
}
/**
* Used to retrieve an instance from the injector.
*
* @param [token] usually the [Type] of object. (Same as token used while setting up a binding).
* Retrieves an instance from the injector.
*
* @param [token] usually a [Type]. (Same as the token used while setting up a binding).
* @returns an instance represented by the token. Returns `null` if not found.
*/
getOptional(token) {
@ -145,9 +146,9 @@ export class Injector {
}
/**
* Used to retrieve an instance from the injector asynchronously. Used with asynchronous bindings.
*
* @param [token] usually the [Type] of object. (Same as token used while setting up a binding).
* Retrieves an instance from the injector asynchronously. Used with asynchronous bindings.
*
* @param [token] usually a [Type]. (Same as token used while setting up a binding).
* @returns a [Promise] which resolves to the instance represented by the token.
*/
asyncGet(token):Promise {
@ -155,14 +156,14 @@ export class Injector {
}
/**
* Create a child injector and load a new set of bindings into it.
*
* A resolution is a process of flattening multiple nested and converting individual bindings into a
* list of [ResolvedBinding]s. The resolution can be cached [Injector.resolve] for performance sensitive
* Creates a child injector and loads a new set of bindings into it.
*
* A resolution is a process of flattening multiple nested lists and converting individual bindings into a
* list of [ResolvedBinding]s. The resolution can be cached by [Injector.resolve] for performance-sensitive
* code.
*
*
* See: [Injector.resolve].
*
*
* @param [bindings] can be a list of [Type], [Binding], [ResolvedBinding], or a recursive list of more bindings.
* @returns a new child `Injector`.
*/
@ -171,8 +172,8 @@ export class Injector {
}
/**
* Create a child injector and load a new set of [ResolvedBinding] into it.
*
* Creates a child injector and loads a new set of [ResolvedBinding]s into it.
*
* @param [bindings] A sparse list of [ResolvedBinding]s. See [Injector.resolve].
* @returns a new child `Injector`.
*/

14
modules/angular2/src/di/key.js vendored
View File

@ -4,14 +4,14 @@ import {MapWrapper} from 'angular2/src/facade/collection';
// TODO: uncoment `int` once https://github.com/angular/angular/issues/1414 is fixed
/**
* A unique object used for retrieving items from the Injector.
* A unique object used for retrieving items from the [Injector].
*
* [Key]s have:
* - system wide unique [id].
* - [token] usually the [Type] of the instance.
* - a system-wide unique [id].
* - a [token], usually the [Type] of the instance.
*
* [Key]s are used internaly in [Injector] becouse they have system wide unique [id]s which allow the injector to
* index in arrays rather ther look up items in maps.
* [Key]s are used internally in [Injector]s because their system-wide unique [id]s allow the
* injector to index in arrays rather than looking up items in maps.
*
* @exportedAs angular2/di
*/
@ -26,14 +26,14 @@ export class Key {
}
/**
* Retrieve a [Key] for a token.
* Retrieves a [Key] for a token.
*/
static get(token):Key {
return _globalKeyRegistry.get(token);
}
/**
* @returns number of [Key]s registered in the system.
* @returns the number of [Key]s registered in the system.
*/
static get numberOfKeys()/* :int */ {
return _globalKeyRegistry.numberOfKeys;

6
modules/angular2/template.js vendored
View File

@ -1,6 +0,0 @@
/**
* @module
* @public
* @description
* Define public API for Angular here.
*/

2
modules/angular2/view.js vendored
View File

@ -2,5 +2,5 @@
* @module
* @public
* @description
* Define public API for Angular here.
* Provides API for working with Angular views.
*/