From 58f3596f7622944c5e91675630f3bc71a9e838f8 Mon Sep 17 00:00:00 2001
From: tomass22 <dominanthat@gmail.com>
Date: Sun, 9 Aug 2026 10:39:32 +0000
Subject: [PATCH] doc: document --trace-promises

`--trace-promises` has been available since v21.5.0 but was never added
to the CLI documentation. Instead it was added to the list of
intentionally undocumented options in
test/parallel/test-process-env-allowed-flags-are-documented.js.

Unlike the other entries in that list, which are either legacy no-ops or
internal-only debugging switches, `--trace-promises` is a user-facing
diagnostic flag that is allowed in NODE_OPTIONS, and its siblings
`--trace-env`, `--trace-uncaught` and `--trace-warnings` are all
documented.

Document it in doc/api/cli.md, regenerate doc/node.1 accordingly, and
drop the two exemptions from the test.

Assisted-by: Claude Opus 5 (1M context)
Signed-off-by: tomass22 <dominanthat@gmail.com>
---
 doc/api/cli.md                                     | 14 ++++++++++++++
 doc/node.1                                         |  8 ++++++++
 ...est-process-env-allowed-flags-are-documented.js |  2 --
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 2052f010f4b..563e97fcef3 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -3323,6 +3323,19 @@ added:
 Prints a stack trace whenever an environment is exited proactively,
 i.e. invoking `process.exit()`.
 
+### `--trace-promises`
+
+<!-- YAML
+added:
+ - v21.5.0
+ - v20.12.0
+-->
+
+Prints a stack trace to stderr whenever a promise is created or resolved. Each
+promise is given an identifier, and the identifier of the parent promise is
+also printed when the promise is derived from another one. Promise `before` and
+`after` hook events are not traced, to reduce the amount of output.
+
 ### `--trace-require-module=mode`
 
 <!-- YAML
@@ -3982,6 +3995,7 @@ one is included in the list below.
 * `--trace-event-file-pattern`
 * `--trace-events-enabled`
 * `--trace-exit`
+* `--trace-promises`
 * `--trace-require-module`
 * `--trace-sigint`
 * `--trace-sync-io`
diff --git a/doc/node.1 b/doc/node.1
index 1098bcff047..74cf7ca97d6 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -1608,6 +1608,12 @@ Enables the collection of trace event tracing information.
 Prints a stack trace whenever an environment is exited proactively,
 i.e. invoking \fBprocess.exit()\fR.
 .
+.It Fl -trace-promises
+Prints a stack trace to stderr whenever a promise is created or resolved. Each
+promise is given an identifier, and the identifier of the parent promise is
+also printed when the promise is derived from another one. Promise \fBbefore\fR and
+\fBafter\fR hook events are not traced, to reduce the amount of output.
+.
 .It Fl -trace-require-module Ns = Ns Ar mode
 Prints information about usage of Loading ECMAScript modules using \fBrequire()\fR.
 When \fBmode\fR is \fBall\fR, all usage is printed. When \fBmode\fR is \fBno-node-modules\fR, usage
@@ -2216,6 +2222,8 @@ one is included in the list below.
 .It
 \fB--trace-exit\fR
 .It
+\fB--trace-promises\fR
+.It
 \fB--trace-require-module\fR
 .It
 \fB--trace-sigint\fR
diff --git a/test/parallel/test-process-env-allowed-flags-are-documented.js b/test/parallel/test-process-env-allowed-flags-are-documented.js
index 6028bbab787..aff9b19817d 100644
--- a/test/parallel/test-process-env-allowed-flags-are-documented.js
+++ b/test/parallel/test-process-env-allowed-flags-are-documented.js
@@ -139,8 +139,6 @@ assert(undocumented.delete('--no-node-snapshot'));
 assert(undocumented.delete('--loader'));
 assert(undocumented.delete('--verify-base-objects'));
 assert(undocumented.delete('--no-verify-base-objects'));
-assert(undocumented.delete('--trace-promises'));
-assert(undocumented.delete('--no-trace-promises'));
 
 // Remove negated versions of the flags.
 for (const flag of undocumented) {