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

packages/core/src/application_init.ts

@@ -12,22 +12,26 @@ import {Inject, Injectable, InjectionToken, Optional} from './di';
 
 
 /**
- * An injection token that allows you to provide one or more initialization functions.
+ * A [DI token](guide/glossary#di-token "DI token definition") that you can use to provide
- * These function are injected at application startup and executed during
+ * 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
  */

packages/core/src/application_tokens.ts

@@ -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
+ * BY default, the value is randomly generated and assigned to the application by Angular.
- * a custom value via a DI provider <!-- TODO: provider --> configuring the root {@link Injector}
+ * To provide a custom ID value, use a DI provider <!-- TODO: provider --> to configure
- * using this token.
+ * 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.
+ * A [DI token](guide/glossary#di-token "DI token definition") that provides a set of callbacks to
- * Signature of the callback:
+ * 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');

packages/core/src/change_detection/change_detector_ref.ts

@@ -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
  *

packages/core/src/change_detection/constants.ts

@@ -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 {

packages/core/src/di/metadata.ts

@@ -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
+   * @see [Dependency Injection guide](guide/dependency-injection-in-action#skip).
-   * [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'}
    *

packages/core/src/linker/ng_module_factory.ts

@@ -13,27 +13,25 @@ import {ComponentFactoryResolver} from './component_factory_resolver';
 
 
 /**
- * Represents an instance of an NgModule created via a {@link NgModuleFactory}.
+ * Represents an instance of an `NgModule` created by an `NgModuleFactory`.
- *
+ * Provides access to the `NgModule` instance and related objects.
- * `NgModuleRef` provides access to the NgModule Instance as well other objects related to this
- * NgModule Instance.
  *
  * @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;
 }

packages/core/src/linker/view_ref.ts

@@ -10,12 +10,9 @@ import {ApplicationRef} from '../application_ref';
 import {ChangeDetectorRef} from '../change_detection/change_detector_ref';
 
 /**
- * Represents an Angular [view](guide/glossary#view),
+ * Represents an Angular [view](guide/glossary#view "Definition").
- * 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).
  *
- * @see `EmbeddedViewRef`
+ * @see {@link ChangeDetectorRef#usage-notes Change detection usage}
  *
  * @publicApi
  */

packages/core/src/metadata/directives.ts

@@ -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
+   * When present, this directive/component is ignored by the AOT compiler.
-   * compiled using JIT.
+   * It remains in distributed code, and the JIT compiler attempts to compile it
-   *
+   * at run time, in the browser.
-   * This exists to support future Ivy work and has no effect currently.
+   * 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,

packages/core/src/metadata/ng_module.ts

@@ -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.
+ * @see [Deprecations](guide/deprecations#modulewithproviders-type-without-a-generic)
- *
- * Note that using ModuleWithProviders without a generic type is deprecated.
- * The generic will become required in a future version of Angular.
  *
  * @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
+   * When present, this module is ignored by the AOT compiler.
-   * using JIT.
+   * It remains in distributed code, and the JIT compiler attempts to compile it
-   *
+   * at run time, in the browser.
-   * This exists to support future Ivy work and has no effect currently.
+   * To ensure the correct behavior, the app must import `@angular/compiler`.
    */
   jit?: true;
 }