From 3532f5587c9ed3610fb52d885d6ebb9864e420a8 Mon Sep 17 00:00:00 2001
From: Chengzhong Wu <chengzhong.wcz@alibaba-inc.com>
Date: Thu, 18 Jan 2024 14:30:33 +0800
Subject: [PATCH] doc: add notes on inspector breakpoints

Setting breakpoints with a same-thread inspector session should be
avoided because the program being attached and paused is exactly the
debugger itself. A worker thread inspector session or a debugger
program should be used if breakpoints are needed.

PR-URL: https://github.com/nodejs/node/pull/51417
Fixes: https://github.com/nodejs/node/issues/51397
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
---
 doc/api/inspector.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/doc/api/inspector.md b/doc/api/inspector.md
index 7d91377fc0040e..05178153ceb630 100644
--- a/doc/api/inspector.md
+++ b/doc/api/inspector.md
@@ -74,6 +74,9 @@ session.on('inspectorNotification', (message) => console.log(message.method));
 // Debugger.resumed
 ```
 
+> **Caveat** Breakpoints with same-thread session is not recommended, see
+> [support of breakpoints][].
+
 It is also possible to subscribe only to notifications with specific method:
 
 #### Event: `<inspector-protocol-method>`;
@@ -98,6 +101,9 @@ session.on('Debugger.paused', ({ params }) => {
 // [ '/the/file/that/has/the/breakpoint.js:11:0' ]
 ```
 
+> **Caveat** Breakpoints with same-thread session is not recommended, see
+> [support of breakpoints][].
+
 #### `session.connect()`
 
 <!-- YAML
@@ -247,6 +253,9 @@ session.on('inspectorNotification', (message) => console.log(message.method));
 // Debugger.resumed
 ```
 
+> **Caveat** Breakpoints with same-thread session is not recommended, see
+> [support of breakpoints][].
+
 It is also possible to subscribe only to notifications with specific method:
 
 #### Event: `<inspector-protocol-method>`;
@@ -271,6 +280,9 @@ session.on('Debugger.paused', ({ params }) => {
 // [ '/the/file/that/has/the/breakpoint.js:11:0' ]
 ```
 
+> **Caveat** Breakpoints with same-thread session is not recommended, see
+> [support of breakpoints][].
+
 #### `session.connect()`
 
 <!-- YAML
@@ -476,10 +488,27 @@ Blocks until a client (existing or connected later) has sent
 
 An exception will be thrown if there is no active inspector.
 
+## Support of breakpoints
+
+The Chrome DevTools Protocol [`Debugger` domain][] allows an
+`inspector.Session` to attach to a program and set breakpoints to step through
+the codes.
+
+However, setting breakpoints with a same-thread `inspector.Session`, which is
+connected by [`session.connect()`][], should be avoided as the program being
+attached and paused is exactly the debugger itself. Instead, try connect to the
+main thread by [`session.connectToMainThread()`][] and set breakpoints in a
+worker thread, or connect with a [Debugger][] program over WebSocket
+connection.
+
 [CPU Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/Profiler
 [Chrome DevTools Protocol Viewer]: https://chromedevtools.github.io/devtools-protocol/v8/
+[Debugger]: debugger.md
 [Heap Profiler]: https://chromedevtools.github.io/devtools-protocol/v8/HeapProfiler
 [`'Debugger.paused'`]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger#event-paused
+[`Debugger` domain]: https://chromedevtools.github.io/devtools-protocol/v8/Debugger
 [`inspector.close()`]: #inspectorclose
 [`session.connect()`]: #sessionconnect
+[`session.connectToMainThread()`]: #sessionconnecttomainthread
 [security warning]: cli.md#warning-binding-inspector-to-a-public-ipport-combination-is-insecure
+[support of breakpoints]: #support-of-breakpoints