cargdev/angular
1
0
Fork 0
Code Issues 13 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(x-ref links): Change links to use dgeni syntax

Browse Source 
Closes #1440
This commit is contained in:
Naomi Black
2015-04-17 13:01:07 -07:00
committed by Misko Hevery
parent 64ad74acbe
commit 5c25248582
51 changed files with 259 additions and 249 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@ -20,7 +20,7 @@ export class Inject {
}
/**
* A parameter annotation that specifies a [Promise] of a dependency.
* A parameter annotation that specifies a `Promise` of a dependency.
*
* ```
* class AComponent {
@ -62,9 +62,9 @@ export class InjectLazy {
}
/**
* A parameter annotation that marks a dependency as optional. [Injector] provides `null` if the dependency is not
* A parameter annotation that marks a dependency as optional. {@link Injector} provides `null` if the dependency is not
* found.
*
*
* ```
* class AComponent {
* constructor(@Optional() aService:MyService) {

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

@ -31,9 +31,9 @@ export class Dependency {
var _EMPTY_LIST = []; // TODO: make const when supported
/**
* Describes how the [Injector] should instantiate a given token.
* Describes how the {@link Injector} should instantiate a given token.
*
* See [bind].
* See {@link bind}.
*
* ## Example
*
@ -50,7 +50,7 @@ var _EMPTY_LIST = []; // TODO: make const when supported
export class Binding {
/**
* Token used when retrieving this binding. Usually the [Type].
* Token used when retrieving this binding. Usually the `Type`.
*/
token;
@ -103,7 +103,7 @@ export class Binding {
/**
* Binds a key to the alias for an existing key.
*
* An alias means that [Injector] returns the same instance as if the alias token was used. This is in contrast to
* An alias means that {@link 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
@ -171,9 +171,9 @@ export class Binding {
* ```
*
* 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
* function takes the resolved value. This shows that the {@link 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.
* `asyncGet` API in the {@link Injector}.
*
*/
toAsyncFactory:Function;
@ -218,9 +218,9 @@ export class Binding {
}
/**
* Converts the [Binding] into [ResolvedBinding].
* Converts the {@link Binding} into {@link ResolvedBinding}.
*
* [Injector] internaly only uses [ResolvedBindings], [Binding] contains convenience sugar.
* {@link Injector} internally only uses {@link ResolvedBinding}, {@link Binding} contains convenience binding syntax.
*/
resolve(): ResolvedBinding {
var factoryFn:Function;
@ -254,31 +254,31 @@ export class Binding {
}
/**
* An internal resolved representation of a [Binding] used by the [Injector].
* An internal resolved representation of a {@link Binding} used by the {@link 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.
* A {@link Binding} is resolved when it has a factory function. Binding to a class, alias, or value, are just convenience
* methods, as {@link Injector} only operates on calling factory functions.
*
* @exportedAs angular2/di
*/
export class ResolvedBinding {
/**
* A key, usually a [Type].
* A key, usually a `Type`.
*/
key:Key;
/**
* Factory function which can return an instance of represented by a [key].
* Factory function which can return an instance of an object represented by a key.
*/
factory:Function;
/**
* Arguments (dependencies) to the [factory] function.
* Arguments (dependencies) to the `factory` function.
*/
dependencies:List<Dependency>;
/**
* Specifies whether the [factory] function returns a [Promise].
* Specifies whether the `factory` function returns a `Promise`.
*/
providedAsPromise:boolean;
@ -291,7 +291,7 @@ export class ResolvedBinding {
}
/**
* Provides an API for imperatively constructing [Binding]s.
* Provides an API for imperatively constructing {@link Binding}s.
*
* This is only relevant for JavaScript. See {@link BindingBuilder}.
*
@ -309,7 +309,7 @@ export function bind(token):BindingBuilder {
}
/**
* Helper class for the [bind] function.
* Helper class for the {@link bind} function.
*
* @exportedAs angular2/di
*/
@ -446,9 +446,9 @@ export class BindingBuilder {
* ```
*
* 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
* function takes the resolved value. This shows that the {@link Injector} delays executing of the `String` factory
* until after the `Number` is resolved. This can only be done if the `token` is retrieved using the
* [Injector.asyncGet] API.
* the `asyncGet` API in the {@link Injector}.
*/
toAsyncFactory(factoryFunction:Function, dependencies:List = null):Binding {
return new Binding(this.token, {

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

@ -54,8 +54,8 @@ export class AbstractBindingError extends Error {
}
/**
* Thrown when trying to retrieve a dependency by [Key] from [Injector], but the [Injector] does not have a [Binding]
* for [Key].
* Thrown when trying to retrieve a dependency by `Key` from {@link Injector}, but the {@link Injector} does not have a
* {@link Binding} for {@link Key}.
*
* @exportedAs angular2/di_errors
*/
@ -70,7 +70,7 @@ export class NoBindingError extends AbstractBindingError {
}
/**
* Thrown when trying to retrieve an async [Binding] using the sync API.
* Thrown when trying to retrieve an async {@link Binding} using the sync API.
*
* ## Example
*
@ -151,7 +151,7 @@ export class InstantiationError extends AbstractBindingError {
}
/**
* Thrown when an object other then [Binding] (or [Type]) is passed to [Injector] creation.
* Thrown when an object other then {@link Binding} (or `Type`) is passed to {@link Injector} creation.
*
* @exportedAs angular2/di_errors
*/
@ -170,7 +170,7 @@ export class InvalidBindingError extends Error {
/**
* Thrown when the class has no annotation information.
*
* Lack of annotation information prevents the [Injector] from determining which dependencies need to be injected into
* Lack of annotation information prevents the {@link Injector} from determining which dependencies need to be injected into
* the constructor.
*
* @exportedAs angular2/di_errors

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

@ -70,14 +70,15 @@ export class Injector {
* 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.
* list of {@link ResolvedBinding}s. The resolution can be cached by `resolve` for the {@link Injector} for
* performance-sensitive code.
*
* @param [bindings] can be a list of [Type], [Binding], [ResolvedBinding], or a recursive list of more bindings.
* @param `bindings` can be a list of `Type`, {@link Binding}, {@link 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
* passing it to [Injector] functions that require resolved binding lists, such as [fromResolvedBindings] and
* [createChildFromResolved].
* The returned list is sparse, indexed by `id` for the {@link Key}. It is generally not useful to application code
* other than for passing it to {@link Injector} functions that require resolved binding lists, such as
* `fromResolvedBindings` and `createChildFromResolved`.
*/
static resolve(bindings:List/*<ResolvedBinding|Binding|Type|List>*/):List<ResolvedBinding> {
var resolvedBindings = _resolveBindings(bindings);
@ -87,12 +88,14 @@ 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].
* corresponding `fromResolvedBindings` because it needs to resolve bindings first. See `resolve` for the
* {@link Injector}.
*
* Prefer [fromResolvedBindings] in performance-critical code that creates lots of injectors.
* 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.
* @param [defaultBindings] Setting to true will auto-create bindings.
* @param `bindings` can be a list of `Type`, {@link Binding}, {@link ResolvedBinding}, or a recursive list of more
* bindings.
* @param `defaultBindings` Setting to true will auto-create bindings.
*/
static resolveAndCreate(bindings:List/*<ResolvedBinding|Binding|Type|List>*/, {defaultBindings=false}={}) {
return new Injector(Injector.resolve(bindings), null, defaultBindings);
@ -102,17 +105,17 @@ export class Injector {
* 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].
* @param [defaultBindings] Setting to true will auto-create bindings.
* @param `bindings` A sparse list of {@link ResolvedBinding}s. See `resolve` for the {@link Injector}.
* @param `defaultBindings` Setting to true will auto-create bindings.
*/
static fromResolvedBindings(bindings:List<ResolvedBinding>, {defaultBindings=false}={}) {
return new Injector(bindings, null, defaultBindings);
}
/**
* @param [bindings] A sparse list of [ResolvedBinding]s. See [Injector.resolve].
* @param [parent] Parent Injector or `null` if root injector.
* @param [defaultBindings] Setting to true will auto-create bindings. (Only use with root injector.)
* @param `bindings` A sparse list of {@link ResolvedBinding}s. See `resolve` for the {@link Injector}.
* @param `parent` Parent Injector or `null` if root Injector.
* @param `defaultBindings` Setting to true will auto-create bindings. (Only use with root injector.)
*/
constructor(bindings:List<ResolvedBinding>, parent:Injector, defaultBindings:boolean) {
this._bindings = bindings;
@ -126,7 +129,7 @@ export class Injector {
/**
* Retrieves an instance from the injector.
*
* @param [token] usually the [Type] of an object. (Same as the token used while setting up a binding).
* @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) {
@ -138,7 +141,7 @@ export class Injector {
/**
* Retrieves an instance from the injector.
*
* @param [token] usually a [Type]. (Same as the token used while setting up a binding).
* @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) {
@ -148,8 +151,8 @@ export class Injector {
/**
* 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.
* @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 {
return this._getByKey(Key.get(token), true, false, false);
@ -159,23 +162,22 @@ export class Injector {
* 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.
* list of {@link ResolvedBinding}s. The resolution can be cached by `resolve` for the {@link Injector} for
* performance-sensitive code.
*
* See: [Injector.resolve].
* @param `bindings` can be a list of `Type`, {@link Binding}, {@link ResolvedBinding}, or a recursive
* list of more bindings.
*
* @param [bindings] can be a list of [Type], [Binding], [ResolvedBinding], or a recursive list of more bindings.
* @returns a new child `Injector`.
*/
resolveAndCreateChild(bindings:List/*<ResolvedBinding|Binding|Type|List>*/):Injector {
return new Injector(Injector.resolve(bindings), this, false);
}
/**
* Creates a child injector and loads a new set of [ResolvedBinding]s into it.
* Creates a child injector and loads a new set of {@link ResolvedBinding}s into it.
*
* @param [bindings] A sparse list of [ResolvedBinding]s. See [Injector.resolve].
* @returns a new child `Injector`.
* @param `bindings`: A sparse list of {@link ResolvedBinding}s. See `resolve` for the {@link Injector}.
* @returns a new child {@link Injector}.
*/
createChildFromResolved(bindings:List<ResolvedBinding>):Injector {
return new Injector(bindings, this, false);

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

@ -4,13 +4,13 @@ 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 {@link Injector}.
*
* [Key]s have:
* - a system-wide unique [id].
* - a [token], usually the [Type] of the instance.
* Keys have:
* - a system-wide unique `id`.
* - a `token`, usually the `Type` of the instance.
*
* [Key]s are used internally in [Injector]s because their system-wide unique [id]s allow the
* Keys are used internally by the {@link Injector} 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 {
}
/**
* Retrieves a [Key] for a token.
* Retrieves a `Key` for a token.
*/
static get(token):Key {
return _globalKeyRegistry.get(token);
}
/**
* @returns the number of [Key]s registered in the system.
* @returns the number of keys registered in the system.
*/
static get numberOfKeys()/* :int */ {
return _globalKeyRegistry.numberOfKeys;