From a9d99d83475d095440efeccb4947231418765d7a Mon Sep 17 00:00:00 2001
From: Piotr Osiewicz <24362066+osiewicz@users.noreply.github.com>
Date: Tue, 3 Jun 2025 16:35:35 +0200
Subject: [PATCH] docs: Improve docs for debugger (around breakpoints and doc
 structure) (#31962)

Closes #ISSUE

Release Notes:

- N/A
---
 docs/src/debugger.md | 164 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 137 insertions(+), 27 deletions(-)

diff --git a/docs/src/debugger.md b/docs/src/debugger.md
index d23de9542c..1a3507fae3 100644
--- a/docs/src/debugger.md
+++ b/docs/src/debugger.md
@@ -34,7 +34,16 @@ For more advanced use cases, you can create debug configurations by directly edi
 
 You can then use the `New Session Modal` to select a configuration and start debugging.
 
-### Configuration
+### Launching & Attaching
+
+Zed debugger offers two ways to debug your program; you can either _launch_ a new instance of your program or _attach_ to an existing process.
+Which one you choose depends on what you are trying to achieve.
+
+When launching a new instance, Zed (and the underlying debug adapter) can often do a better job at picking up the debug information compared to attaching to an existing process, since it controls the lifetime of a whole program. Running unit tests or a debug build of your application is a good use case for launching.
+
+Compared to launching, attaching to an existing process might seem inferior, but that's far from truth; there are cases where you cannot afford to restart your program, because e.g. the bug is not reproducible outside of a production environment or some other circumstances.
+
+## Configuration
 
 While configuration fields are debug adapter-dependent, most adapters support the following fields:
 
@@ -58,22 +67,91 @@ While configuration fields are debug adapter-dependent, most adapters support th
 ]
 ```
 
-#### Tasks
-
 All configuration fields support task variables. See [Tasks Variables](./tasks.md#variables)
 
-Zed also allows embedding a task that is run before the debugger starts. This is useful for setting up the environment or running any necessary setup steps before the debugger starts.
+### Build tasks
 
-See an example [here](#build-binary-then-debug)
-
-#### Python Examples
-
-##### Python Active File
+Zed also allows embedding a Zed task in a `build` field that is run before the debugger starts. This is useful for setting up the environment or running any necessary setup steps before the debugger starts.
 
 ```json
 [
   {
-    "label": "Active File",
+    "label": "Build Binary",
+    "adapter": "CodeLLDB",
+    "program": "path_to_program",
+    "request": "launch",
+    "build": {
+      "command": "make",
+      "args": ["build", "-j8"]
+    }
+  }
+]
+```
+
+Build tasks can also refer to the existing tasks by unsubstituted label:
+
+```json
+[
+  {
+    "label": "Build Binary",
+    "adapter": "CodeLLDB",
+    "program": "path_to_program",
+    "request": "launch",
+    "build": "my build task" // Or "my build task for $ZED_FILE"
+  }
+]
+```
+
+### Automatic scenario creation
+
+Given a Zed task, Zed can automatically create a scenario for you. Automatic scenario creation also powers our scenario creation from gutter.
+Automatic scenario creation is currently supported for Rust, Go and Python. Javascript/TypeScript support being worked on.
+
+### Example Configurations
+
+#### JavaScript
+
+##### Debug Active File
+
+```json
+[
+  {
+    "label": "Debug with node",
+    "adapter": "JavaScript",
+    "program": "$ZED_FILE",
+    "request": "launch",
+    "console": "integratedTerminal",
+    "type": "pwa-node"
+  }
+]
+```
+
+##### Attach debugger to a server running in web browser (`npx serve`)
+
+Given an externally-ran web server (e.g. with `npx serve` or `npx live-server`) one can attach to it and open it with a browser.
+
+```json
+[
+  {
+    "label": "Inspect ",
+    "adapter": "JavaScript",
+    "type": "pwa-chrome",
+    "request": "launch",
+    "url": "http://localhost:5500", // Fill your URL here.
+    "program": "$ZED_FILE",
+    "webRoot": "${ZED_WORKTREE_ROOT}"
+  }
+]
+```
+
+#### Python
+
+##### Debug Active File
+
+```json
+[
+  {
+    "label": "Python Active File",
     "adapter": "Debugpy",
     "program": "$ZED_FILE",
     "request": "launch"
@@ -85,16 +163,20 @@ See an example [here](#build-binary-then-debug)
 
 For a common Flask Application with a file structure similar to the following:
 
-- .venv/
-- app/
-  - **init**.py
-  - **main**.py
-  - routes.py
-- templates/
-  - index.html
-- static/
-  - style.css
-- requirements.txt
+```
+.venv/
+app/
+  init.py
+  main.py
+  routes.py
+templates/
+  index.html
+static/
+  style.css
+requirements.txt
+```
+
+the following configuration can be used:
 
 ```json
 [
@@ -154,18 +236,46 @@ For a common Flask Application with a file structure similar to the following:
 ]
 ```
 
+#### TypeScript
+
+##### Attach debugger to a server running in web browser (`npx serve`)
+
+Given an externally-ran web server (e.g. with `npx serve` or `npx live-server`) one can attach to it and open it with a browser.
+
+```json
+[
+  {
+    "label": "Launch Chromee (TypeScript)",
+    "adapter": "JavaScript",
+    "type": "pwa-chrome",
+    "request": "launch",
+    "url": "http://localhost:5500",
+    "program": "$ZED_FILE",
+    "webRoot": "${ZED_WORKTREE_ROOT}",
+    "sourceMaps": true,
+    "build": {
+      "command": "npx",
+      "args": ["tsc"]
+    }
+  }
+]
+```
+
 ## Breakpoints
 
-Zed currently supports these types of breakpoints:
+To set a breakpoint, simply click next to the line number in the editor gutter.
+Breakpoints can be tweaked dependending on your needs; to access additional options of a given breakpoint, right-click on the breakpoint icon in the gutter and select the desired option.
+At present, you can:
 
-- Standard Breakpoints: Stop at the breakpoint when it's hit
-- Log Breakpoints: Output a log message instead of stopping at the breakpoint when it's hit
-- Conditional Breakpoints: Stop at the breakpoint when it's hit if the condition is met
-- Hit Breakpoints: Stop at the breakpoint when it's hit a certain number of times
+- Add a log to a breakpoint, which will output a log message whenever that breakpoint is hit.
+- Make the breakpoint conditional, which will only stop at the breakpoint when the condition is met. The syntax for conditions is adapter-specific.
+- Add a hit count to a breakpoint, which will only stop at the breakpoint after it's hit a certain number of times.
+- Disable a breakpoint, which will prevent it from being hit while leaving it visible in the gutter.
 
-Standard breakpoints can be toggled by left-clicking on the editor gutter or using the Toggle Breakpoint action. Right-clicking on a breakpoint or on a code runner symbol brings up the breakpoint context menu. This has options for toggling breakpoints and editing log breakpoints.
+Some debug adapters (e.g. CodeLLDB and JavaScript) will also _verify_ whether your breakpoints can be hit; breakpoints that cannot be hit are surfaced more prominently in the UI.
 
-Other kinds of breakpoints can be toggled/edited by right-clicking on the breakpoint icon in the gutter and selecting the desired option.
+All breakpoints enabled for a given project are also listed in "Breakpoints" item in your debugging session UI. From "Breakpoints" item in your UI you can also manage exception breakpoints.
+The debug adapter will then stop whenever an exception of a given kind occurs. Which exception types are supported depends on the debug adapter.
 
 ## Settings