Merge pull request #2074 from TTOzzi/gardening-docs

Gardening documents

Author: ahoppen

Contributor Documentation/BSP Extensions.md

@@ -69,7 +69,7 @@ export interface PrepareParams {
 }
 ```
 
-## `builtTarget/sources`
+## `buildTarget/sources`
 
 `SourceItemDataKind` can be `sourceKit` in which case `SourceItem.data` contains the following data.
 
@@ -90,7 +90,7 @@ export interface SourceKitSourceItemData {
   isHeader?: bool;
 
   /**
-   * The output path that are is during indexing for this file, ie. the `-index-unit-output-path`, if it is specified
+   * The output path that is during indexing for this file, ie. the `-index-unit-output-path`, if it is specified
    * in the compiler arguments or the file that is passed as `-o`, if `-index-unit-output-path` is not specified.
    *
    * This allows SourceKit-LSP to remove index entries for source files that are removed from a target but remain

Contributor Documentation/Environment Variables.md

@@ -10,8 +10,8 @@ The following environment variables can be used to control some behavior in Sour
 
 ## Runtime
 
-- `SOURCEKIT_LSP_LOG_LEVEL`: When using `NonDarwinLogger`, specify the level at which messages should be logged. Defaults to `debug` in debug build and `default` in release builds. Primarily used to increase the log level when running tests from a release build in Swift CI. To adjust the logging on user devices, use the [Configuration file](Configuration%20File.md).
-- `SOURCEKIT_LSP_LOG_PRIVACY_LEVEL`: When using `NonDarwinLogger`, specifies whether information that might contain sensitive information (essentially source code) should be logged. Defaults to `private` in debug build and `public` in release builds. Primarily used to log sensitive information when running tests from a release build in Swift CI. To adjust the logging on user devices, use the [Configuration file](Configuration%20File.md).
+- `SOURCEKIT_LSP_LOG_LEVEL`: When using `NonDarwinLogger`, specify the level at which messages should be logged. Defaults to `debug` in debug build and `default` in release builds. Primarily used to increase the log level when running tests from a release build in Swift CI. To adjust the logging on user devices, use the [Configuration file](../Documentation/Configuration%20File.md).
+- `SOURCEKIT_LSP_LOG_PRIVACY_LEVEL`: When using `NonDarwinLogger`, specifies whether information that might contain sensitive information (essentially source code) should be logged. Defaults to `private` in debug build and `public` in release builds. Primarily used to log sensitive information when running tests from a release build in Swift CI. To adjust the logging on user devices, use the [Configuration file](../Documentation/Configuration%20File.md).
 
 ## Testing
 - `SKIP_LONG_TESTS`: Skip tests that typically take more than 1s to execute.

Contributor Documentation/Files To Reindex.md

@@ -13,7 +13,7 @@ We decided to not re-index any files other than the file itself because naively
 We mark the targets of the changed file as well as any dependent targets as out-of-date. The assumption is that most likely the user will go back to any of the affected files shortly afterwards and modify them again. When that happens, the affected file will get re-indexed and bring the index back up to date.
 
 Alternatives would be:
-- We could we check the file’s interface hash and re-index other files based on whether it has changed. But at that point we are somewhat implementing a build system. And even if a new public method was introduced it’s very likely that the user hasn’t actually used it anywhere yet, which means that re-indexing all dependent modules would still be doing unnecessary work.
+- We could check the file’s interface hash and re-index other files based on whether it has changed. But at that point we are somewhat implementing a build system. And even if a new public method was introduced it’s very likely that the user hasn’t actually used it anywhere yet, which means that re-indexing all dependent modules would still be doing unnecessary work.
 - To cover case (2) from above, we could re-index only dependencies that previously indexed with errors. This is an alternative that hasn’t been fully explored.
 
 ## `.h`

Contributor Documentation/LSP Extensions.md

@@ -180,7 +180,7 @@ a text document and returns a `DoccDocumentationResponse`. The response contains
 representing single JSON encoded DocC RenderNode. This RenderNode can then be rendered in an
 editor via https://github.com/swiftlang/swift-docc-render.
 
-The position may be ommitted for documentation within DocC markdown and tutorial files as they
+The position may be omitted for documentation within DocC markdown and tutorial files as they
 represent a single documentation page. It is only required for generating documentation within
 Swift files as they usually contain multiple documentable symbols.
 

Documentation/Diagnose Bundle.md

@@ -13,7 +13,7 @@ You may want to inspect the bundle to determine whether you're willing to share
   - From Xcode toolchains, just a stack trace.
   - For assert compilers (ie. nightly toolchains) also sometimes some source code that was currently compiled to cause the crash.
 - Log messages emitted by SourceKit
-  - We mark all information that may contain private information (source code, file names, …) as private by default, so all of that will be redacted. Private logging can be enabled for SourceKit-LSP as described in [Enable Extended Logging](#enable-extended-logging). On macOS these extended log messages are also included in a sysdiagnose.
+  - We mark all information that may contain private information (source code, file names, …) as private by default, so all of that will be redacted. Private logging can be enabled for SourceKit-LSP as described in [Enable Extended Logging](Enable%20Extended%20Logging.md). On macOS these extended log messages are also included in a sysdiagnose.
 - Versions of Swift installed on your system
 - If possible, a minimized project that caused SourceKit to crash
 - If possible, a minimized project that caused the Swift compiler to crash

Documentation/Enable Experimental Background Indexing.md

@@ -7,12 +7,12 @@ Background indexing in SourceKit-LSP is enabled by default in Swift 6.1 toolchai
 
 ## Behavior Without Background Indexing
 
-With background indexing disabled SourceKit-LSP does not update its global index in the background or build Swift modules in the background. Thus, a lot of cross-module or global functionality is limited if the project hasn't been built recently. For example consider two modules: `Lib` and `Exec`, where `Exec` depends on `Lib`: Without background indexing, if a function is added to `Lib`, completion/jump to definition/etc in `Exec` would not be able to see that function until after a build. Background indexing solves that issue.
+With background indexing disabled, SourceKit-LSP does not update its global index in the background or build Swift modules in the background. Thus, a lot of cross-module or global functionality is limited if the project hasn't been built recently. For example, consider two modules: `Lib` and `Exec`, where `Exec` depends on `Lib`: Without background indexing, if a function is added to `Lib`, completion/jump to definition/etc in `Exec` would not be able to see that function until after a build. Background indexing solves that issue.
 
 ## Set Up
 
 1. Install the Swift 6.0 toolchain or install [Xcode 16](https://developer.apple.com/xcode/).
-3. Enable the experimental `background-indexing` feature by creating a [configuration file](Configuration%20File.md) with the following contents at `~/.sourcekit-lsp/config.json` with the following contents:
+2. Enable the experimental `background-indexing` feature by creating a [configuration file](Configuration%20File.md) at `~/.sourcekit-lsp/config.json` with the following contents:
 ```json
 {
   "backgroundIndexing": true,

Documentation/Enable Extended Logging.md

@@ -1,6 +1,6 @@
 # Enable Extended logging
 
-By default, SourceKit-LSP redacts information about your source code, directory structure, and similar potentially sensitive information from its logs. If you are comfortable with sharing such information, you can enable extended SourceKit-LSP’s extended logging, which improves the ability of SourceKit-LSP developers to understand and fix issues.
+By default, SourceKit-LSP redacts information about your source code, directory structure, and similar potentially sensitive information from its logs. If you are comfortable with sharing such information, you can enable SourceKit-LSP’s extended logging, which improves the ability of SourceKit-LSP developers to understand and fix issues.
 
 When extended logging is enabled, it will log extended information from that point onwards. To capture the extended logs for an issue you are seeing, please reproduce the issue after enabling extended logging and capture a diagnose bundle by running `sourcekit-lsp diagnose` in terminal.
 
@@ -12,7 +12,7 @@ To disable extended logging again, remove the configuration profile as described
 
 ## Non-Apple platforms
 
-To enable extended logging on non-Apple platforms, create a [configuration file](Configuration%20File.md) with the following contents at `~/.sourcekit-lsp/config.json` with the following contents:
+To enable extended logging on non-Apple platforms, create a [configuration file](Configuration%20File.md) at `~/.sourcekit-lsp/config.json` with the following contents:
 ```json
 {
   "logging": {