Add a documentation article for @_spi and when to use existentials

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

@@ -17,13 +17,18 @@ allows Swift tools to parse, inspect, generate, and transform Swift source code.
 ### Articles
 
 - <doc:Working-with-SwiftSyntax>
-- <doc:ChangingSwiftSyntax>
-- <doc:Create-SwiftSyntax-Release>
 
 ### Tutorials
 
 - <doc:Tutorial-Table-of-Contents>
 
+### Contributing
+
+These articles are intended for developers wishing to contribute to SwiftSyntax
+
+- <doc:ChangingSwiftSyntax>
+- <doc:Existentials>
+
 ### Syntax
 
 - <doc:SwiftSyntax/Syntax>

Sources/SwiftSyntax/Documentation.docc/Existentials.md

@@ -0,0 +1,10 @@
+# When to use protocols in SwiftSyntax
+
+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. 
+
+There are two more performant 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)`.

Sources/SwiftSyntax/Documentation.docc/SPI.md

@@ -0,0 +1,9 @@
+# `@_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.

Sources/SwiftSyntax/Documentation.docc/generated/SwiftSyntax.md

@@ -17,13 +17,18 @@ allows Swift tools to parse, inspect, generate, and transform Swift source code.
 ### Articles
 
 - <doc:Working-with-SwiftSyntax>
-- <doc:ChangingSwiftSyntax>
-- <doc:Create-SwiftSyntax-Release>
 
 ### Tutorials
 
 - <doc:Tutorial-Table-of-Contents>
 
+### Contributing
+
+These articles are intended for developers wishing to contribute to SwiftSyntax
+
+- <doc:ChangingSwiftSyntax>
+- <doc:Existentials>
+
 ### Syntax
 
 - <doc:SwiftSyntax/Syntax>