docs: add di-related api doc (#27731)

PR Close #27731

aio/content/guide/dependency-injection-in-action.md

@@ -262,6 +262,8 @@ Using a custom provider allows you to provide a concrete implementation for impl
 
 The `factory` function returns the `localStorage` property that is attached to the browser window object. The `Inject` decorator is a constructor parameter used to specify a custom provider of a dependency. This custom provider can now be overridden during testing with a mock API of `localStorage` instead of interactive with real browser APIs.
 
+{@a skip}
+
 ### Modify the provider search with `@Self` and `@SkipSelf`
 
 Providers can also be scoped by injector through constructor parameter decorators. The following example overrides the `BROWSER_STORAGE` token in the `Component` class `providers` with the `sessionStorage` browser API. The same `BrowserStorageService` is injected twice in the constructor, decorated with `@Self` and `@SkipSelf` to define which injector handles the provider dependency.
@@ -784,4 +786,3 @@ If you want to show only one of them, use the directive to make sure __??of what
 `<hero-overview heroCache></hero-overview>`
 
  --->
-

packages/common/src/location/location_strategy.ts

@@ -40,16 +40,15 @@ export abstract class LocationStrategy {
 
 
 /**
- * The `APP_BASE_HREF` token represents the base href to be used with the
+ * A predefined [DI token](guide/glossary#di-token) for the base href
- * {@link PathLocationStrategy}.
+ * to be used with the `PathLocationStrategy`.
- *
+ * The base href is the URL prefix that should be preserved when generating
- * If you're using {@link PathLocationStrategy}, you must provide a provider to a string
+ * and recognizing URLs.
- * representing the URL prefix that should be preserved when generating and recognizing
- * URLs.
  *
  * @usageNotes
  *
- * ### Example
+ * The following example shows how to use this token to configure the root app injector
+ * with a base href value, so that the DI framework can supply the dependency anywhere in the app.
  *
  * ```typescript
  * import {Component, NgModule} from '@angular/core';

packages/core/src/di/injectable.ts

@@ -30,17 +30,20 @@ export type InjectableProvider = ValueSansProvider | ExistingSansProvider |
  */
 export interface InjectableDecorator {
   /**
-   * A marker metadata that marks a class as available to `Injector` for creation.
+   * Marks a class as available to `Injector` for creation.
    *
-   * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+   * @see [Introduction to Services and DI](guide/architecture-services)
+   * @see [Dependency Injection Guide](guide/dependency-injection)
    *
    * @usageNotes
-   * ### Example
+   *
+   * The following example shows how service classes are properly marked as
+   * injectable.
    *
    * {@example core/di/ts/metadata_spec.ts region='Injectable'}
    *
-   * `Injector` will throw an error when trying to instantiate a class that
+   * `Injector` throws an error if it tries to instantiate a class that
-   * does not have `@Injectable` marker, as shown in the example below.
+   * is not decorated with `@Injectable`, as shown in the following example.
    *
    * {@example core/di/ts/metadata_spec.ts region='InjectableThrows'}
    *
@@ -56,7 +59,15 @@ export interface InjectableDecorator {
  *
  * @publicApi
  */
-export interface Injectable { providedIn?: Type<any>|'root'|null; }
+export interface Injectable {
+  /**
+   * Determines which injectors will provide the injectable,
+   * by either associating it with an @NgModule or other `InjectorType`,
+   * or by specifying that this injectable should be provided in the
+   * 'root' injector, which will be the application-level injector in most apps.
+   */
+  providedIn?: Type<any>|'root'|null;
+}
 
 /**
  * Injectable decorator and metadata.

packages/core/src/di/metadata.ts

@@ -20,10 +20,10 @@ import {EMPTY_ARRAY} from '../view/util';
  */
 export interface InjectDecorator {
   /**
-   * A constructor parameter decorator that specifies a
+   * A parameter decorator on a dependency parameter of a class constructor
-   * custom provider of a dependency.
+   * that specifies a custom provider of the dependency.
    *
-   * @see ["Dependency Injection Guide"](guide/dependency-injection).
+   * Learn more in the ["Dependency Injection Guide"](guide/dependency-injection).
    *
    * @usageNotes
    * The following example shows a class constructor that specifies a
@@ -31,7 +31,7 @@ export interface InjectDecorator {
    *
    * {@example core/di/ts/metadata_spec.ts region='Inject'}
    *
-   * When `@Inject()` is not present, the `Injector` uses the type annotation of the
+   * When `@Inject()` is not present, the injector uses the type annotation of the
    * parameter as the provider.
    *
    * {@example core/di/ts/metadata_spec.ts region='InjectWithoutDecorator'}
@@ -47,7 +47,7 @@ export interface InjectDecorator {
  */
 export interface Inject {
   /**
-   * Injector token that maps to the dependency to be injected.
+   * A [DI token](guide/glossary#di-token) that maps to the dependency to be injected.
    */
   token: any;
 }
@@ -68,14 +68,21 @@ export const Inject: InjectDecorator = makeParamDecorator('Inject', (token: any)
  */
 export interface OptionalDecorator {
   /**
-   * A constructor parameter decorator that marks a dependency as optional.
+   * A 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.
-   * For example, the following code allows the possibility of a null result:
+   *
+   * 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:
    *
    * {@example core/di/ts/metadata_spec.ts region='Optional'}
    *
-   * @see ["Dependency Injection Guide"](guide/dependency-injection).
    */
   (): any;
   new (): Optional;
@@ -103,8 +110,13 @@ export const Optional: OptionalDecorator = makeParamDecorator('Optional');
  */
 export interface SelfDecorator {
   /**
-   * A constructor parameter decorator that tells the DI framework
+   * A parameter decorator to be used on constructor parameters,
-   * to retrieve a dependency only from the local injector.
+   * which tells the DI framework to start dependency resolution from the local injector.
+   *
+   * Resolution works upward through the injector hierarchy, so the children
+   * of this class must configure their own providers or be prepared for a null result.
+   *
+   * @usageNotes
    *
    * In the following example, the dependency can be resolved
    * by the local injector when instantiating the class itself, but not
@@ -112,8 +124,8 @@ export interface SelfDecorator {
    *
    * {@example core/di/ts/metadata_spec.ts region='Self'}
    *
-   * @see ["Dependency Injection Guide"](guide/dependency-injection).
+   * @see `SkipSelf`
-   *
+   * @see `Optional`
    *
    */
   (): any;
@@ -143,16 +155,23 @@ export const Self: SelfDecorator = makeParamDecorator('Self');
  */
 export interface SkipSelfDecorator {
   /**
-   * A constructor parameter decorator that tells the DI framework
+   * A parameter decorator to be used on constructor parameters,
-   * that dependency resolution should start from the parent injector.
+   * 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.
+   *
+   * @usageNotes
    *
    * In the following example, the dependency can be resolved when
    * instantiating a child, but not when instantiating the class itself.
    *
    * {@example core/di/ts/metadata_spec.ts region='SkipSelf'}
    *
-   * @see ["Dependency Injection Guide"](guide/dependency-injection).
+   * Learn more in the
+   * [Dependency Injection guide](guide/dependency-injection-in-action#skip).
    *
+   * @see `Self`
+   * @see `Optional`
    *
    */
   (): any;
@@ -181,14 +200,17 @@ export const SkipSelf: SkipSelfDecorator = makeParamDecorator('SkipSelf');
  */
 export interface HostDecorator {
   /**
-   * A constructor parameter decorator that tells the DI framework
+   * A parameter decorator on a view-provider parameter of a class constructor
-   * to retrieve a dependency from any injector until
+   * that tells the DI framework to resolve the view by checking injectors of child
-   * reaching the host element of the current component.
+   * elements, and stop when reaching the host element of the current component.
    *
-   * @see ["Dependency Injection Guide"](guide/dependency-injection).
+   * 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.
+   *
    * {@example core/di/ts/metadata_spec.ts region='Host'}
    */
   (): any;

packages/core/src/metadata/di.ts

@@ -11,15 +11,16 @@ import {Type} from '../type';
 import {makeParamDecorator, makePropDecorator} from '../util/decorators';
 
 /**
- * This token can be used to create a virtual provider that will populate the
+ * A DI token that you can use to create a virtual [provider](guide/glossary#provider)
- * `entryComponents` fields of components and ng modules based on its `useValue`.
+ * that will populate the `entryComponents` field of components and NgModules
+ * based on its `useValue` property value.
  * All components that are referenced in the `useValue` value (either directly
- * or in a nested array or map) will be added to the `entryComponents` property.
+ * or in a nested array or map) are added to the `entryComponents` property.
  *
  * @usageNotes
- * ### Example
+ *
  * The following example shows how the router can populate the `entryComponents`
- * field of an NgModule based on the router configuration which refers
+ * field of an NgModule based on a router configuration that refers
  * to components.
  *
  * ```typescript
@@ -48,7 +49,7 @@ import {makeParamDecorator, makePropDecorator} from '../util/decorators';
 export const ANALYZE_FOR_ENTRY_COMPONENTS = new InjectionToken<any>('AnalyzeForEntryComponents');
 
 /**
- * Type of the Attribute decorator / constructor function.
+ * Type of the `Attribute` decorator / constructor function.
  *
  * @publicApi
  */
@@ -67,29 +68,10 @@ export interface AttributeDecorator {
    * <input type="text">
    * ```
    *
-   * A decorator can inject string literal `text` like so:
+   * A decorator can inject string literal `text` as in the following example.
    *
    * {@example core/ts/metadata/metadata.ts region='attributeMetadata'}
    *
-   * ### Example as TypeScript Decorator
-   *
-   * {@example core/ts/metadata/metadata.ts region='attributeFactory'}
-   *
-   * ### Example as ES5 annotation
-   *
-   * ```
-   * var MyComponent = function(title) {
-   *   ...
-   * };
-   *
-   * MyComponent.annotations = [
-   *   new ng.Component({...})
-   * ]
-   * MyComponent.parameters = [
-   *   [new ng.Attribute('title')]
-   * ]
-   * ```
-   *
    * @publicApi
    */
   (name: string): any;
@@ -102,7 +84,12 @@ export interface AttributeDecorator {
  *
  * @publicApi
  */
-export interface Attribute { attributeName?: string; }
+export interface Attribute {
+  /**
+   * The name of the attribute to be injected into the constructor.
+   */
+  attributeName?: string;
+}
 
 /**
  * Attribute decorator and metadata.