From 998c7c2e03edea6de4c00725f506c40157cd0b0e Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Thu, 3 Sep 2015 16:17:23 -0700 Subject: [PATCH] doc: add some API doc Closes #4060 --- modules/angular2/router.ts | 22 ++++++++ .../angular2/src/core/application_tokens.ts | 3 +- .../core/change_detection/pipe_transform.ts | 31 +++++++++-- .../angular2/src/core/compiler/element_ref.ts | 15 +++--- modules/angular2/src/core/di/binding.ts | 30 +++++++++-- modules/angular2/src/core/di/injector.ts | 12 +++++ modules/angular2/src/core/di/opaque_token.ts | 25 +++++++-- modules/angular2/src/core/facade/async.ts | 51 ++++++++++++++++--- modules/angular2/src/router/router.ts | 8 +-- 9 files changed, 164 insertions(+), 33 deletions(-) diff --git a/modules/angular2/router.ts b/modules/angular2/router.ts index 21d3a8169b..7beb32465c 100644 --- a/modules/angular2/router.ts +++ b/modules/angular2/router.ts @@ -38,6 +38,28 @@ import {CONST_EXPR} from './src/core/facade/lang'; export const ROUTER_DIRECTIVES: any[] = CONST_EXPR([RouterOutlet, RouterLink]); +/** + * A list of {@link Binding}. To use the router, you must add this to your application. + * + * ## Example + * + * ```typescript + * @Component({...}) + * @View({directives: [ROUTER_DIRECTIVES]}) + * @RouteConfig([ + * new Route(...), + * ]) + * class AppCmp { + * constructor(router: Router, location: Location) { + * // ... + * } + * + * } + * + * + * bootstrap(AppCmp, [ROUTER_BINDINGS]); + * ``` + */ export const ROUTER_BINDINGS: any[] = CONST_EXPR([ RouteRegistry, Pipeline, diff --git a/modules/angular2/src/core/application_tokens.ts b/modules/angular2/src/core/application_tokens.ts index c27b7c5a37..03f4252b40 100644 --- a/modules/angular2/src/core/application_tokens.ts +++ b/modules/angular2/src/core/application_tokens.ts @@ -7,7 +7,8 @@ import {CONST_EXPR} from 'angular2/src/core/facade/lang'; export const APP_COMPONENT_REF_PROMISE = CONST_EXPR(new OpaqueToken('Promise')); /** - * An opaque token representing the application root type in the {@link Injector}. + * An {@link angular2/di/OpaqueToken} representing the application root type in the {@link + * Injector}. * * ``` * @Component(...) diff --git a/modules/angular2/src/core/change_detection/pipe_transform.ts b/modules/angular2/src/core/change_detection/pipe_transform.ts index 1d354a0fb6..966a2da8e7 100644 --- a/modules/angular2/src/core/change_detection/pipe_transform.ts +++ b/modules/angular2/src/core/change_detection/pipe_transform.ts @@ -1,17 +1,38 @@ import {ABSTRACT, BaseException, CONST, Type} from 'angular2/src/core/facade/lang'; /** - * An interface which all pipes must implement. + * To create a Pipe, you must implement this interface. * - * #Example + * Angular invokes the `transform` method with the subject as the `value` argument and any + * parameters in the `args` Array. + * + * ## Syntax + * + * `subject | pipeName[:arg0[:arg1...]]` + * + * ## Example + * + * The `RepeatPipe` below repeats the subject as many times as indicated by the first argument: * * ``` - * class DoublePipe implements PipeTransform { - * transform(value, args = []) { - * return `${value}${value}`; + * @Pipe({name: 'repeat'}) + * class RepeatPipe implements PipeTransform { + * + * transform(value: any, args: any[] = []) { + * if (isBlank(args) || args.length == 0) { + * throw new BaseException('limitTo pipe requires one argument'); + * } + * + * let times: number = args[0]; + * + * return value.repeat(times); * } * } * ``` + * + * Invoking `{{ 'ok' | repeat:3 }}` in a template produces `okokok`. + * + * ``` */ export interface PipeTransform { transform(value: any, args: any[]): any; } diff --git a/modules/angular2/src/core/compiler/element_ref.ts b/modules/angular2/src/core/compiler/element_ref.ts index cdd9dbb721..1325b0b041 100644 --- a/modules/angular2/src/core/compiler/element_ref.ts +++ b/modules/angular2/src/core/compiler/element_ref.ts @@ -3,12 +3,11 @@ import {ViewRef} from './view_ref'; import {RenderViewRef, RenderElementRef, Renderer} from 'angular2/src/core/render/api'; /** - * Reference to the element. + * An opaque reference to the underlying element. * - * Represents an opaque reference to the underlying element. The element is a DOM ELement in - * a Browser, but may represent other types on other rendering platforms. In the browser the - * `ElementRef` can be sent to the web-worker. Web Workers can not have references to the - * DOM Elements. + * The underlying native element is a DOM Element in a browser context, but may represent other + * types on other rendering platforms. In the browser the `ElementRef` can be sent to the Web + * Worker. Web Workers can not have references to the DOM Elements. */ export class ElementRef implements RenderElementRef { /** @@ -51,11 +50,11 @@ export class ElementRef implements RenderElementRef { /** * Returns the native Element implementation. * - * In the browser this represents the DOM Element. + * In the browser this represents the DOM element. * * The `nativeElement` can be used as an escape hatch when direct DOM manipulation is needed. Use - * this with caution, as it creates tight coupling between your application and the Browser, which - * will not work in WebWorkers. + * this with caution, as it creates tight coupling between your application and the browser, which + * will not work in Web Workers. * * NOTE: This method will return null in the webworker scenario! */ diff --git a/modules/angular2/src/core/di/binding.ts b/modules/angular2/src/core/di/binding.ts index 69afd92c1d..ac846a4e10 100644 --- a/modules/angular2/src/core/di/binding.ts +++ b/modules/angular2/src/core/di/binding.ts @@ -266,14 +266,38 @@ export class ResolvedFactory { /** * Provides an API for imperatively constructing {@link Binding}s. * - * This is only relevant for JavaScript. See {@link BindingBuilder}. + * To construct a {@link Binding}, bind a `token` to either a class, a value or a factory function. + * See {@link BindingBuilder} for more details. + * + * The `token` is most commonly an {@link angular2/di/OpaqueToken} or a class. + * + * `bind` is only relevant for JavaScript. For Dart use the {@link Binding} constructor. * * ## Example * - * ```javascript - * bind(MyInterface).toClass(MyClass) + * ```typescript + * // inj.get(MyClass) would instantiate MyClass + * bind(MyClass).toClass(MyClass); * + * // inj.get(MyClass) === 'my class' + * bind(MyClass).toValue('my class'); + * + * // inj.get(MyClass) would instantiate the depenency and call the factory function with the + * // instance + * bind(MyClass).toFactory(dep => new MyClass(dep), [DepClass]); + * + * // inj.get(MyOtherClass) === inj.get(MyClass) + * bind(MyOtherClass).toAlias(MyClass); * ``` + * + * ```dart + * var binding = new Binding(MyClass, toClass: MyClass); + * var binding = new Binding(MyClass, toValue: 'my class'); + * var binding = new Binding(MyClass, toFactory: (dep) => new MyClass(dep), + * dependencies: [DepClass]); + * var binding = new Binding(MyOtherClass, toAlias: MyClass); + * ``` + * */ export function bind(token): BindingBuilder { return new BindingBuilder(token); diff --git a/modules/angular2/src/core/di/injector.ts b/modules/angular2/src/core/di/injector.ts index cc377fe2ce..2b5bbf169f 100644 --- a/modules/angular2/src/core/di/injector.ts +++ b/modules/angular2/src/core/di/injector.ts @@ -27,9 +27,21 @@ const _MAX_CONSTRUCTION_COUNTER = 10; export const UNDEFINED: Object = CONST_EXPR(new Object()); +/** + * Visibility of a {@link Binding}. + */ export enum Visibility { + /** + * A `Public` {@link Binding} is only visible to regular (as opposed to host) child injectors. + */ Public, + /** + * A `Private` {@link Binding} is only visible to host (as opposed to regular) child injectors. + */ Private, + /** + * A `PublicAndPrivate` {@link Binding} is visible to both host and regular child injectors. + */ PublicAndPrivate } diff --git a/modules/angular2/src/core/di/opaque_token.ts b/modules/angular2/src/core/di/opaque_token.ts index 42e2af989a..dc9b77317f 100644 --- a/modules/angular2/src/core/di/opaque_token.ts +++ b/modules/angular2/src/core/di/opaque_token.ts @@ -1,10 +1,27 @@ import {CONST} from 'angular2/src/core/facade/lang'; +/** + * By binding to an `OpaqueToken` you can enable an application to return more meaningful error + * messages. + * + * ## Example + * + * ``` + * // While the following would work, see below for the preferred way + * var binding = bind('value0').toValue(0); + * ... + * var value = injector.get('value0'); + * + * // An OpaqueToken is the preferred way and lead to more helpful error messages + * export value0Token = new OpaqueToken('value0'); + * var binding = bind(value0Token).toValue(0); + * ... + * var value = injector.get(value0Token); + * ``` + */ @CONST() export class OpaqueToken { - _desc: string; + constructor(private _desc: string) {} - constructor(desc: string) { this._desc = 'Token(' + desc + ')'; } - - toString(): string { return this._desc; } + toString(): string { return `Token ${this._desc}`; } } diff --git a/modules/angular2/src/core/facade/async.ts b/modules/angular2/src/core/facade/async.ts index 17f07f3826..178c2ef7fd 100644 --- a/modules/angular2/src/core/facade/async.ts +++ b/modules/angular2/src/core/facade/async.ts @@ -90,20 +90,46 @@ export class Observable { } /** + * Use by directives and components to emit custom {@link Event}s. + * + * ## Examples + * + * In the following example, `Zippy` alternatively emits `open` and `close` events when its + * title gets clicked: + * + * ``` + * @Component({selector: 'zippy'}) + * @View({template: ` + *
+ *
Toggle
+ *
+ * + *
+ *
`}) + * export class Zippy { + * visible: boolean = true; + * @Event() open: EventEmitter = new EventEmitter(); + * @Event() close: EventEmitter = new EventEmitter(); + * + * toggle() { + * this.visible = !this.visible; + * if (this.visible) { + * this.open.next(null); + * } else { + * this.close.next(null); + * } + * } + * } + * ``` + * * Use Rx.Observable but provides an adapter to make it work as specified here: * https://github.com/jhusain/observable-spec * * Once a reference implementation of the spec is available, switch to it. */ export class EventEmitter extends Observable { - _subject: Rx.Subject; - _immediateScheduler; - - constructor() { - super(); - this._subject = new Rx.Subject(); - this._immediateScheduler = (Rx.Scheduler).immediate; - } + _subject: Rx.Subject = new Rx.Subject(); + _immediateScheduler = (Rx.Scheduler).immediate; observer(generator: any): Rx.IDisposable { return this._subject.observeOn(this._immediateScheduler) @@ -114,9 +140,18 @@ export class EventEmitter extends Observable { toRx(): Rx.Observable { return this._subject; } + /** + * Emits a `value`. + */ next(value: any) { this._subject.onNext(value); } + /** + * Emits an `error`. + */ throw(error: any) { this._subject.onError(error); } + /** + * Closes the stream. + */ return (value?: any) { this._subject.onCompleted(); } } diff --git a/modules/angular2/src/router/router.ts b/modules/angular2/src/router/router.ts index 436d4a1fab..2f1d992365 100644 --- a/modules/angular2/src/router/router.ts +++ b/modules/angular2/src/router/router.ts @@ -27,17 +27,17 @@ let _resolveToTrue = PromiseWrapper.resolve(true); let _resolveToFalse = PromiseWrapper.resolve(false); /** - * # Router - * The router is responsible for mapping URLs to components. + * The `Router` is responsible for mapping URLs to components. * * You can see the state of the router by inspecting the read-only field `router.navigating`. * This may be useful for showing a spinner, for instance. * * ## Concepts + * * Routers and component instances have a 1:1 correspondence. * - * The router holds reference to a number of "outlets." An outlet is a placeholder that the - * router dynamically fills in depending on the current URL. + * The router holds reference to a number of {@link RouterOutlet}. + * An outlet is a placeholder that the router dynamically fills in depending on the current URL. * * When the router navigates from a URL, it must first recognizes it and serialize it into an * `Instruction`.