Improve documentation articles

Author: ahoppen

CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndex.swift

@@ -67,9 +67,40 @@ let nodesSections: String = {
   return result
 }()
 
+var contributingDocs: String = {
+  let contributingDocsFolder = URL(fileURLWithPath: #filePath)
+    .deletingLastPathComponent()
+    .deletingLastPathComponent()
+    .deletingLastPathComponent()
+    .deletingLastPathComponent()
+    .deletingLastPathComponent()
+    .deletingLastPathComponent()
+    .appendingPathComponent("Sources")
+    .appendingPathComponent("SwiftSyntax")
+    .appendingPathComponent("Documentation.docc")
+    .appendingPathComponent("Contributing")
+
+  let files = (try? FileManager.default.contentsOfDirectory(at: contributingDocsFolder, includingPropertiesForKeys: nil)) ?? []
+
+  return files.compactMap { file in
+    if file.pathExtension != "md" {
+      return nil
+    }
+    let doccName = file.lastPathComponent
+      .replacingOccurrences(of: ".md", with: "")
+      .replacingOccurrences(of: " ", with: "-")
+    return "- <doc:\(doccName)>"
+  }.sorted().joined(separator: "\n")
+}()
+
 let swiftSyntaxDoccIndex: String = {
-  let templateURL = URL(fileURLWithPath: #filePath).deletingLastPathComponent().appendingPathComponent("SwiftSyntaxDoccIndexTemplate.md")
+  let templateURL = URL(fileURLWithPath: #filePath)
+    .deletingLastPathComponent()
+    .appendingPathComponent("SwiftSyntaxDoccIndexTemplate.md")
   let template = try! String(contentsOf: templateURL)
 
-  return template.replacingOccurrences(of: "{{Nodes}}", with: nodesSections)
+  return
+    template
+    .replacingOccurrences(of: "{{Nodes}}", with: nodesSections)
+    .replacingOccurrences(of: "{{ContributingDocs}}", with: contributingDocs)
 }()

CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntax/SwiftSyntaxDoccIndexTemplate.md

@@ -26,8 +26,7 @@ allows Swift tools to parse, inspect, generate, and transform Swift source code.
 
 These articles are intended for developers wishing to contribute to SwiftSyntax
 
-- <doc:ChangingSwiftSyntax>
-- <doc:Existentials>
+{{ContributingDocs}}
 
 ### Syntax
 

Sources/SwiftSyntax/Documentation.docc/ChangingSwiftSyntax.md renamed to Sources/SwiftSyntax/Documentation.docc/Contributing/ChangingSwiftSyntax.md

@@ -3,8 +3,8 @@
 Learn when to use protocols value types like ``ExprSyntax`` over protocols like ``ExprSyntaxProtocol``. 
 
 
-SwiftSyntax tries to minimize the use of existentials (aka. protocols spelled with `any` or protocols spelled without `some`) wherever possible. This is because when the stored value is more than 3 words (a word is the size of a pointer) large, these existentials store their data on the heap. The data stored inside `RawSyntax` is bigger than 3 words and thus every time you pass a value around as a e.g. an `ExprSyntaxProtocol`, a new heap allocation will be made and that data needs to be reference-counted, which causes a very noticable performance overhead. 
+SwiftSyntax tries to minimize the use of existentials (aka. protocols spelled with `any` or protocols spelled without `some`) wherever possible. This is because when the stored value is more than 3 words (a word is the size of a pointer) large, these existentials store their data on the heap. The data stored inside `RawSyntax` is larger than 3 words and thus every time you pass a value around as a e.g. an `ExprSyntaxProtocol`, a new heap allocation will be made and that data needs to be reference-counted, which causes a very noticeable performance overhead. 
 
-There are two more performant alternatives:
+swift-syntax offers tow alternatives:
 - When passing a single node around, use `some ExprSyntaxProtocol`. This allows the concrete expression node (e.g. an ``IntegerLiteralExprSyntax``) to be passed directly without the need to wrap it in an existential and thus avoid the performance overhead.
-- When multiple expression nodes need to be represented that might be of different types, eg. in an array of expressions, use the ``ExprSyntax`` type. ``ExprSyntax`` is a struct and can thus be allocated on the stack. The downside is that specific expression nodes need to explicitly be upcast to `ExprSyntax`, eg. as `ExprSyntax(integerLiteral)`. ``ExprSyntax`` can be cast to more specific types using the `as` method, e.g. `expr.as(IntegerLiteralExprSyntax.self)`.
+- When multiple expression nodes need to be represented that might be of different types, eg. in an array of expressions, use the ``ExprSyntax`` type. ``ExprSyntax`` is a struct and can thus be allocated on the stack. The downside is that specific expression nodes need to explicitly be upcast to `ExprSyntax` (`ExprSyntax(integerLiteral)`) and downcast to more specific types using a custom `as` method (`expr.as(IntegerLiteralExprSyntax.self)`).

Sources/SwiftSyntax/Documentation.docc/Existentials.md renamed to Sources/SwiftSyntax/Documentation.docc/Contributing/Existentials.md

@@ -1,9 +1,9 @@
-# `@_spi` attribute
+# @_spi attribute
 
 Learn when SwiftSyntax exposes declaration annotated as `@_spi`.
 
 Functions marked as `@_spi(RawSyntax)` (where ``RawSyntax`` can be any name) are considered *SPI* (System Programming Interface) and are only accessible if the module that declares them is imported as `@_spi(RawSyntax)`.
 
 Since functions marked as SPI are not part of the public API, swift-syntax makes no guarantee to their source stability. swift-syntax makes no effort to keep its SPI stable.
 
-Declarations are typically marked as SPI because they have some kind of caveat that makes them unsafe to use in general. For example, when accessing ``RawSyntax`` nodes, you need to manually guarantee that the ``SyntaxArena`` they live in doesn’t get de-allocated. Other declarations have an `@_spi` to share them between different modudules within the swift-syntax package but those APIs shouldn’t be accessed publicly.
+Declarations are typically marked as SPI because they have some kind of caveat that makes them unsafe to use in general. For example, when accessing ``RawSyntax`` nodes, you need to manually guarantee that the ``SyntaxArena`` they’re allocated in will not be de-allocated. Other declarations have an `@_spi` to share them between different modules within the swift-syntax package. These woulde use the [`package` modifier](https://github.com/apple/swift-evolution/blob/main/proposals/0386-package-access-modifier.md) if not for the fact that swift-syntax needed to compile with the last two Swift releases (see <doc:Swift-Version>).

Sources/SwiftSyntax/Documentation.docc/SPI.md renamed to Sources/SwiftSyntax/Documentation.docc/Contributing/SPI.md

@@ -0,0 +1,7 @@
+# Language Features Usable in swift-syntax
+
+Defines which language features the swift-syntax package can use.
+
+We require that SwiftSyntax builds with the latest released compiler and the previous major version (e.g. with Swift 5.8 and Swift 5.7).
+
+*This documentation article needs to be expanded*

Sources/SwiftSyntax/Documentation.docc/Contributing/Swift Version.md

@@ -28,6 +28,8 @@ These articles are intended for developers wishing to contribute to SwiftSyntax
 
 - <doc:ChangingSwiftSyntax>
 - <doc:Existentials>
+- <doc:SPI>
+- <doc:Swift-Version>
 
 ### Syntax