Improve documentation (#1588)

Co-authored-by: Paul LeMarquand <[email protected]>
Co-authored-by: Joseph Heck <[email protected]>

Author: 3 people

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/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.
 

README.md

@@ -12,7 +12,7 @@ This extension adds language support for Swift to Visual Studio Code, providing
 
 # Documentation
 
-The official documentation for this extension is available at [vscode-swift](https://docs.swift.org/vscode/documentation/userdocs)
+The official documentation for this extension is [available on swift.org](https://docs.swift.org/vscode/documentation/userdocs).
 
 This extension uses [SourceKit LSP](https://github.com/apple/sourcekit-lsp) for the [language server](https://microsoft.github.io/language-server-protocol/overviews/lsp/overview/), which powers code completion. It also has a dependency on the [LLDB DAP](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.lldb-dap) extension to enable debugging.
 

userdocs/userdocs.docc/Articles/Advanced/install-pre-release.md

@@ -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 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:
+
+![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)
+
+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.

userdocs/userdocs.docc/remote-dev.md renamed to userdocs/userdocs.docc/Articles/Advanced/remote-dev.md

@@ -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.
 

userdocs/userdocs.docc/Articles/Features/automatic-task-creation.md

@@ -0,0 +1,13 @@
+# Automatic Task Creation
+
+Add tasks for common operations with your Package.
+
+For workspaces that contain a `Package.swift` file, the Swift extension adds 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.
+
+> 💡 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.

userdocs/userdocs.docc/debugging.md renamed to userdocs/userdocs.docc/Articles/Features/debugging.md

@@ -1,11 +1,11 @@
 # Debugging
 
-vscode-swift allows you to debug your Swift packages.
-
-> Tip: Debugging works best when using a version of the Swift toolchain 6.0 or higher
+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.
 
-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.
+> 💡 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.
 
-Debugging uses workflows common to all VSCode extensions. For more information see https://code.visualstudio.com/docs/editor/debugging
+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.

userdocs/userdocs.docc/Articles/Features/docc-live-preview.md

@@ -0,0 +1,19 @@
+# Documentation Live Preview
+
+@Metadata {
+    @Available("Swift", introduced: "6.2")
+}
+
+Show a live preview of your Swift documentation while editing.
+
+
+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/).
+
+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.
+

userdocs/userdocs.docc/Articles/Features/language-features.md

@@ -0,0 +1,13 @@
+# Language Features
+
+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 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.

userdocs/userdocs.docc/project-view.md renamed to userdocs/userdocs.docc/Articles/Features/project-view.md

@@ -1,9 +1,9 @@
-# Project View
+# Swift Project View
 
-vscode-swift provides project view
+Use this view to navigate your Swift project.
 
 If your workspace contains a package, this extension will add a **Swift Project** view to the Explorer:
 
-![](package-dependencies.png)
+![A snapshot of the Package Dependencies view showing dependencies for the async-http-client Swift project.](package-dependencies.png)
 
 Additionally, the extension will monitor `Package.swift` and `Package.resolved` for changes, resolve any changes to the dependencies, and update the view as needed.

userdocs/userdocs.docc/test-coverage.md renamed to userdocs/userdocs.docc/Articles/Features/test-explorer.md

@@ -1,17 +1,27 @@
-# Test Coverage
+# Running and Debugging Tests
 
-vscode-swift provides mechanisms to see coverage of your tests.
+View test results 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.
+
+![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.
+
+## 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.
 
 The Swift extension integrates with VS Code's Code Coverage APIs to record what code has been hit or missed by your tests.
 
-![](coverage-run.png)
+![A snapshot of the Test Explorer with the mouse hovering over the "Run Tests With Coverage" button.](coverage-run.png)
 
 Once you've performed a code coverage run a coverage report will be displayed in a section of the primary side bar. This report lists all the source files in your project and what percentage of lines were hit by tests. You can click on each file to open that file in the code editor. If you close the report you can always get it back by running the command `Test: Open Coverage`.
 
-![](coverage-report.png)
+![A snapshot of the Test Coverage view showing percentage of code covered for each source file.](coverage-report.png)
 
 After generating code coverage lines numbers in covered files will be coloured red or green depending on if they ran during the test run. Hovering over the line numbers shows how many times each line was run. Hitting the "Toggle Inline Coverage" link that appears when hovering over the line numbers will keep this information visible.
 
-![](coverage-render.png)
+![A snapshot of a text editor with Swift code highlighted in green to show that it has been executed in the test.](coverage-render.png)