Update docs for Swift debugging (#33483)

Release Notes:

- N/A *or* Added/Fixed/Improved ...

docs/src/debugger.md

@@ -18,7 +18,7 @@ Zed supports a variety of debug adapters for different programming languages out
 
 - Python ([debugpy](https://github.com/microsoft/debugpy.git)): Provides debugging capabilities for Python applications, supporting features like remote debugging, multi-threaded debugging, and Django/Flask application debugging.
 
-- LLDB ([CodeLLDB](https://github.com/vadimcn/codelldb.git)): A powerful debugger for Rust, C, C++, and some other compiled languages, offering low-level debugging features and support for Apple platforms. (For Swift, [see below](#swift).)
+- LLDB ([CodeLLDB](https://github.com/vadimcn/codelldb.git)): A powerful debugger for Rust, C, C++, and some other compiled languages, offering low-level debugging features and support for Apple platforms.
 
 - GDB ([GDB](https://sourceware.org/gdb/)): The GNU Debugger, which supports debugging for multiple programming languages including C, C++, Go, and Rust, across various platforms.
 
@@ -376,21 +376,6 @@ You might find yourself needing to connect to an existing instance of Delve that
 
 In such case Zed won't spawn a new instance of Delve, as it opts to use an existing one. The consequence of this is that _there will be no terminal_ in Zed; you have to interact with the Delve instance directly, as it handles stdin/stdout of the debuggee.
 
-#### Swift
-
-Out-of-the-box support for debugging Swift programs will be provided by the Swift extension for Zed in the near future. In the meantime, the builtin CodeLLDB adapter can be used with some customization. On macOS, you'll need to locate the `lldb-dap` binary that's part of Apple's LLVM toolchain by running `which lldb-dap`, then point Zed to it in your project's `.zed/settings.json`:
-
-```json
-{
-  "dap": {
-    "CodeLLDB": {
-      "binary": "/Applications/Xcode.app/Contents/Developer/usr/bin/lldb-dap", // example value, may vary between systems
-      "args": []
-    }
-  }
-}
-```
-
 #### Ruby
 
 To run a ruby task in the debugger, you will need to configure it in the `.zed/debug.json` file in your project. We don't yet have automatic detection of ruby tasks, nor do we support connecting to an existing process.

docs/src/languages/swift.md

@@ -5,7 +5,34 @@ Report issues to: [https://github.com/zed-extensions/swift/issues](https://githu
 
 - Tree-sitter: [alex-pinkus/tree-sitter-swift](https://github.com/alex-pinkus/tree-sitter-swift)
 - Language Server: [swiftlang/sourcekit-lsp](https://github.com/swiftlang/sourcekit-lsp)
+- Debug Adapter: [`lldb-dap`](https://github.com/swiftlang/llvm-project/blob/next/lldb/tools/lldb-dap/README.md)
 
-## Configuration
+## Language Server Configuration
 
 You can modify the behavior of SourceKit LSP by creating a `.sourcekit-lsp/config.json` under your home directory or in your project root. See [SourceKit-LSP configuration file](https://github.com/swiftlang/sourcekit-lsp/blob/main/Documentation/Configuration%20File.md) for complete documentation.
+
+## Debugging
+
+The Swift extension provides a debug adapter for debugging Swift code.
+Zed's name for the adapter (in the UI and `debug.json`) is `Swift`, and under the hood it uses [`lldb-dap`](https://github.com/swiftlang/llvm-project/blob/next/lldb/tools/lldb-dap/README.md), as provided by the Swift toolchain.
+The extension tries to find an `lldb-dap` binary using `swiftly`, using `xcrun`, and by searching `$PATH`, in that order of preference.
+The extension doesn't attempt to download `lldb-dap` if it's not found.
+
+### Examples
+
+#### Build and debug a Swift binary
+
+```json
+[
+  {
+    "label": "Debug Swift",
+    "build": {
+      "command": "swift",
+      "args": ["build"]
+    },
+    "program": "$ZED_WORKTREE_ROOT/swift-app/.build/arm64-apple-macosx/debug/swift-app",
+    "request": "launch",
+    "adapter": "Swift"
+  }
+]
+```