docs: api doc cleanup (#31377)

PR Close #31377

packages/core/src/di/injectable.ts

@@ -31,7 +31,7 @@ export type InjectableProvider = ValueSansProvider | ExistingSansProvider |
  */
 export interface InjectableDecorator {
   /**
-   * Marks a class as available to `Injector` for creation.
+   * Decorator that marks a class as available to `Injector` for creation.
    *
    * @see [Introduction to Services and DI](guide/architecture-services)
    * @see [Dependency Injection Guide](guide/dependency-injection)
@@ -41,7 +41,8 @@ export interface InjectableDecorator {
    * The following example shows how service classes are properly marked as
    * injectable.
    *
-   * <code-example path="core/di/ts/metadata_spec.ts" region="Injectable"></code-example>
+   * <code-example path="core/di/ts/metadata_spec.ts" region="Injectable"
+   *  linenums="false"></code-example>
    *
    */
   (): TypeDecorator;

packages/core/src/di/interface/provider.ts

@@ -23,29 +23,28 @@ export interface ValueSansProvider {
 
 /**
  * Configures the `Injector` to return a value for a token.
- *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @usageNotes
  *
  * ### Example
  *
- * {@example core/di/ts/provider_spec.ts region='ValueProvider'}
+ * {@example core/di/ts/provider_spec.ts region='ValueProvider' linenums="false"}
  *
  * ### Multi-value example
  *
- * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
+ * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
  *
  * @publicApi
  */
 export interface ValueProvider extends ValueSansProvider {
   /**
-   * An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
+   * An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
    */
   provide: any;
 
   /**
-   * If true, then injector returns an array of instances. This is useful to allow multiple
+   * When true, injector returns an array of instances. This is useful to allow multiple
    * providers spread across many files to provide configuration information to a common token.
    */
   multi?: boolean;
@@ -59,13 +58,13 @@ export interface ValueProvider extends ValueSansProvider {
  */
 export interface StaticClassSansProvider {
   /**
-   * An optional class to instantiate for the `token`. (If not provided `provide` is assumed to be a
-   * class to instantiate)
+   * An optional class to instantiate for the `token`. By default, the `provide`
+   * class is instantiated.
    */
   useClass: Type<any>;
 
   /**
-   * A list of `token`s which need to be resolved by the injector. The list of values is then
+   * A list of `token`s to be resolved by the injector. The list of values is then
    * used as arguments to the `useClass` constructor.
    */
   deps: any[];
@@ -73,33 +72,30 @@ export interface StaticClassSansProvider {
 
 /**
  * Configures the `Injector` to return an instance of `useClass` for a token.
- *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @usageNotes
  *
- * ### Example
- *
  * {@example core/di/ts/provider_spec.ts region='StaticClassProvider'}
  *
  * Note that following two providers are not equal:
  *
- * {@example core/di/ts/provider_spec.ts region='StaticClassProviderDifference'}
+ * {@example core/di/ts/provider_spec.ts region='StaticClassProviderDifference' linenums="false"}
  *
  * ### Multi-value example
  *
- * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
+ * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
  *
  * @publicApi
  */
 export interface StaticClassProvider extends StaticClassSansProvider {
   /**
-   * An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
+   * An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
    */
   provide: any;
 
   /**
-   * If true, then injector returns an array of instances. This is useful to allow multiple
+   * When true, injector returns an array of instances. This is useful to allow multiple
    * providers spread across many files to provide configuration information to a common token.
    */
   multi?: boolean;
@@ -108,13 +104,11 @@ export interface StaticClassProvider extends StaticClassSansProvider {
 /**
  * Configures the `Injector` to return an instance of a token.
  *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @usageNotes
  *
- * ### Example
- *
- * ```
+ * ```ts
  * @Injectable(SomeModule, {deps: []})
  * class MyService {}
  * ```
@@ -123,8 +117,7 @@ export interface StaticClassProvider extends StaticClassSansProvider {
  */
 export interface ConstructorSansProvider {
   /**
-   * A list of `token`s which need to be resolved by the injector. The list of values is then
-   * used as arguments to the `useClass` constructor.
+   * A list of `token`s to be resolved by the injector.
    */
   deps?: any[];
 }
@@ -132,28 +125,26 @@ export interface ConstructorSansProvider {
 /**
  * Configures the `Injector` to return an instance of a token.
  *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @usageNotes
  *
- * ### Example
- *
- * {@example core/di/ts/provider_spec.ts region='ConstructorProvider'}
+ * {@example core/di/ts/provider_spec.ts region='ConstructorProvider' linenums="false"}
  *
  * ### Multi-value example
  *
- * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
+ * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
  *
  * @publicApi
  */
 export interface ConstructorProvider extends ConstructorSansProvider {
   /**
-   * An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
+   * An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
    */
   provide: Type<any>;
 
   /**
-   * If true, then injector returns an array of instances. This is useful to allow multiple
+   * When true, injector returns an array of instances. This is useful to allow multiple
    * providers spread across many files to provide configuration information to a common token.
    */
   multi?: boolean;
@@ -162,13 +153,14 @@ export interface ConstructorProvider extends ConstructorSansProvider {
 /**
  * Configures the `Injector` to return a value of another `useExisting` token.
  *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see `ExistingProvider`
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @publicApi
  */
 export interface ExistingSansProvider {
   /**
-   * Existing `token` to return. (equivalent to `injector.get(useExisting)`)
+   * Existing `token` to return. (Equivalent to `injector.get(useExisting)`)
    */
   useExisting: any;
 }
@@ -176,28 +168,26 @@ export interface ExistingSansProvider {
 /**
  * Configures the `Injector` to return a value of another `useExisting` token.
  *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @usageNotes
  *
- * ### Example
- *
- * {@example core/di/ts/provider_spec.ts region='ExistingProvider'}
+ * {@example core/di/ts/provider_spec.ts region='ExistingProvider' linenums="false"}
  *
  * ### Multi-value example
  *
- * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
+ * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
  *
  * @publicApi
  */
 export interface ExistingProvider extends ExistingSansProvider {
   /**
-   * An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).
+   * An injection token. Typically an instance of `Type` or `InjectionToken`, but can be `any`.
    */
   provide: any;
 
   /**
-   * If true, then injector returns an array of instances. This is useful to allow multiple
+   * When true, injector returns an array of instances. This is useful to allow multiple
    * providers spread across many files to provide configuration information to a common token.
    */
   multi?: boolean;
@@ -206,7 +196,8 @@ export interface ExistingProvider extends ExistingSansProvider {
 /**
  * Configures the `Injector` to return a value by invoking a `useFactory` function.
  *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see `FactoryProvider`
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @publicApi
  */
@@ -218,7 +209,7 @@ export interface FactorySansProvider {
   useFactory: Function;
 
   /**
-   * A list of `token`s which need to be resolved by the injector. The list of values is then
+   * A list of `token`s to be resolved by the injector. The list of values is then
    * used as arguments to the `useFactory` function.
    */
   deps?: any[];
@@ -226,22 +217,19 @@ export interface FactorySansProvider {
 
 /**
  * Configures the `Injector` to return a value by invoking a `useFactory` function.
- *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @usageNotes
  *
- * ### Example
- *
- * {@example core/di/ts/provider_spec.ts region='FactoryProvider'}
+ * {@example core/di/ts/provider_spec.ts region='FactoryProvider' linenums="false"}
  *
  * Dependencies can also be marked as optional:
  *
- * {@example core/di/ts/provider_spec.ts region='FactoryProviderOptionalDeps'}
+ * {@example core/di/ts/provider_spec.ts region='FactoryProviderOptionalDeps' linenums="false"}
  *
  * ### Multi-value example
  *
- * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
+ * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
  *
  * @publicApi
  */
@@ -252,20 +240,15 @@ export interface FactoryProvider extends FactorySansProvider {
   provide: any;
 
   /**
-   * If true, then injector returns an array of instances. This is useful to allow multiple
+   * When true, injector returns an array of instances. This is useful to allow multiple
    * providers spread across many files to provide configuration information to a common token.
    */
   multi?: boolean;
 }
 
 /**
- * Describes how the `Injector` should be configured in a static way (Without reflection).
- *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
- *
- * @see `ValueProvider`
- * @see `ExistingProvider`
- * @see `FactoryProvider`
+ * Describes how the `Injector` should be configured as static (that is, without reflection).
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @publicApi
  */
@@ -283,9 +266,7 @@ export type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvi
  *
  * @usageNotes
  *
- * ### Example
- *
- * {@example core/di/ts/provider_spec.ts region='TypeProvider'}
+ * {@example core/di/ts/provider_spec.ts region='TypeProvider' linenums="false"}
  *
  * @publicApi
  */
@@ -295,7 +276,7 @@ export interface TypeProvider extends Type<any> {}
  * Configures the `Injector` to return a value by invoking a `useClass` function.
  * Base for `ClassProvider` decorator.
  *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @publicApi
  */
@@ -308,22 +289,19 @@ export interface ClassSansProvider {
 
 /**
  * Configures the `Injector` to return an instance of `useClass` for a token.
- *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
  * @usageNotes
  *
- * ### Example
- *
- * {@example core/di/ts/provider_spec.ts region='ClassProvider'}
+ * {@example core/di/ts/provider_spec.ts region='ClassProvider' linenums="false"}
  *
  * Note that following two providers are not equal:
  *
- * {@example core/di/ts/provider_spec.ts region='ClassProviderDifference'}
+ * {@example core/di/ts/provider_spec.ts region='ClassProviderDifference' linenums="false"}
  *
  * ### Multi-value example
  *
- * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect'}
+ * {@example core/di/ts/provider_spec.ts region='MultiProviderAspect' linenums="false"}
  *
  * @publicApi
  */
@@ -334,7 +312,7 @@ export interface ClassProvider extends ClassSansProvider {
   provide: any;
 
   /**
-   * If true, then injector returns an array of instances. This is useful to allow multiple
+   * When true, injector returns an array of instances. This is useful to allow multiple
    * providers spread across many files to provide configuration information to a common token.
    */
   multi?: boolean;
@@ -342,11 +320,8 @@ export interface ClassProvider extends ClassSansProvider {
 
 /**
  * Describes how the `Injector` should be configured.
+ * @see ["Dependency Injection Guide"](guide/dependency-injection).
  *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
- *
- * @see `TypeProvider`
- * @see `ClassProvider`
  * @see `StaticProvider`
  *
  * @publicApi
@@ -355,7 +330,7 @@ export type Provider = TypeProvider | ValueProvider | ClassProvider | Constructo
     ExistingProvider | FactoryProvider | any[];
 
 /**
- * Describes a function that is used to process provider list (for example in case of provider
+ * Describes a function that is used to process provider lists (such as provider
  * overrides).
  */
 export type ProcessProvidersFunction = (providers: Provider[]) => Provider[];

packages/core/src/di/metadata.ts

@@ -17,7 +17,7 @@ import {makeParamDecorator} from '../util/decorators';
  */
 export interface InjectDecorator {
   /**
-   * A parameter decorator on a dependency parameter of a class constructor
+   * 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).
@@ -30,7 +30,7 @@ export interface InjectDecorator {
    * parameter as the provider.
    *
    * <code-example path="core/di/ts/metadata_spec.ts"
-   * region="InjectWithoutDecorator"></code-example>
+   * region="InjectWithoutDecorator"  linenums="false"></code-example>
    */
   (token: any): any;
   new (token: any): Inject;
@@ -64,7 +64,7 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any)
  */
 export interface OptionalDecorator {
   /**
-   * A parameter decorator to be used on constructor parameters,
+   * Parameter decorator to be used on constructor parameters,
    * which marks the parameter as being an optional dependency.
    * The DI framework provides null if the dependency is not found.
    *
@@ -77,7 +77,8 @@ export interface OptionalDecorator {
    *
    * The following code allows the possibility of a null result:
    *
-   * <code-example path="core/di/ts/metadata_spec.ts" region="Optional"></code-example>
+   * <code-example path="core/di/ts/metadata_spec.ts" region="Optional"
+   *  linenums="false"></code-example>
    *
    */
   (): any;
@@ -106,7 +107,7 @@ export const Optional: OptionalDecorator = makeParamDecorator('Optional');
  */
 export interface SelfDecorator {
   /**
-   * A parameter decorator to be used on constructor parameters,
+   * Parameter decorator to be used on constructor parameters,
    * which tells the DI framework to start dependency resolution from the local injector.
    *
    * Resolution works upward through the injector hierarchy, so the children
@@ -118,8 +119,9 @@ export interface SelfDecorator {
    * by the local injector when instantiating the class itself, but not
    * when instantiating a child.
    *
-   * <code-example path="core/di/ts/metadata_spec.ts" region="Self"></code-example>
-   * 
+   * <code-example path="core/di/ts/metadata_spec.ts" region="Self"
+   *  linenums="false"></code-example>
+   *
    *
    * @see `SkipSelf`
    * @see `Optional`
@@ -152,7 +154,7 @@ export const Self: SelfDecorator = makeParamDecorator('Self');
  */
 export interface SkipSelfDecorator {
   /**
-   * A parameter decorator to be used on constructor parameters,
+   * Parameter decorator to be used on constructor parameters,
    * which tells the DI framework to start dependency resolution from the parent injector.
    * Resolution works upward through the injector hierarchy, so the local injector
    * is not checked for a provider.
@@ -162,7 +164,8 @@ export interface SkipSelfDecorator {
    * In the following example, the dependency can be resolved when
    * instantiating a child, but not when instantiating the class itself.
    *
-   * <code-example path="core/di/ts/metadata_spec.ts" region="SkipSelf"></code-example>
+   * <code-example path="core/di/ts/metadata_spec.ts" region="SkipSelf"
+   *  linenums="false"></code-example>
    *
    * Learn more in the
    * [Dependency Injection guide](guide/dependency-injection-in-action#skip).
@@ -197,7 +200,7 @@ export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf');
  */
 export interface HostDecorator {
   /**
-   * A parameter decorator on a view-provider parameter of a class constructor
+   * Parameter decorator on a view-provider parameter of a class constructor
    * 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.
    *
@@ -208,7 +211,8 @@ export interface HostDecorator {
    *
    * 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>
+   * <code-example path="core/di/ts/metadata_spec.ts" region="Host"
+   *  linenums="false"></code-example>
    */
   (): any;
   new (): Host;
@@ -237,7 +241,7 @@ export const Host: HostDecorator = makeParamDecorator('Host');
  */
 export interface AttributeDecorator {
   /**
-   * A parameter decorator for a directive constructor that designates
+   * Parameter decorator for a directive constructor that designates
    * a host-element attribute whose value is injected as a constant string literal.
    *
    * @usageNotes
@@ -250,11 +254,11 @@ export interface AttributeDecorator {
    *
    * The following example uses the decorator to inject the string literal `text`.
    *
-   * {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
+   * {@example core/ts/metadata/metadata.ts region='attributeMetadata' linenums="false"}
    *
    * ### Example as TypeScript Decorator
    *
-   * {@example core/ts/metadata/metadata.ts region='attributeFactory'}
+   * {@example core/ts/metadata/metadata.ts region='attributeFactory' linenums="false"}
    *
    */
   (name: string): any;