doc: document common warning types

Fixes: #24987 Signed-off-by: James M Snell <[email protected]> PR-URL: #36713 Reviewed-By: Rich Trott <[email protected]>
nodejs · May 1, 2021 · bcca52c · bcca52c
1 parent 97faeeb
commit bcca52c
Showing 1 changed file with 24 additions and 0 deletions.
diff --git a/doc/api/process.md b/doc/api/process.md
@@ -460,6 +460,29 @@ The `*-deprecation` command-line flags only affect warnings that use the name
 See the [`process.emitWarning()`][process_emit_warning] method for issuing
 custom or application-specific warnings.
 
+#### Node.js warning names
+
+There are no strict guidelines for warning types (as identified by the `name`
+property) emitted by Node.js. New types of warnings can be added at any time.
+A few of the warning types that are most common include:
+
+* `'DeprecationWarning'` - Indicates use of a deprecated Node.js API or feature.
+  Such warnings must include a `'code'` property identifying the
+  [deprecation code][].
+* `'ExperimentalWarning'` - Indicates use of an experimental Node.js API or
+  feature. Such features must be used with caution as they may change at any
+  time and are not subject to the same strict semantic-versioning and long-term
+  support policies as supported features.
+* `'MaxListenersExceededWarning'` - Indicates that too many listeners for a
+  given event have been registered on either an `EventEmitter` or `EventTarget`.
+  This is often an indication of a memory leak.
+* `'TimeoutOverflowWarning'` - Indicates that a numeric value that cannot fit
+  within a 32-bit signed integer has been provided to either the `setTimeout()`
+  or `setInterval()` functions.
+* `'UnsupportedWarning'` - Indicates use of an unsupported option or feature
+  that will be ignored rather than treated as an error. One example is use of
+  the HTTP response status message when using the HTTP/2 compatibility API.
+
 ### Signal events
 
 <!--type=event-->
@@ -2654,6 +2677,7 @@ cases:
 [`subprocess.kill()`]: child_process.md#child_process_subprocess_kill_signal
 [`v8.setFlagsFromString()`]: v8.md#v8_v8_setflagsfromstring_flags
 [debugger]: debugger.md
+[deprecation code]: deprecations.md
 [note on process I/O]: process.md#process_a_note_on_process_i_o
 [process.cpuUsage]: #process_process_cpuusage_previousvalue
 [process_emit_warning]: #process_process_emitwarning_warning_type_code_ctor