Apply suggestions from code review

matthewbastien · heckj · matthewbastien · commit 4310265857e2 · 2025-06-03T11:29:56.000-04:00
Co-authored-by: Joseph Heck &lt;j_heck@apple.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -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/Resources/install-pre-release.png)
+![A snapshot of VS Code that has Extensions highlighted, showing the Swift extension. In the detail panel of the extension view, a red box highlights the button "Switch to Pre-Release Version".](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.
 
diff --git a/userdocs/userdocs.docc/Articles/Advanced/install-pre-release.md b/userdocs/userdocs.docc/Articles/Advanced/install-pre-release.md
@@ -2,10 +2,10 @@
 
 Try out the latest updates by switching to the pre-release version.
 
-The Swift extension provides pre-release builds that let you 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 Swift extension provides pre-release builds that you can use to test out unreleased features or get bug fixes before the project publishes an official release. Pre-release build numbers are 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 snapshot of VS Code that has Extensions highlighted, showing the Swift extension. In the detail panel of the extension view, a red box highlights the button "Switch to Pre-Release Version".](install-pre-release.png)
 
-A "Switch to Release Version" button will appear in its place that lets you go back to the official release.
+When you select to use a pre-release version, the button changes to "Switch to Release Version", which lets you go back to the official release.
diff --git a/userdocs/userdocs.docc/Articles/Features/automatic-task-creation.md b/userdocs/userdocs.docc/Articles/Features/automatic-task-creation.md
@@ -1,13 +1,13 @@
 # Automatic Task Creation
 
-Tasks added for common operations with your Package.
+Add tasks 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 adds the following 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.
 
-- **Build All**: Build all targets in the Package
-- **Build Debug <Executable>**: Each executable in a Package.swift gets a task for building a debug build
-- **Build Release <Executable>**: Each executable in a Package.swift gets a task for building a release build
+> 💡 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).
 
 These tasks are available via the commands **Terminal ▸ Run Task...** and **Terminal ▸ Run Build Task...** in the command palette.
diff --git a/userdocs/userdocs.docc/Articles/Features/debugging.md b/userdocs/userdocs.docc/Articles/Features/debugging.md
@@ -2,10 +2,10 @@
 
 Debug your Swift executables using LLDB.
 
+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.
+
 > 💡 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.
diff --git a/userdocs/userdocs.docc/Articles/Features/docc-live-preview.md b/userdocs/userdocs.docc/Articles/Features/docc-live-preview.md
@@ -1,11 +1,19 @@
 # Documentation Live Preview
 
+@Metadata {
+    @Available("Swift", introduced: "6.2")
+}
+
 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 toolchain provides DocC, which compiles documentation for your Swift package. You can distribute compiled documentation to developers, or host the content. It's what this project used to make its documentation! 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:
+View a side-by-side live preview of your documentation as you edit it with the Swift extension for VS Code.
+Access this feature using the Preview Swift Documentation button at the top right of an editor, or be invoking `Swift: Preview Documentation` in the command palette.
+ This opens up a new editor pane with your rendered documentation:
 
 ![An animation showing how to launch documentation live preview.](docc-live-preview.gif)
+
+> Note: This feature is only available when using a Swift toolchain 6.2 or higher running on macOS or Linux.
+
diff --git a/userdocs/userdocs.docc/Articles/Features/language-features.md b/userdocs/userdocs.docc/Articles/Features/language-features.md
@@ -1,13 +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.
+Navigate and write your Swift code more easily with Language features.
 
 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 correctly. Whenever you add a new dependency to your project, make sure to rebuild it so that SourceKit-LSP can update its information.
+> ⚠️ 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.
 
+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.
+
 SourceKit-LSP can be configured via extension settings. See <doc:settings> for more information.
diff --git a/userdocs/userdocs.docc/Articles/Features/test-explorer.md b/userdocs/userdocs.docc/Articles/Features/test-explorer.md
@@ -1,12 +1,12 @@
 # Running and Debugging Tests
 
-vscode-swift shows test results in the test explorer.
+View 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.
+All VS Code extensions provide a [testing capabilities and views(https://code.visualstudio.com/docs/debugtest/testing).
+View, run, and debug tests that your package containers in the Test Explorer.
 
-![](test-explorer.png)
+![A screenshot of the test explorer pane in Visual Studio Code that shows a selection of 5 tests run and passed.](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 you have already opened a file, you can quickly jump to the source code for a test.
 
diff --git a/userdocs/userdocs.docc/Articles/Reference/commands.md b/userdocs/userdocs.docc/Articles/Reference/commands.md
@@ -2,7 +2,6 @@
 
 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.
 
@@ -55,4 +54,6 @@ The following command is only available on macOS:
 - **`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.
+- **`Re-Index Project`** - Force a re-index of the project to refresh code completion and symbol navigation support.
+
+> 💡 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.
diff --git a/userdocs/userdocs.docc/Articles/Reference/settings.md b/userdocs/userdocs.docc/Articles/Reference/settings.md
@@ -1,6 +1,6 @@
 # Extension Settings
 
-vscode-swift provides various settings to configure its behaviour.
+Configure the behavior of the Swift extension.
 
 > 💡 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.
 
diff --git a/userdocs/userdocs.docc/Articles/Topics/supported-toolchains.md b/userdocs/userdocs.docc/Articles/Topics/supported-toolchains.md
@@ -1,18 +1,19 @@
 # Supported Toolchains
 
-vscode-swift supports several versions of the Swift toolchain.
+Find out which versions of Swift the extension supports.
 
-vscode-swift supports the following Swift toolchains:
+The Swift extension supports the following Swift toolchains:
  * 5.9
  * 5.10
  * 6.0
  * 6.1
+ * 6.2
 
 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 out of the extension. The following features only work with certain toolchains as listed:
+Certain features of the Swift extension 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                     
+Feature                    | Minimum Toolchain Required
 -------------------------- | ------------------------------------- 
 Debugging with `lldb-dap`  | 6.0
 <doc:docc-live-preview>    | 6.2
diff --git a/userdocs/userdocs.docc/userdocs.md b/userdocs/userdocs.docc/userdocs.md
@@ -1,4 +1,4 @@
-# vscode-swift
+# The Swift Extension for VS Code
 
 @Metadata {
    @TechnologyRoot

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# vscode-swift`
	`1`	`+# The Swift Extension for VS Code`
`2`	`2`
`3`	`3`	`@Metadata {`
`4`	`4`	`@TechnologyRoot`