doc: document non-node_modules-only runtime deprecation

We already have this special kind of runtime deprecation for
Buffer constructors which does not fit into the original
description of runtiem deprecations. Document this kind of
deprecation separately.

PR-URL: #50748
Reviewed-By: Geoffrey Booth <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Benjamin Gruenbaum <[email protected]>

Author: joyeecheung

doc/api/deprecations.md

@@ -10,10 +10,11 @@ Node.js APIs might be deprecated for any of the following reasons:
 * An improved alternative API is available.
 * Breaking changes to the API are expected in a future major release.
 
-Node.js uses three kinds of Deprecations:
+Node.js uses four kinds of deprecations:
 
 * Documentation-only
-* Runtime
+* Application (non-`node_modules` code only)
+* Runtime (all code)
 * End-of-Life
 
 A Documentation-only deprecation is one that is expressed only within the
@@ -25,10 +26,17 @@ deprecations below. Documentation-only deprecations that support that flag
 are explicitly labeled as such in the
 [list of Deprecated APIs](#list-of-deprecated-apis).
 
-A Runtime deprecation will, by default, generate a process warning that will
-be printed to `stderr` the first time the deprecated API is used. When the
-[`--throw-deprecation`][] command-line flag is used, a Runtime deprecation will
-cause an error to be thrown.
+An Application deprecation for only non-`node_modules` code will, by default,
+generate a process warning that will be printed to `stderr` the first time
+the deprecated API is used in code that's not loaded from `node_modules`.
+When the [`--throw-deprecation`][] command-line flag is used, a Runtime
+deprecation will cause an error to be thrown. When
+[`--pending-deprecation`][] is used, warnings will also be emitted for
+code loaded from `node_modules`.
+
+A runtime deprecation for all code is similar to the runtime deprecation
+for non-`node_modules` code, except that it also emits a warning for
+code loaded from `node_modules`.
 
 An End-of-Life deprecation is used when functionality is or will soon be removed
 from Node.js.
@@ -140,7 +148,7 @@ changes:
     description: Documentation-only deprecation.
 -->
 
-Type: Runtime (supports [`--pending-deprecation`][])
+Type: Application (non-`node_modules` code only)
 
 The `Buffer()` function and `new Buffer()` constructor are deprecated due to
 API usability issues that can lead to accidental security issues.