swiftlang · matthewbastien · Jun 3, 2025 · May 28, 2025 · May 28, 2025 · May 29, 2025
@@ -64,7 +64,7 @@ If you'd like to return to using the released version of the extension you can u
 
 Occasionally, pre-release builds will be published to the VS Code Marketplace. You can switch to the pre-release version by clicking on the `Switch to Pre-Release Version` button in the Extensions View:
 
-![](userdocs/userdocs.docc/install-pre-release.png)
+![](userdocs/userdocs.docc/Resources/install-pre-release.png)
 
 Switching back to the release version can be done by clicking on the `Switch to Release Version` button.
 

@@ -0,0 +1,11 @@
+# Installing Pre-Release Builds
+
+Try out the latest updates by switching to the pre-release version.
+
+The Swift extension provides pre-release builds that can be used to test out unreleased features or get bug fixes before an official release can be published. Pre-release build numbers are always one minor version ahead of the most recent release.
+
+The "Switch to Pre-Release Version" button in the VS Code extensions view is used to install the latest pre-release builds:
+
+![](install-pre-release.png)
+
+A "Switch to Release Version" button will appear in its place that lets you go back to the official release.
@@ -1,6 +1,6 @@
 # Visual Studio Code Dev Containers
 
-Dev containers can be used as an easy way to develop when building for other platforms.
+Create reusable development environments using containers.
 
 [VS Code Dev Containers](https://code.visualstudio.com/docs/remote/containers) allows you to run your code and environment in a container. This is especially useful for Swift when developing on macOS and deploying to Linux. You can ensure there are no compatibility issues in Foundation when running your code. The extension also works with [GitHub Codespaces](https://github.com/features/codespaces) to allow you to write your code on the web.
 

@@ -0,0 +1,13 @@
+# Automatic Task Creation
+
+Tasks added for common operations with your Package.
+
+> 💡 Tip: Tasks use workflows common to all VS Code extensions. For more information see [the VS Code documentation for tasks](https://code.visualstudio.com/docs/editor/tasks).
+
+For workspaces that contain a **Package.swift** file, the Swift extension will add the following tasks:
+
+- **Build All**: Build all targets in the Package
+- **Build Debug <Executable>**: Each executable in a Package.swift get a task for building a debug build
+- **Build Release <Executable>**: Each executable in a Package.swift get a task for building a release build
+
+These tasks are available via the commands **Terminal ▸ Run Task...** and **Terminal ▸ Run Build Task...** in the command palette.
@@ -1,11 +1,11 @@
 # Debugging
 
-
+
+@Metadata {
+    @Available("Swift", introduced: "6.0")
+}
-
+
+@Metadata {
+    @Available("Swift", introduced: "6.0")
+}
-vscode-swift allows you to debug your Swift packages.
+Debug your Swift executables using LLDB.
 
-> Tip: Debugging works best when using a version of the Swift toolchain 6.0 or higher
+> 💡 Tip: Debugging workflows are common to all VS Code extensions. See the [VS Code documentation about testing](https://code.visualstudio.com/docs/debugtest/testing) for a more in-depth overview.
+>
+> Debugging works best when using a version of the Swift toolchain 6.0 or higher.
 
 When you open a Swift package (a directory containing a `Package.swift` file), the extension automatically generates build tasks and launch configurations for each executable within the package. Additionally, if the package includes tests, the extension creates a configuration specifically designed to run those tests. These configurations all leverage the CodeLLDB extension as the debugger of choice.
 
 Use the **Run > Start Debugging** menu item to run an executable and start debugging. If you have multiple launch configurations you can choose which launch configuration to use in the debugger view.
-
-Debugging uses workflows common to all VSCode extensions. For more information see https://code.visualstudio.com/docs/editor/debugging
@@ -0,0 +1,11 @@
+# Documentation Live Preview
+
+Show a live preview of your Swift documentation while editing.
+
+> Note: This feature is only available when using a Swift toolchain 6.2 or higher running on macOS or Linux.
+
+The Swift toolchain comes with a built-in documentation compiler called DocC that can be used to build documentation for your Swift code. This documentation can then be distributed to developers or other contributors. It's what we used to make the documentation for vscode-swift! You can learn more about DocC by reading [the documentation on the Swift organization's website](https://www.swift.org/documentation/docc/).
+
+The Swift extension for VS Code can show you a side-by-side live preview of your documentation as you edit it. This feature can be accessed via the Preview Swift Documentation button at the top right of an editor or with the `Swift: Preview Documentation` command in the command palette. This will open up a new editor pane with your rendered documentation:
+
+![An animation showing how to launch documentation live preview.](docc-live-preview.gif)
@@ -0,0 +1,13 @@
+# Language Features
+
+Language features to help you write Swift code.
+
+> 💡 Tip: Language features are common to all VS Code extensions. See the [VS Code documentation about navigating code](https://code.visualstudio.com/docs/editing/editingevolved) for a more in-depth overview.
+
+The Swift extension provides language features such as code completion and jump to definition via [SourceKit-LSP](https://github.com/apple/sourcekit-lsp).
+
+> ⚠️ Important: With Swift toolchains prior to 6.1 you will need to build your project at least once for SourceKit-LSP to function correcly. Whenever you add a new dependency to your project, make sure to rebuild it so that SourceKit-LSP can update its information.
+
+SourceKit-LSP provides background indexing in Swift toolchain 6.1 which will automatically index your project on startup. All indexing results are cached in the `.build/index-build` folder within your workspace.
+
+SourceKit-LSP can be configured via extension settings. See <doc:settings> for more information.
@@ -1,6 +1,6 @@
-# Project View
+# Swift Project View
 
-vscode-swift provides project view
+Navigate your Swift project.
 
 If your workspace contains a package, this extension will add a **Swift Project** view to the Explorer:
 

@@ -1,6 +1,16 @@
-# Test Coverage
+# Running and Debugging Tests
 
-vscode-swift provides mechanisms to see coverage of your tests.
+vscode-swift shows test results in the test explorer.
+
+> 💡 Tip: The Testing view is common to all VS Code extensions. See the [VS Code documentation about testing](https://code.visualstudio.com/docs/debugtest/testing) for a more in-depth overview.
+
+If your package contains tests then they can be viewed, run and debugged in the Test Explorer.
+
+![](test-explorer.png)
+
+Once your project is built, the Test Explorer will list all your tests. These tests are grouped by package, then test target, and finally, by XCTestCase class. From the Test Explorer, you can initiate a test run, debug a test run, and if a file has already been opened, you can jump to the source code for a test.
+
+## Run Tests with Coverage
 
 Test coverage is a measurement of how much of your code is tested by your tests. It defines how many lines of code were actually run when you ran your tests and how many were not. When a line of code is not run by your tests it will not have been tested and perhaps you need to extend your tests.
 

@@ -0,0 +1,58 @@
+# Commands
+
+Useful VS Code commands added by the Swift extension.
+
+> 💡 Tip: Commands can be accessed from the VS Code command palette which is common to all VS Code extensions. See the [VS Code documentation about the command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) for a more in-depth overview.
+
+The Swift extension adds the following commands, each prefixed with `"Swift: "` in the command palette.
+
+#### Configuration
+
+- **`Create New Project...`** - Create a new Swift project using a template. This opens a dialog to guide you through creating a new project structure.
+- **`Create New Swift File...`** - Create a new `.swift` file in the current workspace.
+- **`Select Toolchain...`** - Select the locally installed Swift toolchain (including Xcode toolchains on macOS) that you want to use Swift tools from.
+
+The following command is only available on macOS:
+
+- **`Select Target Platform...`** - An experimental command available in Swift 6.1 that offers code completion for iOS, tvOS, watchOS, and visionOS projects.
+
+#### Building and Debugging
+
+- **`Run Build`** - Run `swift build` for the package associated with the open file.
+- **`Debug Build`** - Run `swift build` with debugging enabled for the package associated with the open file, launching the binary and attaching the debugger.
+- **`Attach to Process...`** - Attach the debugger to an already running process for debugging.
+- **`Clean Build Folder`** - Clean the `.build` folder for the package associated with the open file, removing all previously built products.
+
+#### Dependency Management
+
+- **`Resolve Package Dependencies`** - Run `swift package resolve` on packages associated with the open file.
+- **`Update Package Dependencies`** - Run `swift package update` on packages associated with the open file.
+- **`Reset Package Dependencies`** - Run `swift package reset` on packages associated with the open file.
+- **`Add to Workspace`** - Add the current package to the active workspace in VS Code.
+- **`Clean Build`** - Run `swift package clean` on packages associated with the open file.
+- **`Open Package.swift`** - Open `Package.swift` for the package associated with the open file.
+- **`Use Local Version`** - Switch the package dependency to use a local version of the package instead of the remote repository version.
+- **`Edit Locally`** - Make the package dependency editable locally, allowing changes to the dependency to be reflected immediately.
+- **`Revert To Original Version`** - Revert the package dependency to its original, unedited state after local changes have been made.
+- **`View Repository`** - Open the external repository of the selected Swift package in a browser.
+
+#### Testing
+
+- **`Test: Run All Tests`** - Run all the tests across all test targes in the open project.
+- **`Test: Rerun Last Run`** - Perform the last test run again.
+- **`Test: Open Coverage`** - Open the last generated coverage report, if one exists.
+- **`Test: Run All Tests in Parallel`** - Run all tests in parallel. This action only affects XCTests. Swift-testing tests are parallel by default, and their parallelism [is controlled in code](https://developer.apple.com/documentation/testing/parallelization).
+
+#### Snippets and Scripts
+
+- **`Insert Function Comment`** - Insert a standard comment block for documenting a Swift function in the current file.
+- **`Run Swift Script`** - Run the currently open file, as a Swift script. The file must not be part of a build target. If the file has not been saved it will save it to a temporary file so it can be run.
+- **`Run Swift Snippet`** - If the currently open file is a Swift snippet then run it.
+- **`Debug Swift Snippet`** - If the currently open file is a Swift snippet then debug it.
+
+#### Diagnostics
+
+- **`Capture Diagnostic Bundle`** - Capture a diagnostic bundle from VS Code, containing logs and information to aid in troubleshooting Swift-related issues.
+- **`Clear Diagnostics Collection`** - Clear all collected diagnostics in the current workspace to start fresh.
+- **`Restart LSP Server`** - Restart the Swift Language Server Protocol (LSP) server for the current workspace.
+- **`Re-Index Project`** - Force a re-index of the project to refresh code completion and symbol navigation support.
@@ -2,7 +2,9 @@
 
 vscode-swift provides various settings to configure its behaviour.
 
-The Visual Studio Code Swift extension comes with a number of settings you can use to control how it works. Detailed descriptions of each setting is provided in the extension settings page.
+> 💡 Tip: The Settings Editor is common to all VS Code extensions. See the [documentation about personalizing VS Code](https://code.visualstudio.com/docs/getstarted/personalize-vscode) for a more in-depth overview.
+
+The Swift extension comes with a number of settings you can use to control how it works. Detailed descriptions of each setting are provided in the extension settings page.
 
 This document outlines useful configuration options not covered by the settings descriptions in the extension settings page.
 
@@ -65,13 +67,15 @@ Alternatively you can specfiy which specific command the arguments should apply
 
 ## SourceKit-LSP
 
-[SourceKit-LSP](https://github.com/apple/sourcekit-lsp) is the language server used by the the Swift extension to provide symbol completion, jump to definition etc. It is developed by Apple to provide Swift and C language support for any editor that supports the Language Server Protocol.
+[SourceKit-LSP](https://github.com/apple/sourcekit-lsp) is the language server used by the the Swift extension to provide symbol completion, jump to definition, etc. It is developed by Apple to provide Swift and C language support for any editor that supports the Language Server Protocol.
 
 ### Background Indexing
 
-If you're using a nightly (`main`) or recent `6.0` toolchain you can enable support for background indexing in Sourcekit-LSP. This removes the need to do a build before getting code completion and diagnostics.
+Background Indexing was added as an experimental feature in Swift toolchain version 6.0 and then enabled by default in 6.1. This feature removes the need to do a build before getting code completion and diagnostics.
+
+On startup, SourceKit-LSP will read your project information from your `Package.swift` and begin indexing your project automatically. All indexing results are cached in the `.build/index-build` folder within your workspace.
 
-To enable support, set the [`swift.sourcekit-lsp.backgroundIndexing`](vscode://settings/swift.sourcekit-lsp.backgroundIndexing) setting to `true`.
+To enable or disable this feature you can use the [`swift.sourcekit-lsp.backgroundIndexing`](vscode://settings/swift.sourcekit-lsp.backgroundIndexing) setting.
 
 ### Support for 'Expand Macro'
 

@@ -1,6 +1,6 @@
 # Installation
 
-vscode-code Swift is installed through the extension marketplace.
+Install the Swift extension via the VS Code Marketplace.
 
 The Swift extension is supported on macOS, Linux, and Windows.
 

@@ -10,11 +10,12 @@ vscode-swift supports the following Swift toolchains:
 
 The extension also strives to work with the latest nightly toolchains built from the main branch.
 
-Certain features of vscode-swift will only work with newer versions of the toolchains. We recommend using the latest version of the Swift toolchain to get the most benefit of the extension. The following features only work with certain toolchains as listed:
+Certain features of vscode-swift will only work with newer versions of the toolchains. We recommend using the latest version of the Swift toolchain to get the most benefit out of the extension. The following features only work with certain toolchains as listed:
 
-Feature                  | Minimum Toolchain Required                     
------------------------- | ------------------------------------- 
-lldb-dap debugging       | 6.0
+Feature                    | Minimum Toolchain Required                     
+-------------------------- | ------------------------------------- 
+Debugging with `lldb-dap`  | 6.0
+<doc:docc-live-preview>    | 6.2
 
 ## Swiftly Support
 
@@ -24,7 +25,7 @@ You can choose a swiftly managed toolchain to use from the `> Swift: Select Tool
 
 If you do `swiftly use` on the command line you must restart VS Code or do `> Developer: Reload Window` in order for the VS Code Swift extension to start using the new toolchain.
 
-### `.swift-version` Support
+### .swift-version Support
 
 Swiftly can use a special `.swift-version` file in the root of your package so that you can share your toolchain preference with the rest of your team. The VS Code Swift extension respects this file if it exists and will use the toolchain specified within it to build and test your package.