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

docs: clean up api doc in core (#37053) 

Add introductions to usage examples and edit descriptions to be more complete and consistent with current API reference styles

PR Close #37053
This commit is contained in:
Judy Bogart 2020-05-11 14:57:23 -07:00 committed by Andrew Kushnir
parent 11dd2bef2d
commit 9206a26e1d
9 changed files with 65 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
packages/core/src/application_init.ts
View File

@ -12,22 +12,26 @@ import {Inject, Injectable, InjectionToken, Optional} from './di';
/**
* An injection token that allows you to provide one or more initialization functions.
* These function are injected at application startup and executed during
* A [DI token](guide/glossary#di-token "DI token definition") that you can use to provide
* one or more initialization functions.
*
* The provided function are injected at application startup and executed during
* app initialization. If any of these functions returns a Promise, initialization
* does not complete until the Promise is resolved.
*
* You can, for example, create a factory function that loads language data
* or an external configuration, and provide that function to the `APP_INITIALIZER` token.
* That way, the function is executed during the application bootstrap process,
* The function is executed during the application bootstrap process,
* and the needed data is available on startup.
*
* @see `ApplicationInitStatus`
*
* @publicApi
*/
export const APP_INITIALIZER = new InjectionToken<Array<() => void>>('Application Initializer');
/**
* A class that reflects the state of running {@link APP_INITIALIZER}s.
* A class that reflects the state of running {@link APP_INITIALIZER} functions.
*
* @publicApi
*/

26
packages/core/src/application_tokens.ts
View File

@ -11,13 +11,14 @@ import {ComponentRef} from './linker/component_factory';
/**
* A DI Token representing a unique string id assigned to the application by Angular and used
* A [DI token](guide/glossary#di-token "DI token definition") representing a unique string ID, used
* primarily for prefixing application attributes and CSS styles when
* {@link ViewEncapsulation#Emulated ViewEncapsulation.Emulated} is being used.
*
* If you need to avoid randomly generated value to be used as an application id, you can provide
* a custom value via a DI provider <!-- TODO: provider --> configuring the root {@link Injector}
* using this token.
* BY default, the value is randomly generated and assigned to the application by Angular.
* To provide a custom ID value, use a DI provider <!-- TODO: provider --> to configure
* the root {@link Injector} that uses this token.
*
* @publicApi
*/
export const APP_ID = new InjectionToken<string>('AppId');
@ -27,7 +28,7 @@ export function _appIdRandomProviderFactory() {
}
/**
* Providers that will generate a random APP_ID_TOKEN.
* Providers that generate a random `APP_ID_TOKEN`.
* @publicApi
*/
export const APP_ID_RANDOM_PROVIDER = {
@ -41,22 +42,24 @@ function _randomChar(): string {
}
/**
* A function that will be executed when a platform is initialized.
* A function that is executed when a platform is initialized.
* @publicApi
*/
export const PLATFORM_INITIALIZER = new InjectionToken<Array<() => void>>('Platform Initializer');
/**
* A token that indicates an opaque platform id.
* A token that indicates an opaque platform ID.
* @publicApi
*/
export const PLATFORM_ID = new InjectionToken<Object>('Platform ID');
/**
* All callbacks provided via this token will be called for every component that is bootstrapped.
* Signature of the callback:
* A [DI token](guide/glossary#di-token "DI token definition") that provides a set of callbacks to
* be called for every component that is bootstrapped.
*
* `(componentRef: ComponentRef) => void`.
* Each callback must take a `ComponentRef` instance and return nothing.
*
* `(componentRef: ComponentRef) => void`
*
* @publicApi
*/
@ -64,7 +67,8 @@ export const APP_BOOTSTRAP_LISTENER =
new InjectionToken<Array<(compRef: ComponentRef<any>) => void>>('appBootstrapListener');
/**
* A token which indicates the root directory of the application
* A [DI token](guide/glossary#di-token "DI token definition") that indicates the root directory of
* the application
* @publicApi
*/
export const PACKAGE_ROOT_URL = new InjectionToken<string>('Application Packages Root URL');

7
packages/core/src/change_detection/change_detector_ref.ts
View File

@ -9,10 +9,13 @@
import {injectChangeDetectorRef as render3InjectChangeDetectorRef} from '../render3/view_engine_compatibility';
/**
* Base class for Angular Views, provides change detection functionality.
* Base class that provides change detection functionality.
* A change-detection tree collects all views that are to be checked for changes.
* Use the methods to add and remove views from the tree, initiate change-detection,
* and explicitly mark views as _dirty_, meaning that they have changed and need to be rerendered.
* and explicitly mark views as _dirty_, meaning that they have changed and need to be re-rendered.
*
* @see [Using change detection hooks](guide/lifecycle-hooks#using-change-detection-hooks)
* @see [Defining custom change detection](guide/lifecycle-hooks#defining-custom-change-detection)
*
* @usageNotes
*

2
packages/core/src/change_detection/constants.ts
View File

@ -11,6 +11,8 @@
* The strategy that the default change detector uses to detect changes.
* When set, takes effect the next time change detection is triggered.
*
* @see {@link ChangeDetectorRef#usage-notes Change detection usage}
*
* @publicApi
*/
export enum ChangeDetectionStrategy {

31
packages/core/src/di/metadata.ts
View File

@ -20,8 +20,6 @@ export interface InjectDecorator {
* Parameter decorator on a dependency parameter of a class constructor
* that specifies a custom provider of the dependency.
*
* Learn more in the ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
* The following example shows a class constructor that specifies a
* custom provider of a dependency using the parameter decorator.
@ -31,6 +29,9 @@ export interface InjectDecorator {
*
* <code-example path="core/di/ts/metadata_spec.ts" region="InjectWithoutDecorator">
* </code-example>
*
* @see ["Dependency Injection Guide"](guide/dependency-injection)
*
*/
(token: any): any;
new(token: any): Inject;
@ -71,8 +72,6 @@ export interface OptionalDecorator {
* Can be used together with other parameter decorators
* that modify how dependency injection operates.
*
* Learn more in the ["Dependency Injection Guide"](guide/dependency-injection).
*
* @usageNotes
*
* The following code allows the possibility of a null result:
@ -80,6 +79,7 @@ export interface OptionalDecorator {
* <code-example path="core/di/ts/metadata_spec.ts" region="Optional">
* </code-example>
*
* @see ["Dependency Injection Guide"](guide/dependency-injection).
*/
(): any;
new(): Optional;
@ -122,7 +122,6 @@ export interface SelfDecorator {
* <code-example path="core/di/ts/metadata_spec.ts" region="Self">
* </code-example>
*
*
* @see `SkipSelf`
* @see `Optional`
*
@ -148,7 +147,7 @@ export const Self: SelfDecorator = makeParamDecorator('Self');
/**
* Type of the SkipSelf decorator / constructor function.
* Type of the `SkipSelf` decorator / constructor function.
*
* @publicApi
*/
@ -167,9 +166,7 @@ export interface SkipSelfDecorator {
* <code-example path="core/di/ts/metadata_spec.ts" region="SkipSelf">
* </code-example>
*
* Learn more in the
* [Dependency Injection guide](guide/dependency-injection-in-action#skip).
*
* @see [Dependency Injection guide](guide/dependency-injection-in-action#skip).
* @see `Self`
* @see `Optional`
*
@ -179,14 +176,14 @@ export interface SkipSelfDecorator {
}
/**
* Type of the SkipSelf metadata.
* Type of the `SkipSelf` metadata.
*
* @publicApi
*/
export interface SkipSelf {}
/**
* SkipSelf decorator and metadata.
* `SkipSelf` decorator and metadata.
*
* @Annotation
* @publicApi
@ -194,7 +191,7 @@ export interface SkipSelf {}
export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf');
/**
* Type of the Host decorator / constructor function.
* Type of the `Host` decorator / constructor function.
*
* @publicApi
*/
@ -204,15 +201,15 @@ export interface HostDecorator {
* that tells the DI framework to resolve the view by checking injectors of child
* elements, and stop when reaching the host element of the current component.
*
* For an extended example, see
* ["Dependency Injection Guide"](guide/dependency-injection-in-action#optional).
*
* @usageNotes
*
* The following shows use with the `@Optional` decorator, and allows for a null result.
*
* <code-example path="core/di/ts/metadata_spec.ts" region="Host">
* </code-example>
*
* For an extended example, see ["Dependency Injection
* Guide"](guide/dependency-injection-in-action#optional).
*/
(): any;
new(): Host;
@ -252,11 +249,11 @@ export interface AttributeDecorator {
* <input type="text">
* ```
*
* The following example uses the decorator to inject the string literal `text`.
* The following example uses the decorator to inject the string literal `text` in a directive.
*
* {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
*
* ### Example as TypeScript Decorator
* The following example uses the decorator in a component constructor.
*
* {@example core/ts/metadata/metadata.ts region='attributeFactory'}
*

14
packages/core/src/linker/ng_module_factory.ts
View File

@ -13,27 +13,25 @@ import {ComponentFactoryResolver} from './component_factory_resolver';
/**
* Represents an instance of an NgModule created via a {@link NgModuleFactory}.
*
* `NgModuleRef` provides access to the NgModule Instance as well other objects related to this
* NgModule Instance.
* Represents an instance of an `NgModule` created by an `NgModuleFactory`.
* Provides access to the `NgModule` instance and related objects.
*
* @publicApi
*/
export abstract class NgModuleRef<T> {
/**
* The injector that contains all of the providers of the NgModule.
* The injector that contains all of the providers of the `NgModule`.
*/
abstract get injector(): Injector;
/**
* The ComponentFactoryResolver to get hold of the ComponentFactories
* The resolver that can retrieve the component factories
* declared in the `entryComponents` property of the module.
*/
abstract get componentFactoryResolver(): ComponentFactoryResolver;
/**
* The NgModule instance.
* The `NgModule` instance.
*/
abstract get instance(): T;
@ -43,7 +41,7 @@ export abstract class NgModuleRef<T> {
abstract destroy(): void;
/**
* Allows to register a callback that will be called when the module is destroyed.
* Registers a callback to be executed when the module is destroyed.
*/
abstract onDestroy(callback: () => void): void;
}

7
packages/core/src/linker/view_ref.ts
View File

@ -10,12 +10,9 @@ import {ApplicationRef} from '../application_ref';
import {ChangeDetectorRef} from '../change_detection/change_detector_ref';
/**
* Represents an Angular [view](guide/glossary#view),
* specifically the [host view](guide/glossary#view-tree) that is defined by a component.
* Also serves as the base class
* that adds destroy methods for [embedded views](guide/glossary#view-tree).
* Represents an Angular [view](guide/glossary#view "Definition").
*
* @see `EmbeddedViewRef`
* @see {@link ChangeDetectorRef#usage-notes Change detection usage}
*
* @publicApi
*/

11
packages/core/src/metadata/directives.ts
View File

@ -282,10 +282,10 @@ export interface Directive {
host?: {[key: string]: string};
/**
* If true, this directive/component will be skipped by the AOT compiler and so will always be
* compiled using JIT.
*
* This exists to support future Ivy work and has no effect currently.
* When present, this directive/component is ignored by the AOT compiler.
* It remains in distributed code, and the JIT compiler attempts to compile it
* at run time, in the browser.
* To ensure the correct behavior, the app must import `@angular/compiler`.
*/
jit?: true;
}
@ -314,7 +314,8 @@ export interface ComponentDecorator {
* An Angular app contains a tree of Angular components.
*
* Angular components are a subset of directives, always associated with a template.
* Unlike other directives, only one component can be instantiated per an element in a template.
* Unlike other directives, only one component can be instantiated for a given element in a
* template.
*
* A component must belong to an NgModule in order for it to be available
* to another component or application. To make it a member of an NgModule,

16
packages/core/src/metadata/ng_module.ts
View File

@ -80,12 +80,10 @@ export interface NgModuleDef<T> {
}
/**
* A wrapper around an NgModule that associates it with the providers.
* A wrapper around an NgModule that associates it with [providers](guide/glossary#provider
* "Definition"). Usage without a generic type is deprecated.
*
* @param T the module type.
*
* Note that using ModuleWithProviders without a generic type is deprecated.
* The generic will become required in a future version of Angular.
* @see [Deprecations](guide/deprecations#modulewithproviders-type-without-a-generic)
*
* @publicApi
*/
@ -296,10 +294,10 @@ export interface NgModule {
id?: string;
/**
* If true, this module will be skipped by the AOT compiler and so will always be compiled
* using JIT.
*
* This exists to support future Ivy work and has no effect currently.
* When present, this module is ignored by the AOT compiler.
* It remains in distributed code, and the JIT compiler attempts to compile it
* at run time, in the browser.
* To ensure the correct behavior, the app must import `@angular/compiler`.
*/
jit?: true;
}