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

docs(core): migrate `@whatItDoes` tags to the description (#23185) 

We get the overview for the doc by splitting off the first
paragraph.

PR Close #23185
This commit is contained in:
Pete Bacon Darwin 2018-04-05 10:16:31 +01:00 committed by Igor Minar
parent 5bb14a68d2
commit 7dc150c1e8
11 changed files with 81 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
packages/core/src/di/injectable.ts
View File

@ -34,7 +34,6 @@ export type InjectableProvider = ValueSansProvider | ExistingSansProvider |
*/
export interface InjectableDecorator {
/**
* @whatItDoes A marker metadata that marks a class as available to {@link Injector} for creation.
* @usageNotes
* ```
* @Injectable()
@ -42,6 +41,8 @@ export interface InjectableDecorator {
* ```
*
* @description
* A marker metadata that marks a class as available to {@link Injector} for creation.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example

4
packages/core/src/di/injector.ts
View File

@ -39,7 +39,6 @@ export class NullInjector implements Injector {
}
/**
* @whatItDoes Injector interface
* @usageNotes
* ```
* const injector: Injector = ...;
@ -47,6 +46,9 @@ export class NullInjector implements Injector {
* ```
*
* @description
*
* Concrete injectors implement this interface.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example

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

@ -20,7 +20,6 @@ import {EMPTY_ARRAY} from '../view/util';
*/
export interface InjectDecorator {
/**
* @whatItDoes A parameter decorator that specifies a dependency.
* @usageNotes
* ```
* @Injectable()
@ -30,6 +29,8 @@ export interface InjectDecorator {
* ```
*
* @description
* A parameter decorator that specifies a dependency.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -72,8 +73,6 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any)
*/
export interface OptionalDecorator {
/**
* @whatItDoes A parameter metadata that marks a dependency as optional.
* {@link Injector} provides `null` if the dependency is not found.
* @usageNotes
* ```
* @Injectable()
@ -83,6 +82,9 @@ export interface OptionalDecorator {
* ```
*
* @description
* A parameter metadata that marks a dependency as optional.
* {@link Injector} provides `null` if the dependency is not found.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -117,7 +119,6 @@ export const Optional: OptionalDecorator = makeParamDecorator('Optional');
*/
export interface SelfDecorator {
/**
* @whatItDoes Specifies that an {@link Injector} should retrieve a dependency only from itself.
* @usageNotes
* ```
* @Injectable()
@ -127,6 +128,8 @@ export interface SelfDecorator {
* ```
*
* @description
* Specifies that an {@link Injector} should retrieve a dependency only from itself.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -162,7 +165,6 @@ export const Self: SelfDecorator = makeParamDecorator('Self');
*/
export interface SkipSelfDecorator {
/**
* @whatItDoes Specifies that the dependency resolution should start from the parent injector.
* @usageNotes
* ```
* @Injectable()
@ -172,6 +174,8 @@ export interface SkipSelfDecorator {
* ```
*
* @description
* Specifies that the dependency resolution should start from the parent injector.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -206,8 +210,6 @@ export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf');
*/
export interface HostDecorator {
/**
* @whatItDoes Specifies that an injector should retrieve a dependency from any injector until
* reaching the host element of the current component.
* @usageNotes
* ```
* @Injectable()
@ -217,6 +219,9 @@ export interface HostDecorator {
* ```
*
* @description
* Specifies that an injector should retrieve a dependency from any injector until
* reaching the host element of the current component.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example

49
packages/core/src/di/provider.ts
View File

@ -9,7 +9,6 @@
import {Type} from '../type';
/**
* @whatItDoes Configures the {@link Injector} to return a value for a token.
* @usageNotes
* ```
* @Injectable(SomeModule, {useValue: 'someValue'})
@ -17,6 +16,8 @@ import {Type} from '../type';
* ```
*
* @description
* Configures the {@link Injector} to return a value for a token.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -33,13 +34,14 @@ export interface ValueSansProvider {
}
/**
* @whatItDoes Configures the {@link Injector} to return a value for a token.
* @usageNotes
* ```
* const provider: ValueProvider = {provide: 'someToken', useValue: 'someValue'};
* ```
*
* @description
* Configures the {@link Injector} to return a value for a token.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -66,7 +68,6 @@ export interface ValueProvider extends ValueSansProvider {
}
/**
* @whatItDoes Configures the {@link Injector} to return an instance of `useClass` for a token.
* @usageNotes
* ```
* @Injectable(SomeModule, {useClass: MyService, deps: []})
@ -74,6 +75,8 @@ export interface ValueProvider extends ValueSansProvider {
* ```
*
* @description
* Configures the {@link Injector} to return an instance of `useClass` for a token.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -97,7 +100,6 @@ export interface StaticClassSansProvider {
}
/**
* @whatItDoes Configures the {@link Injector} to return an instance of `useClass` for a token.
* @usageNotes
* ```
* @Injectable()
@ -107,6 +109,8 @@ export interface StaticClassSansProvider {
* ```
*
* @description
* Configures the {@link Injector} to return an instance of `useClass` for a token.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -136,7 +140,6 @@ export interface StaticClassProvider extends StaticClassSansProvider {
}
/**
* @whatItDoes Configures the {@link Injector} to return an instance of a token.
* @usageNotes
* ```
* @Injectable(SomeModule, {deps: []})
@ -144,6 +147,8 @@ export interface StaticClassProvider extends StaticClassSansProvider {
* ```
*
* @description
* Configures the {@link Injector} to return an instance of a token.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -161,7 +166,6 @@ export interface ConstructorSansProvider {
}
/**
* @whatItDoes Configures the {@link Injector} to return an instance of a token.
* @usageNotes
* ```
* @Injectable()
@ -171,6 +175,8 @@ export interface ConstructorSansProvider {
* ```
*
* @description
* Configures the {@link Injector} to return an instance of a token.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -197,7 +203,6 @@ export interface ConstructorProvider extends ConstructorSansProvider {
}
/**
* @whatItDoes Configures the {@link Injector} to return a value of another `useExisting` token.
* @usageNotes
* ```
* @Injectable(SomeModule, {useExisting: 'someOtherToken'})
@ -205,6 +210,8 @@ export interface ConstructorProvider extends ConstructorSansProvider {
* ```
*
* @description
* Configures the {@link Injector} to return a value of another `useExisting` token.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -221,13 +228,14 @@ export interface ExistingSansProvider {
}
/**
* @whatItDoes Configures the {@link Injector} to return a value of another `useExisting` token.
* @usageNotes
* ```
* const provider: ExistingProvider = {provide: 'someToken', useExisting: 'someOtherToken'};
* ```
*
* @description
* Configures the {@link Injector} to return a value of another `useExisting` token.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -254,8 +262,6 @@ export interface ExistingProvider extends ExistingSansProvider {
}
/**
* @whatItDoes Configures the {@link Injector} to return a value by invoking a `useFactory`
* function.
* @usageNotes
* ```
* function serviceFactory() { ... }
@ -265,6 +271,8 @@ export interface ExistingProvider extends ExistingSansProvider {
* ```
*
* @description
* Configures the {@link Injector} to return a value by invoking a `useFactory` function.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -288,8 +296,6 @@ export interface FactorySansProvider {
}
/**
* @whatItDoes Configures the {@link Injector} to return a value by invoking a `useFactory`
* function.
* @usageNotes
* ```
* function serviceFactory() { ... }
@ -298,6 +304,8 @@ export interface FactorySansProvider {
* ```
*
* @description
* Configures the {@link Injector} to return a value by invoking a `useFactory` function.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -327,12 +335,12 @@ export interface FactoryProvider extends FactorySansProvider {
}
/**
* @whatItDoes Describes how the {@link Injector} should be configured in a static way (Without
* reflection).
* @usageNotes
* See {@link ValueProvider}, {@link ExistingProvider}, {@link FactoryProvider}.
*
* @description
* Describes how the {@link Injector} should be configured in a static way (Without reflection).
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* @stable
@ -342,8 +350,6 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi
/**
* @whatItDoes Configures the {@link Injector} to return an instance of `Type` when `Type' is used
* as token.
* @usageNotes
* ```
* @Injectable()
@ -353,6 +359,7 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi
* ```
*
* @description
* Configures the {@link Injector} to return an instance of `Type` when `Type' is used as the token.
*
* Create an instance by invoking the `new` operator and supplying additional arguments.
* This form is a short form of `TypeProvider`;
@ -368,8 +375,6 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi
export interface TypeProvider extends Type<any> {}
/**
* @whatItDoes Configures the {@link Injector} to return a value by invoking a `useClass`
* function.
* @usageNotes
* ```
*
@ -380,6 +385,8 @@ export interface TypeProvider extends Type<any> {}
* ```
*
* @description
* Configures the {@link Injector} to return a value by invoking a `useClass` function.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -396,7 +403,6 @@ export interface ClassSansProvider {
}
/**
* @whatItDoes Configures the {@link Injector} to return an instance of `useClass` for a token.
* @usageNotes
* ```
* @Injectable()
@ -406,6 +412,8 @@ export interface ClassSansProvider {
* ```
*
* @description
* Configures the {@link Injector} to return an instance of `useClass` for a token.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* ### Example
@ -435,11 +443,12 @@ export interface ClassProvider extends ClassSansProvider {
}
/**
* @whatItDoes Describes how the {@link Injector} should be configured.
* @usageNotes
* See {@link TypeProvider}, {@link ClassProvider}, {@link StaticProvider}.
*
* @description
* Describes how the {@link Injector} should be configured.
*
* For more details, see the {@linkDocs guide/dependency-injection "Dependency Injection Guide"}.
*
* @stable

2
packages/core/src/error_handler.ts
View File

@ -11,9 +11,9 @@ import {ERROR_ORIGINAL_ERROR, getDebugContext, getErrorLogger, getOriginalError}
/**
* @whatItDoes Provides a hook for centralized exception handling.
*
* @description
* Provides a hook for centralized exception handling.
*
* The default implementation of `ErrorHandler` prints error messages to the `console`. To
* intercept error handling, write a custom exception handler that replaces this default as

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

@ -141,13 +141,13 @@ export abstract class Query {}
*/
export interface ContentChildrenDecorator {
/**
* @whatItDoes Configures a content query.
*
* @usageNotes
*
* {@example core/di/ts/contentChildren/content_children_howto.ts region='HowTo'}
*
* @description
* Configures a content query.
*
* You can use ContentChildren to get the {@link QueryList} of elements or directives from the
* content DOM. Any time a child element is added, removed, or moved, the query list will be
@ -203,13 +203,13 @@ export const ContentChildren: ContentChildrenDecorator = makePropDecorator(
*/
export interface ContentChildDecorator {
/**
* @whatItDoes Configures a content query.
*
* @usageNotes
*
* {@example core/di/ts/contentChild/content_child_howto.ts region='HowTo'}
*
* @description
* Configures a content query.
*
* You can use ContentChild to get the first element or the directive matching the selector from
* the content DOM. If the content DOM changes, and a new child matches the selector,
@ -264,13 +264,13 @@ export const ContentChild: ContentChildDecorator = makePropDecorator(
*/
export interface ViewChildrenDecorator {
/**
* @whatItDoes Configures a view query.
*
* @usageNotes
*
* {@example core/di/ts/viewChildren/view_children_howto.ts region='HowTo'}
*
* @description
* Configures a view query.
*
* You can use ViewChildren to get the {@link QueryList} of elements or directives from the
* view DOM. Any time a child element is added, removed, or moved, the query list will be updated,
@ -323,13 +323,13 @@ export const ViewChildren: ViewChildrenDecorator = makePropDecorator(
*/
export interface ViewChildDecorator {
/**
* @whatItDoes Configures a view query.
*
* @usageNotes
*
* {@example core/di/ts/viewChild/view_child_howto.ts region='HowTo'}
*
* @description
* Configures a view query.
*
* You can use ViewChild to get the first element or the directive matching the selector from the
* view DOM. If the view DOM changes, and a new child matches the selector,

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

@ -21,9 +21,6 @@ import {ViewEncapsulation} from './view';
*/
export interface DirectiveDecorator {
/**
* @whatItDoes Marks a class as an Angular directive and collects directive configuration
* metadata.
*
* @usageNotes
*
* ```
@ -38,6 +35,9 @@ export interface DirectiveDecorator {
*
* @description
*
* Marks a class as an Angular directive and collects directive configuration
* metadata.
*
* Directive decorator allows you to mark a class as an Angular directive and provide additional
* metadata that determines how the directive should be processed, instantiated and used at
* runtime.
@ -410,14 +410,14 @@ export const Directive: DirectiveDecorator =
*/
export interface ComponentDecorator {
/**
* @whatItDoes Marks a class as an Angular component and collects component configuration
* metadata.
*
* @usageNotes
*
* {@example core/ts/metadata/metadata.ts region='component'}
*
* @description
* Marks a class as an Angular component and collects component configuration
* metadata.
*
* Component decorator allows you to mark a class as an Angular component and provide additional
* metadata that determines how the component should be processed, instantiated and used at
* runtime.

30
packages/core/src/metadata/lifecycle_hooks.ts
View File

@ -17,11 +17,12 @@ import {SimpleChange} from '../change_detection/change_detection_util';
export interface SimpleChanges { [propName: string]: SimpleChange; }
/**
* @whatItDoes Lifecycle hook that is called when any data-bound property of a directive changes.
* @usageNotes
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnChanges'}
*
* @description
* Lifecycle hook that is called when any data-bound property of a directive changes.
*
* `ngOnChanges` is called right after the data-bound properties have been checked and before view
* and content children are checked if at least one of them has changed.
* The `changes` parameter contains the changed properties.
@ -33,12 +34,13 @@ export interface SimpleChanges { [propName: string]: SimpleChange; }
export interface OnChanges { ngOnChanges(changes: SimpleChanges): void; }
/**
* @whatItDoes Lifecycle hook that is called after data-bound properties of a directive are
* initialized.
* @usageNotes
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnInit'}
*
* @description
* Lifecycle hook that is called after data-bound properties of a directive are
* initialized.
*
* `ngOnInit` is called right after the directive's data-bound properties have been checked for the
* first time, and before any of its children have been checked. It is invoked only once when the
* directive is instantiated.
@ -50,11 +52,12 @@ export interface OnChanges { ngOnChanges(changes: SimpleChanges): void; }
export interface OnInit { ngOnInit(): void; }
/**
* @whatItDoes Lifecycle hook that is called when Angular dirty checks a directive.
* @usageNotes
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='DoCheck'}
*
* @description
* Lifecycle hook that is called when Angular dirty checks a directive.
*
* `ngDoCheck` gets called to check the changes in the directives in addition to the default
* algorithm. The default change detection algorithm looks for differences by comparing
* bound-property values by reference across change detection runs.
@ -73,11 +76,12 @@ export interface OnInit { ngOnInit(): void; }
export interface DoCheck { ngDoCheck(): void; }
/**
* @whatItDoes Lifecycle hook that is called when a directive, pipe or service is destroyed.
* @usageNotes
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='OnDestroy'}
*
* @description
* Lifecycle hook that is called when a directive, pipe or service is destroyed.
*
* `ngOnDestroy` callback is typically used for any custom cleanup that needs to occur when the
* instance is destroyed.
*
@ -89,12 +93,13 @@ export interface OnDestroy { ngOnDestroy(): void; }
/**
*
* @whatItDoes Lifecycle hook that is called after a directive's content has been fully
* initialized.
* @usageNotes
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterContentInit'}
*
* @description
* Lifecycle hook that is called after a directive's content has been fully
* initialized.
*
* See {@linkDocs guide/lifecycle-hooks#aftercontent "Lifecycle Hooks Guide"}.
*
* @stable
@ -102,11 +107,12 @@ export interface OnDestroy { ngOnDestroy(): void; }
export interface AfterContentInit { ngAfterContentInit(): void; }
/**
* @whatItDoes Lifecycle hook that is called after every check of a directive's content.
* @usageNotes
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterContentChecked'}
*
* @description
* Lifecycle hook that is called after every check of a directive's content.
*
* See {@linkDocs guide/lifecycle-hooks#aftercontent "Lifecycle Hooks Guide"}.
*
* @stable
@ -114,12 +120,13 @@ export interface AfterContentInit { ngAfterContentInit(): void; }
export interface AfterContentChecked { ngAfterContentChecked(): void; }
/**
* @whatItDoes Lifecycle hook that is called after a component's view has been fully
* initialized.
* @usageNotes
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterViewInit'}
*
* @description
* Lifecycle hook that is called after a component's view has been fully
* initialized.
*
* See {@linkDocs guide/lifecycle-hooks#afterview "Lifecycle Hooks Guide"}.
*
* @stable
@ -127,11 +134,12 @@ export interface AfterContentChecked { ngAfterContentChecked(): void; }
export interface AfterViewInit { ngAfterViewInit(): void; }
/**
* @whatItDoes Lifecycle hook that is called after every check of a component's view.
* @usageNotes
* {@example core/ts/metadata/lifecycle_hooks_spec.ts region='AfterViewChecked'}
*
* @description
* Lifecycle hook that is called after every check of a component's view.
*
* See {@linkDocs guide/lifecycle-hooks#afterview "Lifecycle Hooks Guide"}.
*
* @stable

4
packages/core/src/type.ts
View File

@ -7,10 +7,10 @@
*/
/**
* @whatItDoes Represents a type that a Component or other object is instances of.
*
* @description
*
* Represents a type that a Component or other object is instances of.
*
* An example of a `Type` is `MyCustomComponent` class, which in JavaScript is be represented by
* the `MyCustomComponent` constructor function.
*

2
packages/core/src/version.ts
View File

@ -7,7 +7,7 @@
*/
/**
* @whatItDoes Represents the version of Angular
* @description Represents the version of Angular
*
* @stable
*/

4
packages/core/testing/src/test_bed.ts
View File

@ -49,9 +49,9 @@ export type TestModuleMetadata = {
};
/**
* @whatItDoes Configures and initializes environment for unit testing and provides methods for
* creating components and services in unit tests.
* @description
* Configures and initializes environment for unit testing and provides methods for
* creating components and services in unit tests.
*
* TestBed is the primary api for writing unit tests for Angular applications and libraries.
*