docs(core): deprecate providedIn: NgModule and providedIn: 'any' (#…

…47616)

This commit deprecates the above two forms of `providedIn`.

DEPRECATED:

- The ability to pass an `NgModule` to the `providedIn` option for
`@Injectable` and `InjectionToken` is now deprecated.

`providedIn: NgModule` was intended to be a tree-shakable alternative to
NgModule providers. It does not have wide usage, and in most cases is used
incorrectly, in circumstances where `providedIn: 'root'` should be
preferred. If providers should truly be scoped to a specific NgModule, use
`NgModule.providers` instead.

- The ability to set `providedIn: 'any'` for an `@Injectable` or
`InjectionToken` is now deprecated.

`providedIn: 'any'` is an option with confusing semantics and is almost
never used apart from a handful of esoteric cases internal to the framework.

PR Close #47616

aio/content/guide/deprecations.md

@@ -35,6 +35,7 @@ v11 - v14
 v12 - v15
 v13 - v16
 v14 - v17
+v15 - v18
 -->
 
 | Area                                | API or Feature                                                                                             | May be removed in        |
@@ -57,6 +58,7 @@ v14 - v17
 | `@angular/core`                     | [`ComponentFactory`](#core)                                                                                | <!-- v13 --> v16         |
 | `@angular/core`                     | [`ComponentFactoryResolver`](#core)                                                                        | <!-- v13 --> v16         |
 | `@angular/core`                     | [`CompilerOptions.useJit and CompilerOptions.missingTranslation config options`](#core)                    | <!-- v13 --> v16         |
+| `@angular/core`                     | NgModule and `'any'` options for [`providedIn`](#core) | <!-- v15 --> v17 |
 | `@angular/platform-browser-dynamic` | [`JitCompilerFactory`](#platform-browser-dynamic)                                                          | <!-- v13 --> v16         |
 | `@angular/platform-browser-dynamic` | [`RESOURCE_CACHE_PROVIDER`](#platform-browser-dynamic)                                                     | <!-- v13 --> v16         |
 | `@angular/forms`                    | [`ngModel` with reactive forms](#ngmodel-reactive)                                                         | <!--  v6 --> v11         |
@@ -141,6 +143,8 @@ In the [API reference section](api) of this site, deprecated APIs are indicated
 | [`ComponentFactory`](api/core/ComponentFactory)                                                            | Use non-factory based framework APIs.                                                                                                                             | v13                   | Since Ivy, Component factories are not required. Angular provides other APIs where Component classes can be used directly.                                                                                                                                         |
 | [`ComponentFactoryResolver`](api/core/ComponentFactoryResolver)                                            | Use non-factory based framework APIs.                                                                                                                             | v13                   | Since Ivy, Component factories are not required, thus there is no need to resolve them.                                                                                                                                                                            |
 | [`CompilerOptions.useJit and CompilerOptions.missingTranslation config options`](api/core/CompilerOptions) | none                                                                                                                                                              | v13                   | Since Ivy, those config options are unused, passing them has no effect.                                                                                                                                                                                            |
+| [`providedIn`](api/core/Injectable#providedIn) with NgModule | Prefer `'root'` providers, or use NgModule `providers` if scoping to an NgModule is necessary | v15 | none |
+| [`providedIn: 'any'`](api/core/Injectable#providedIn) | none | v15 | This option has confusing semantics and nearly zero usage. |
 
 <a id="testing"></a>
 

packages/core/src/di/injectable.ts

@@ -64,7 +64,8 @@ export interface Injectable {
   /**
    * Determines which injectors will provide the injectable.
    *
-   * - `Type<any>` - associates the injectable with an `@NgModule` or other `InjectorType`,
+   * - `Type<any>` - associates the injectable with an `@NgModule` or other `InjectorType`. This
+   * option is DEPRECATED.
    * - 'null' : Equivalent to `undefined`. The injectable is not provided in any scope automatically
    * and must be added to a `providers` array of an [@NgModule](api/core/NgModule#providers),
    * [@Component](api/core/Directive#providers) or [@Directive](api/core/Directive#providers).
@@ -75,7 +76,7 @@ export interface Injectable {
    * - 'platform' : A special singleton platform injector shared by all
    * applications on the page.
    * - 'any' : Provides a unique instance in each lazy loaded module while all eagerly loaded
-   * modules share one instance.
+   * modules share one instance. This option is DEPRECATED.
    *
    */
   providedIn?: Type<any>|'root'|'platform'|'any'|null;

packages/core/src/di/injection_token.ts

@@ -35,8 +35,11 @@ import {ɵɵdefineInjectable} from './interface/defs';
  * As you can see in the Tree-shakable InjectionToken example below.
  *
  * Additionally, if a `factory` is specified you can also specify the `providedIn` option, which
- * overrides the above behavior and marks the token as belonging to a particular `@NgModule`. As
- * mentioned above, `'root'` is the default value for `providedIn`.
+ * overrides the above behavior and marks the token as belonging to a particular `@NgModule` (note:
+ * this option is now deprecated). As mentioned above, `'root'` is the default value for
+ * `providedIn`.
+ *
+ * The `providedIn: NgModule` and `providedIn: 'any'` options are deprecated.
  *
  * @usageNotes
  * ### Basic Examples