cargdev/angular
1
0
Fork 0
Code Issues 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

91
modules/angular2/src/core/annotations/annotations.js vendored
View File

@ -8,32 +8,32 @@ import {DEFAULT} from 'angular2/change_detection';
/**
* Directives allow you to attach behavior to elements in the DOM.
*
* Directive is an abstract concept, instead use concrete directives: [Component], [DynamicComponent], [Decorator]
* or [Viewport].
* Directive is an abstract concept, instead use concrete directives: {@link Component}, {@link DynamicComponent}, {@link Decorator}
* or {@link Viewport}.
*
* A directive consists of a single directive annotation and a controller class. When the directive's [selector] matches
* A directive consists of a single directive annotation and a controller class. When the directive's `selector` matches
* elements in the DOM, the following steps occur:
*
* 1. For each directive, the [ElementInjector] attempts to resolve the directive's constructor arguments.
* 2. Angular instantiates directives for each matched element using [ElementInjector] in a depth-first order,
* 1. For each directive, the `ElementInjector` attempts to resolve the directive's constructor arguments.
* 2. Angular instantiates directives for each matched element using `ElementInjector` in a depth-first order,
* as declared in the HTML.
*
* ## Understanding How Injection Works
*
* There are three stages of injection resolution.
* - *Pre-existing Injectors*:
* - The terminal [Injector] cannot resolve dependencies. It either throws an error or, if the dependency was
* - The terminal {@link Injector} cannot resolve dependencies. It either throws an error or, if the dependency was
* specified as `@Optional`, returns `null`.
* - The platform injector resolves browser singleton resources, such as: cookies, title, location, and others.
* - *Component Injectors*: Each `@Component` has its own [Injector], and they follow the same parent-child hierarchy
* - *Component Injectors*: Each `@Component` has its own {@link Injector}, and they follow the same parent-child hierarchy
* as the components in the DOM.
* - *Element Injectors*: Each component has a Shadow DOM. Within the Shadow DOM each element has an [ElementInjector]
* - *Element Injectors*: Each component has a Shadow DOM. Within the Shadow DOM each element has an `ElementInjector`
* which follow the same parent-child hierarchy as the DOM elements themselves.
*
* When a template is instantiated, it also must instantiate the corresponding directives in a depth-first order. The
* current [ElementInjector] resolves the constructor dependencies for each directive.
* current `ElementInjector` resolves the constructor dependencies for each directive.
*
* Angular then resolves dependencies as follows, according to the order in which they appear in the [View]:
* Angular then resolves dependencies as follows, according to the order in which they appear in the {@link View}:
*
* 1. Dependencies on the current element
* 2. Dependencies on element injectors and their parents until it encounters a Shadow DOM boundary
@ -41,21 +41,21 @@ import {DEFAULT} from 'angular2/change_detection';
* 4. Dependencies on pre-existing injectors
*
*
* The [ElementInjector] can inject other directives, element-specific special objects, or it can delegate to the parent
* The `ElementInjector` can inject other directives, element-specific special objects, or it can delegate to the parent
* injector.
*
* To inject other directives, declare the constructor parameter as:
* - `directive:DirectiveType`: a directive on the current element only
* - `@Ancestor() directive:DirectiveType`: any directive that matches the type between the current element and the
* Shadow DOM root. Current element is not included in the resolution, therefor even if it could resolve it, it will
* Shadow DOM root. Current element is not included in the resolution, therefore even if it could resolve it, it will
* be ignored.
* - `@Parent() directive:DirectiveType`: any directive that matches the type on a direct parent element only.
* - `@Children query:Query<DirectiveType>`: A live collection of direct child directives [TO BE IMPLEMENTED].
* - `@Descendants query:Query<DirectiveType>`: A live collection of any child directives [TO BE IMPLEMENTED].
* - `@Children query:Query<DirectiveType>`: A live collection of direct child directives (will be implemented in later release).
* - `@Descendants query:Query<DirectiveType>`: A live collection of any child directives (will be implemented in later relaese).
*
* To inject element-specific special objects, declare the constructor parameter as:
* - `element: NgElement` to obtain a DOM element (DEPRECATED: replacement coming)
* - `viewContainer: ViewContainer` to control child template instantiation, for [Viewport] directives only
* - `viewContainer: ViewContainer` to control child template instantiation, for {@link Viewport} directives only
* - `bindingPropagation: BindingPropagation` to control change detection in a more granular way.
*
* ## Example
@ -184,32 +184,35 @@ import {DEFAULT} from 'angular2/change_detection';
* `dependency="1"`.
*
*
* ### Injecting a live collection of direct child directives [PENDING IMPLEMENTATION]
* ### Injecting a live collection of direct child directives
*
*
* A directive can also query for other child directives. Since parent directives are instantiated before child
* directives, a directive can't simply inject the list of child directives. Instead, the directive asynchronously
* injects a [Query], which updates as children are added, removed, or moved by any [ViewPort] directive such as a
* `for`, an `if`, or a `switch`.
* directives, a directive can't simply inject the list of child directives. Instead, the directive
* injects a {@link QueryList}, which updates its contents as children are added, removed, or moved by any
* {@link Viewport} directive such as a `for`, an `if`, or a `switch`.
*
* ```
* @Decorator({ selector: '[my-directive]' })
* class MyDirective {
* constructor(@Children() dependencies:Query<Maker>) {
* constructor(@Query(Marker) dependencies:QueryList<Maker>) {
* }
* }
* ```
*
* This directive would be instantiated with a [Query] which contains `Dependency` 4 and 6. Here, `Dependency` 5 would
* not be included, because it is not a direct child.
* This directive would be instantiated with a {@link QueryList} which contains `Dependency` 4 and 6. Here, `Dependency`
* 5 would not be included, because it is not a direct child.
*
* ### Injecting a live collection of direct descendant directives [PENDING IMPLEMENTATION]
* ### Injecting a live collection of descendant directives
*
* Note: This is will be implemented in later release. ()
*
* Similar to `@Children` above, but also includes the children of the child elements.
*
* ```
* @Decorator({ selector: '[my-directive]' })
* class MyDirective {
* constructor(@Children() dependencies:Query<Maker>) {
* constructor(@QueryDescendents(Marker) dependencies:QueryList<Maker>) {
* }
* }
* ```
@ -279,7 +282,7 @@ export class Directive extends Injectable {
* - `directiveProperty` specifies the component property where the value is written.
* - `bindingProperty` specifies the DOM property where the value is read from.
*
* You can include [Pipes] when specifying a `bindingProperty` to allow for data transformation and structural
* You can include a {@link Pipe} when specifying a `bindingProperty` to allow for data transformation and structural
* change detection of the value. These pipes will be evaluated in the context of this component.
*
*
@ -333,7 +336,9 @@ export class Directive extends Injectable {
* You can also use pipes when writing binding definitions for a directive.
*
* For example, we could write a binding that updates the directive on structural changes, rather than on reference
* changes, as normally occurs in change detection. (See: [Pipe] and [keyValueDiff] documentation for more details.)
* changes, as normally occurs in change detection.
*
* See {@link Pipe} and {@link keyValDiff} documentation for more details.
*
* ```
* @Decorator({
@ -399,7 +404,7 @@ export class Directive extends Injectable {
* When writing a directive event binding, you can also refer to the following local variables:
* - `$event`: Current event object which triggered the event.
* - `$target`: The source of the event. This will be either a DOM element or an Angular directive.
* [TO BE IMPLEMENTED]
* (will be implemented in later release)
*
*
* ## Syntax
@ -443,7 +448,7 @@ export class Directive extends Injectable {
/**
* Specifies a set of lifecycle hostListeners in which the directive participates.
*
* See: [onChange], [onDestroy], [onAllChangesDone] for details.
* See {@link onChange}, {@link onDestroy}, {@link onAllChangesDone} for details.
*/
lifecycle:List; //List<LifecycleEvent>
@ -471,9 +476,9 @@ export class Directive extends Injectable {
}
/**
* Returns true if a directive participates in a given [LifecycleEvent].
* Returns true if a directive participates in a given `LifecycleEvent`.
*
* See: [onChange], [onDestroy], [onAllChangesDone] for details.
* See {@link onChange}, {@link onDestroy}, {@link onAllChangesDone} for details.
*/
hasLifecycleHook(hook:string):boolean {
return isPresent(this.lifecycle) ? ListWrapper.contains(this.lifecycle, hook) : false;
@ -489,11 +494,11 @@ export class Directive extends Injectable {
* When a component is instantiated, Angular
* - creates a shadow DOM for the component.
* - loads the selected template into the shadow DOM.
* - creates a child [Injector] which is configured with the [Component.injectables].
* - creates a child {@link Injector} which is configured with the `injectables` for the {@link Component}.
*
* All template expressions and statements are then evaluated against the component instance.
*
* For details on the `@View` annotation, see [View].
* For details on the `@View` annotation, see {@link View}.
*
* ## Example
*
@ -530,17 +535,17 @@ export class Component extends Directive {
/**
* Defines the set of injectable objects that are visible to a Component and its children.
*
* The [injectables] defined in the Component annotation allow you to configure a set of bindings for the component's
* The `injectables` defined in the Component annotation allow you to configure a set of bindings for the component's
* injector.
*
* When a component is instantiated, Angular creates a new child Injector, which is configured with the bindings in
* the Component [injectables] annotation. The injectable objects then become available for injection to the component
* the Component `injectables` annotation. The injectable objects then become available for injection to the component
* itself and any of the directives in the component's template, i.e. they are not available to the directives which
* are children in the component's light DOM.
*
*
* The syntax for configuring the [injectables] injectable is identical to [Injector] injectable configuration. See
* [Injector] for additional detail.
* The syntax for configuring the `injectables` injectable is identical to {@link Injector} injectable configuration.
* See {@link Injector} for additional detail.
*
*
* ## Simple Example
@ -656,7 +661,7 @@ export class Component extends Directive {
*/
export class DynamicComponent extends Directive {
/**
* Same as [Component.injectables].
* Same as `injectables` in the {@link Component}.
*/
// TODO(vsankin): Please extract into AbstractComponent
injectables:any; //List;
@ -696,10 +701,10 @@ export class DynamicComponent extends Directive {
* (see: http://en.wikipedia.org/wiki/Composition_over_inheritance)
*
* Decorators:
* - are simplest form of [Directive]s.
* - are simplest form of {@link Directive}s.
* - are best used as a composition pattern ()
*
* Decorators differ from [Component]s in that they:
* Decorators differ from {@link Component}s in that they:
* - can have multiple decorators per element
* - do not create their own evaluation context
* - do not have a template (and therefor do not create Shadow DOM)
@ -788,11 +793,11 @@ export class Decorator extends Directive {
/**
* Directive that controls the instantiation, destruction, and positioning of inline template elements.
*
* A viewport directive uses a [ViewContainer] to instantiate, insert, move, and destroy views at runtime.
* The [ViewContainer] is created as a result of `<template>` element, and represents a location in the current view
* A viewport directive uses a {@link ViewContainer} to instantiate, insert, move, and destroy views at runtime.
* The {@link ViewContainer} is created as a result of `<template>` element, and represents a location in the current view
* where these actions are performed.
*
* Views are always created as children of the current [View], and as siblings of the `<template>` element. Thus a
* Views are always created as children of the current {@link View}, and as siblings of the `<template>` element. Thus a
* directive in a child view cannot inject the viewport directive that created it.
*
* Since viewport directives are common in Angular, and using the full `<template>` element syntax is wordy, Angular
@ -906,7 +911,7 @@ export class Viewport extends Directive {
//TODO(misko): turn into LifecycleEvent class once we switch to TypeScript;
/**
* Notify a directive whenever a [View] that contains it is destroyed.
* Notify a directive whenever a {@link View} that contains it is destroyed.
*
* ## Example
*

4
modules/angular2/src/core/annotations/di.js vendored
View File

@ -69,9 +69,9 @@ export class Attribute extends DependencyAnnotation {
}
/**
* Specifies that a [QueryList] should be injected.
* Specifies that a {@link QueryList} should be injected.
*
* See: [QueryList] for usage and example.
* See {@link QueryList} for usage and example.
*
* @exportedAs angular2/annotations
*/

10
modules/angular2/src/core/annotations/view.js vendored
View File

@ -1,7 +1,7 @@
import {ABSTRACT, CONST, Type} from 'angular2/src/facade/lang';
/**
* Declare the available HTML templates for an application.
* Declares the available HTML templates for an application.
*
* 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.
@ -9,7 +9,7 @@ import {ABSTRACT, CONST, Type} from 'angular2/src/facade/lang';
* 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 [Component].
* For details on the `@Component` annotation, see {@link Component}.
*
* ## Example
*
@ -34,21 +34,21 @@ import {ABSTRACT, CONST, Type} from 'angular2/src/facade/lang';
*/
export class View {
/**
* Specify a template URL for an angular component.
* Specifies a template URL for an angular component.
*
* NOTE: either `templateURL` or `template` should be used, but not both.
*/
templateUrl:any; //string;
/**
* Specify an inline template for an angular component.
* Specifies an inline template for an angular component.
*
* NOTE: either `templateURL` or `template` should be used, but not both.
*/
template:any; //string;
/**
* Specify a list of directives that are active within a template. [TODO: true?]
* Specifies a list of directives that can be used within a template.
*
* Directives must be listed explicitly to provide proper component encapsulation.
*

14
modules/angular2/src/core/application.js vendored
View File

@ -199,7 +199,7 @@ function _createVmZone(givenReporter:Function): VmTurnZone {
* 2. It creates a new child injector (from the platform injector) and configures the injector with the component's
* `injectables`. Optionally, you can also override the injector configuration for an app by invoking
* `bootstrap` with the `componentInjectableBindings` argument.
* 3. It creates a new [Zone] and connects it to the angular application's change detection domain instance.
* 3. It creates a new `Zone` and connects it to the angular application's change detection domain instance.
* 4. It creates a shadow DOM on the selected component's host element and loads the template into it.
* 5. It instantiates the specified component.
* 6. Finally, Angular performs change detection to apply the initial data bindings for the application.
@ -214,7 +214,7 @@ function _createVmZone(givenReporter:Function): VmTurnZone {
*
* Angular creates a new application each time that the `bootstrap()` method is invoked. When multiple applications
* are created for a page, Angular treats each application as independent within an isolated change detection and
* [Zone] domain. If you need to share data between applications, use the strategy described in the next
* `Zone` domain. If you need to share data between applications, use the strategy described in the next
* section, "Applications That Share Change Detection."
*
*
@ -238,13 +238,13 @@ function _createVmZone(givenReporter:Function): VmTurnZone {
*
*
* # API
* - [appComponentType]: The root component which should act as the application. This is a reference to a [Type]
* - `appComponentType`: The root component which should act as the application. This is a reference to a `Type`
* which is annotated with `@Component(...)`.
* - [componentInjectableBindings]: An additional set of bindings that can be added to the [Component.injectables] to
* override default injection behavior.
* - [errorReporter]: `function(exception:any, stackTrace:string)` a default error reporter for unhandled exceptions.
* - `componentInjectableBindings`: An additional set of bindings that can be added to `injectables` for the
* {@link Component} to override default injection behavior.
* - `errorReporter`: `function(exception:any, stackTrace:string)` a default error reporter for unhandled exceptions.
*
* Returns a [Promise] with the application`s private [Injector].
* Returns a `Promise` with the application`s private {@link Injector}.
*
* @exportedAs angular2/core
*/

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

@ -80,4 +80,4 @@ export class QueryList extends BaseQueryList {
return super.removeCallback(callback);
}
}
}

4
modules/angular2/src/core/life_cycle/life_cycle.js vendored
View File

@ -7,14 +7,14 @@ import {isPresent} from 'angular2/src/facade/lang';
/**
* Provides access to explicitly trigger change detection in an application.
*
* By default, [Zone] triggers change detection in Angular on each virtual machine (VM) turn. When testing, or in some
* By default, `Zone` triggers change detection in Angular on each virtual machine (VM) turn. When testing, or in some
* limited application use cases, a developer can also trigger change detection with the `lifecycle.tick()` method.
*
* Each Angular application has a single `LifeCycle` instance.
*
* # Example
*
* This is a contrived example, since the bootstrap automatically runs inside of the [Zone], which invokes
* This is a contrived example, since the bootstrap automatically runs inside of the `Zone`, which invokes
* `lifecycle.tick()` on your behalf.
*
* ```javascript

20
modules/angular2/src/core/zone/vm_turn_zone.dart
View File

@ -4,19 +4,19 @@ import 'dart:async' as async;
import 'package:stack_trace/stack_trace.dart' show Chain;
/**
* A [Zone] wrapper that lets you schedule tasks after its private microtask queue is exhausted but
* A `Zone` wrapper that lets you schedule tasks after its private microtask queue is exhausted but
* before the next "VM turn", i.e. event loop iteration.
*
* This lets you freely schedule microtasks that prepare data, and set an [onTurnDone] handler that
* This lets you freely schedule microtasks that prepare data, and set an {@link onTurnDone} handler that
* will consume that data after it's ready but before the browser has a chance to re-render.
*
* A VM turn consist of a single macrotask followed 0 to many microtasks.
*
* The wrapper maintains an "inner" and "outer" [Zone]. The application code will executes
* in the "inner" zone unless [runOutsideAngular] is explicitely called.
* The wrapper maintains an "inner" and "outer" `Zone`. The application code will executes
* in the "inner" zone unless `runOutsideAngular` is explicitely called.
*
* A typical application will create a singleton [VmTurnZone] whose outer [Zone] is the root [Zone]
* and whose default [onTurnDone] runs the Angular digest.
* A typical application will create a singleton `VmTurnZone` whose outer `Zone` is the root `Zone`
* and whose default `onTurnDone` runs the Angular digest.
*/
class VmTurnZone {
Function _onTurnStart;
@ -32,8 +32,8 @@ class VmTurnZone {
/**
* Associates with this
*
* - an "outer" [Zone], which is the one that created this.
* - an "inner" [Zone], which is a child of the outer [Zone].
* - an "outer" `Zone`, which is the one that created this.
* - an "inner" `Zone`, which is a child of the outer `Zone`.
*
* @param {bool} enableLongStackTrace whether to enable long stack trace. They should only be
* enabled in development mode as they significantly impact perf.
@ -60,7 +60,7 @@ class VmTurnZone {
}
/**
* Runs [fn] in the inner zone and returns whatever it returns.
* Runs `fn` in the inner zone and returns whatever it returns.
*
* In a typical app where the inner zone is the Angular zone, this allows one to make use of the
* Angular's auto digest mechanism.
@ -78,7 +78,7 @@ class VmTurnZone {
dynamic run(fn()) => _innerZone.run(fn);
/**
* Runs [fn] in the outer zone and returns whatever it returns.
* Runs `fn` in the outer zone and returns whatever it returns.
*
* In a typical app where the inner zone is the Angular zone, this allows one to escape Angular's
* auto-digest mechanism.

12
modules/angular2/src/core/zone/vm_turn_zone.es6
View File

@ -4,11 +4,11 @@ import {normalizeBlank, isPresent, global} from 'angular2/src/facade/lang';
/**
* A wrapper around zones that lets you schedule tasks after it has executed a task.
*
* The wrapper maintains an "inner" and "outer" [Zone]. The application code will executes
* in the "inner" zone unless [runOutsideAngular] is explicitely called.
* The wrapper maintains an "inner" and "outer" `Zone`. The application code will executes
* in the "inner" zone unless `runOutsideAngular` is explicitely called.
*
* A typical application will create a singleton [VmTurnZone] whose outer [Zone] is the root [Zone]
* and whose default [onTurnDone] runs the Angular digest.
* A typical application will create a singleton `VmTurnZone` whose outer `Zone` is the root `Zone`
* and whose default `onTurnDone` runs the Angular digest.
*
* @exportedAs angular2/core
*/
@ -56,7 +56,7 @@ export class VmTurnZone {
}
/**
* Runs [fn] in the inner zone and returns whatever it returns.
* Runs `fn` in the inner zone and returns whatever it returns.
*
* In a typical app where the inner zone is the Angular zone, this allows one to make use of the
* Angular's auto digest mechanism.
@ -74,7 +74,7 @@ export class VmTurnZone {
}
/**
* Runs [fn] in the outer zone and returns whatever it returns.
* Runs `fn` in the outer zone and returns whatever it returns.
*
* In a typical app where the inner zone is the Angular zone, this allows one to escape Angular's
* auto-digest mechanism.