From 7dc150c1e8a4a8b210a5cf720f6968cd07073e03 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Thu, 5 Apr 2018 10:16:31 +0100 Subject: [PATCH] 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 --- packages/core/src/di/injectable.ts | 3 +- packages/core/src/di/injector.ts | 4 +- packages/core/src/di/metadata.ts | 19 ++++--- packages/core/src/di/provider.ts | 49 +++++++++++-------- packages/core/src/error_handler.ts | 2 +- packages/core/src/metadata/di.ts | 8 +-- packages/core/src/metadata/directives.ts | 12 ++--- packages/core/src/metadata/lifecycle_hooks.ts | 30 +++++++----- packages/core/src/type.ts | 4 +- packages/core/src/version.ts | 2 +- packages/core/testing/src/test_bed.ts | 4 +- 11 files changed, 81 insertions(+), 56 deletions(-) diff --git a/packages/core/src/di/injectable.ts b/packages/core/src/di/injectable.ts index 3317f5c46d..663a03a219 100644 --- a/packages/core/src/di/injectable.ts +++ b/packages/core/src/di/injectable.ts @@ -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 diff --git a/packages/core/src/di/injector.ts b/packages/core/src/di/injector.ts index a6bc542118..ba98456e35 100644 --- a/packages/core/src/di/injector.ts +++ b/packages/core/src/di/injector.ts @@ -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 diff --git a/packages/core/src/di/metadata.ts b/packages/core/src/di/metadata.ts index 3fb2dd0e8e..bb283669cb 100644 --- a/packages/core/src/di/metadata.ts +++ b/packages/core/src/di/metadata.ts @@ -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 diff --git a/packages/core/src/di/provider.ts b/packages/core/src/di/provider.ts index af7596220c..12b0cc8f18 100644 --- a/packages/core/src/di/provider.ts +++ b/packages/core/src/di/provider.ts @@ -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 {} /** - * @whatItDoes Configures the {@link Injector} to return a value by invoking a `useClass` - * function. * @usageNotes * ``` * @@ -380,6 +385,8 @@ export interface TypeProvider extends Type {} * ``` * * @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 diff --git a/packages/core/src/error_handler.ts b/packages/core/src/error_handler.ts index c1266d1c57..f961c4cc33 100644 --- a/packages/core/src/error_handler.ts +++ b/packages/core/src/error_handler.ts @@ -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 diff --git a/packages/core/src/metadata/di.ts b/packages/core/src/metadata/di.ts index 4de689b2e6..2fe51f3294 100644 --- a/packages/core/src/metadata/di.ts +++ b/packages/core/src/metadata/di.ts @@ -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, diff --git a/packages/core/src/metadata/directives.ts b/packages/core/src/metadata/directives.ts index 679c875617..9c7fb21a30 100644 --- a/packages/core/src/metadata/directives.ts +++ b/packages/core/src/metadata/directives.ts @@ -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. diff --git a/packages/core/src/metadata/lifecycle_hooks.ts b/packages/core/src/metadata/lifecycle_hooks.ts index 23b997fb68..70046d97a2 100644 --- a/packages/core/src/metadata/lifecycle_hooks.ts +++ b/packages/core/src/metadata/lifecycle_hooks.ts @@ -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 diff --git a/packages/core/src/type.ts b/packages/core/src/type.ts index 72524fd2a8..a6429bd970 100644 --- a/packages/core/src/type.ts +++ b/packages/core/src/type.ts @@ -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. * diff --git a/packages/core/src/version.ts b/packages/core/src/version.ts index 0d5b462866..76534b37e8 100644 --- a/packages/core/src/version.ts +++ b/packages/core/src/version.ts @@ -7,7 +7,7 @@ */ /** - * @whatItDoes Represents the version of Angular + * @description Represents the version of Angular * * @stable */ diff --git a/packages/core/testing/src/test_bed.ts b/packages/core/testing/src/test_bed.ts index 17e6fce535..32f1470c45 100644 --- a/packages/core/testing/src/test_bed.ts +++ b/packages/core/testing/src/test_bed.ts @@ -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. *