Add documentation for how we use existentials in SwiftSyntax

Author: ahoppen

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

@@ -27,6 +27,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>
 
 ### 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

@@ -1,8 +1,8 @@
 # `@_spi` attribute
 
-swift-syntax extensively makes extensive use of the `@_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)`.
+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.
 

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

@@ -27,6 +27,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>
 
 ### Syntax