From ba10f452ee96756b19000d847d6214603ae460ba Mon Sep 17 00:00:00 2001
From: cola119 <kohei.ueno119@gmail.com>
Date: Sun, 5 May 2024 22:23:15 +0900
Subject: [PATCH] Update document on Node.js debugger

---
 doc/api/cli.md      |  6 ++++++
 doc/api/debugger.md | 19 +++++++++++++++----
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 95871888de726e..4ed2d8653c8d63 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1241,6 +1241,7 @@ Activate inspector on `host:port`. Default is `127.0.0.1:9229`.
 V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug
 and profile Node.js instances. The tools attach to Node.js instances via a
 tcp port and communicate using the [Chrome DevTools Protocol][].
+See [V8 Inspector integration for Node.js][] for further explanation on Node.js debugger.
 
 <!-- Anchor to make sure old links find a target -->
 
@@ -1271,6 +1272,8 @@ added: v7.6.0
 Activate inspector on `host:port` and break at start of user script.
 Default `host:port` is `127.0.0.1:9229`.
 
+See [V8 Inspector integration for Node.js][] for further explanation on Node.js debugger.
+
 ### `--inspect-port=[host:]port`
 
 <!-- YAML
@@ -1301,6 +1304,8 @@ added: REPLACEME
 Activate inspector on `host:port` and wait for debugger to be attached.
 Default `host:port` is `127.0.0.1:9229`.
 
+See [V8 Inspector integration for Node.js][] for further explanation on Node.js debugger.
+
 ### `-i`, `--interactive`
 
 <!-- YAML
@@ -3137,6 +3142,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [ShadowRealm]: https://github.com/tc39/proposal-shadowrealm
 [Source Map]: https://sourcemaps.info/spec.html
 [Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
+[V8 Inspector integration for Node.js]: debugger.md#v8-inspector-integration-for-nodejs
 [V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
 [V8 code cache]: https://v8.dev/blog/code-caching-for-devs
 [`"type"`]: packages.md#type
diff --git a/doc/api/debugger.md b/doc/api/debugger.md
index f4543b99ca619e..03e9cd9185027e 100644
--- a/doc/api/debugger.md
+++ b/doc/api/debugger.md
@@ -234,10 +234,21 @@ V8 Inspector can be enabled by passing the `--inspect` flag when starting a
 Node.js application. It is also possible to supply a custom port with that flag,
 e.g. `--inspect=9222` will accept DevTools connections on port 9222.
 
-Using the `--inspect` flag will execute the code immediately before debugger
-is connected. This could be problematic if you intend to debug the code from the beginning.
-In such cases, you can use the `--inspect-wait` flag instead, which waits for debugger to be attached,
-or the `--inspect-brk` flag to break on the first line of the code.
+Using the `--inspect` flag will execute the code immediately before debugger is connected.
+This means that the code will start running before you can start debugging, which might
+not be ideal if you want to debug from the very beginning.
+
+In such cases, you have two alternatives:
+
+1. `--inspect-wait` flag: This flag will wait for debugger to be attached before executing the code.
+   This allows you to start debugging right from the beginning of the execution.
+2. `--inspect-brk` flag: Unlike `--inspect`, this flag will break on the first line of the code
+   as soon as debugger is attached. This is useful when you want to debug the code step by step
+   from the very beginning, without any code execution prior to debugging.
+
+So, when deciding between `--inspect`, `--inspect-wait`, and `--inspect-brk`, consider whether you want
+the code to start executing immediately, wait for debugger to be attached before execution,
+or break on the first line for step-by-step debugging.
 
 ```console
 $ node --inspect index.js