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,7 @@
+# Usage of protocol types in SwiftSyntax
+
+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/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