docs: edit injectable decorator doc (#34218)

PR Close #34218

packages/core/src/di/injectable.ts

@@ -65,13 +65,13 @@ export interface InjectableDecorator {
 export interface Injectable {
   /**
    * Determines which injectors will provide the injectable,
-   * by either associating it with an @NgModule or other `InjectorType`,
+   * by either associating it with an `@NgModule` or other `InjectorType`,
-   * or by specifying that this injectable should be provided in the:
+   * or by specifying that this injectable should be provided in one of the following injectors:
-   * - 'root' injector, which will be the application-level injector in most apps.
+   * - 'root' : The application-level injector in most apps.
-   * - 'platform' injector, which would be the special singleton platform injector shared by all
+   * - 'platform' : A special singleton platform injector shared by all
    * applications on the page.
-   * - 'any' injector, which would be the injector which receives the resolution. (Note this only
+   * - 'any' : The NgModule injector that receives the resolution.
-   * works on NgModule Injectors and not on Element Injector)
+   *
    */
   providedIn?: Type<any>|'root'|'platform'|'any'|null;
 }

packages/core/src/di/injector.ts

@@ -32,12 +32,20 @@ export function INJECTOR_IMPL__POST_R3__(
 export const INJECTOR_IMPL = INJECTOR_IMPL__PRE_R3__;
 
 /**
- * Concrete injectors implement this interface.
+ * Concrete injectors implement this interface. Injectors are configured
+ * with [providers](guide/glossary#provider) that associate
+ * dependencies of various types with [injection tokens](guide/glossary#di-token).
  *
- * For more details, see the ["Dependency Injection Guide"](guide/dependency-injection).
+ * @see ["DI Providers"](guide/dependency-injection-providers).
+ * @see `StaticProvider`
  *
  * @usageNotes
- * ### Example
+ *
+ *  The following example creates a service injector instance.
+ *
+ * {@example core/di/ts/provider_spec.ts region='ConstructorProvider'}
+ *
+ * ### Usage example
  *
  * {@example core/di/ts/injector_spec.ts region='Injector'}
  *
@@ -69,16 +77,21 @@ export abstract class Injector {
    */
   static create(providers: StaticProvider[], parent?: Injector): Injector;
 
+  /**
+   * Creates a new injector instance that provides one or more dependencies,
+   * according to a given type or types of `StaticProvider`.
+   *
+   * @param options An object with the following properties:
+   * * `providers`: An array of providers of the [StaticProvider type](api/core/StaticProvider).
+   * * `parent`: (optional) A parent injector.
+   * * `name`: (optional) A developer-defined identifying name for the new injector.
+   *
+   * @returns The new injector instance.
+   *
+   */
   static create(options: {providers: StaticProvider[], parent?: Injector, name?: string}): Injector;
 
-  /**
+
-   * Create a new Injector which is configure using `StaticProvider`s.
-   *
-   * @usageNotes
-   * ### Example
-   *
-   * {@example core/di/ts/provider_spec.ts region='ConstructorProvider'}
-   */
   static create(
       options: StaticProvider[]|{providers: StaticProvider[], parent?: Injector, name?: string},
       parent?: Injector): Injector {

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

@@ -247,8 +247,11 @@ export interface FactoryProvider extends FactorySansProvider {
 }
 
 /**
- * Describes how the `Injector` should be configured as static (that is, without reflection).
+ * Describes how an `Injector` should be configured as static (that is, without reflection).
- * @see ["Dependency Injection Guide"](guide/dependency-injection).
+ * A static provider provides tokens to an injector for various types of dependencies.
+ *
+ * @see [Injector.create()](/api/core/Injector#create).
+ * @see ["Dependency Injection Guide"](guide/dependency-injection-providers).
  *
  * @publicApi
  */