From 8d828a8d24f206209906951589411b0bdf3d2387 Mon Sep 17 00:00:00 2001
From: Dmitrii Valuev <dima.vap2011@yandex.ru>
Date: Sat, 23 Sep 2023 18:10:23 +0300
Subject: [PATCH] Add documentation for base types with their subtypes

---
 .../Sources/SyntaxSupport/Node.swift          |  25 ++++
 .../swiftsyntax/SyntaxBaseNodesFile.swift     |   6 +-
 .../generated/SyntaxBaseNodes.swift           | 128 ++++++++++++++++++
 3 files changed, 158 insertions(+), 1 deletion(-)

diff --git a/CodeGeneration/Sources/SyntaxSupport/Node.swift b/CodeGeneration/Sources/SyntaxSupport/Node.swift
index 1530bd41344..e07aee6c7a1 100644
--- a/CodeGeneration/Sources/SyntaxSupport/Node.swift
+++ b/CodeGeneration/Sources/SyntaxSupport/Node.swift
@@ -224,6 +224,31 @@ public class Node {
     )
   }
 
+  /// A doc comment that lists all the subtypes in which this node occurs as a base type in.
+  public var subtypes: SwiftSyntax.Trivia {
+    if kind == .unexpectedNodes {
+      return []
+    }
+
+    let list =
+      SYNTAX_NODES
+      .filter { $0.base == self.kind }
+      .map { "- ``\($0.kind.syntaxType)``" }
+      .joined(separator: "\n")
+
+    guard !list.isEmpty else {
+      return []
+    }
+
+    return .docCommentTrivia(
+      from: """
+        ### Subtypes
+
+        \(list)
+        """
+    )
+  }
+
   /// Construct the specification for a collection syntax node.
   ///
   /// `base` must be `.syntaxCollection`.
diff --git a/CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxBaseNodesFile.swift b/CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxBaseNodesFile.swift
index de32b813f43..85e24463122 100644
--- a/CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxBaseNodesFile.swift
+++ b/CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxBaseNodesFile.swift
@@ -17,6 +17,10 @@ import Utils
 
 let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
   for node in SYNTAX_NODES where node.kind.isBase {
+    let documentation = SwiftSyntax.Trivia(joining: [
+      node.documentation,
+      node.subtypes,
+    ])
     DeclSyntax(
       """
       // MARK: - \(node.kind.syntaxType)
@@ -170,7 +174,7 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
     try! StructDeclSyntax(
       """
-      \(node.documentation)
+      \(documentation)
       \(node.apiAttributes())\
       public struct \(node.kind.syntaxType): \(node.kind.protocolType), SyntaxHashable
       """
diff --git a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift
index ab916c743b3..7fe243fef78 100644
--- a/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift
+++ b/Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift
@@ -154,6 +154,32 @@ public extension Syntax {
   }
 }
 
+/// ### Subtypes
+/// 
+/// - ``AccessorDeclSyntax``
+/// - ``ActorDeclSyntax``
+/// - ``AssociatedTypeDeclSyntax``
+/// - ``ClassDeclSyntax``
+/// - ``DeinitializerDeclSyntax``
+/// - ``EditorPlaceholderDeclSyntax``
+/// - ``EnumCaseDeclSyntax``
+/// - ``EnumDeclSyntax``
+/// - ``ExtensionDeclSyntax``
+/// - ``FunctionDeclSyntax``
+/// - ``IfConfigDeclSyntax``
+/// - ``ImportDeclSyntax``
+/// - ``InitializerDeclSyntax``
+/// - ``MacroDeclSyntax``
+/// - ``MacroExpansionDeclSyntax``
+/// - ``MissingDeclSyntax``
+/// - ``OperatorDeclSyntax``
+/// - ``PoundSourceLocationSyntax``
+/// - ``PrecedenceGroupDeclSyntax``
+/// - ``ProtocolDeclSyntax``
+/// - ``StructDeclSyntax``
+/// - ``SubscriptDeclSyntax``
+/// - ``TypeAliasDeclSyntax``
+/// - ``VariableDeclSyntax``
 public struct DeclSyntax: DeclSyntaxProtocol, SyntaxHashable {
   public let _syntaxNode: Syntax
   
@@ -430,6 +456,60 @@ public extension Syntax {
   }
 }
 
+/// ### Subtypes
+/// 
+/// - ``ArrayExprSyntax``
+/// - ``ArrowExprSyntax``
+/// - ``AsExprSyntax``
+/// - ``AssignmentExprSyntax``
+/// - ``AwaitExprSyntax``
+/// - ``BinaryOperatorExprSyntax``
+/// - ``BooleanLiteralExprSyntax``
+/// - ``BorrowExprSyntax``
+/// - ``CanImportExprSyntax``
+/// - ``CanImportVersionInfoSyntax``
+/// - ``ClosureExprSyntax``
+/// - ``ConsumeExprSyntax``
+/// - ``CopyExprSyntax``
+/// - ``DeclReferenceExprSyntax``
+/// - ``DictionaryExprSyntax``
+/// - ``DiscardAssignmentExprSyntax``
+/// - ``EditorPlaceholderExprSyntax``
+/// - ``FloatLiteralExprSyntax``
+/// - ``ForceUnwrapExprSyntax``
+/// - ``FunctionCallExprSyntax``
+/// - ``GenericSpecializationExprSyntax``
+/// - ``IfExprSyntax``
+/// - ``InOutExprSyntax``
+/// - ``InfixOperatorExprSyntax``
+/// - ``IntegerLiteralExprSyntax``
+/// - ``IsExprSyntax``
+/// - ``KeyPathExprSyntax``
+/// - ``MacroExpansionExprSyntax``
+/// - ``MemberAccessExprSyntax``
+/// - ``MissingExprSyntax``
+/// - ``NilLiteralExprSyntax``
+/// - ``OptionalChainingExprSyntax``
+/// - ``PackElementExprSyntax``
+/// - ``PackExpansionExprSyntax``
+/// - ``PatternExprSyntax``
+/// - ``PostfixIfConfigExprSyntax``
+/// - ``PostfixOperatorExprSyntax``
+/// - ``PrefixOperatorExprSyntax``
+/// - ``RegexLiteralExprSyntax``
+/// - ``SequenceExprSyntax``
+/// - ``SimpleStringLiteralExprSyntax``
+/// - ``StringLiteralExprSyntax``
+/// - ``SubscriptCallExprSyntax``
+/// - ``SuperExprSyntax``
+/// - ``SwitchExprSyntax``
+/// - ``TernaryExprSyntax``
+/// - ``TryExprSyntax``
+/// - ``TupleExprSyntax``
+/// - ``TypeExprSyntax``
+/// - ``UnresolvedAsExprSyntax``
+/// - ``UnresolvedIsExprSyntax``
+/// - ``UnresolvedTernaryExprSyntax``
 public struct ExprSyntax: ExprSyntaxProtocol, SyntaxHashable {
   public let _syntaxNode: Syntax
   
@@ -734,6 +814,15 @@ public extension Syntax {
   }
 }
 
+/// ### Subtypes
+/// 
+/// - ``ExpressionPatternSyntax``
+/// - ``IdentifierPatternSyntax``
+/// - ``IsTypePatternSyntax``
+/// - ``MissingPatternSyntax``
+/// - ``TuplePatternSyntax``
+/// - ``ValueBindingPatternSyntax``
+/// - ``WildcardPatternSyntax``
 public struct PatternSyntax: PatternSyntaxProtocol, SyntaxHashable {
   public let _syntaxNode: Syntax
   
@@ -993,6 +1082,25 @@ public extension Syntax {
   }
 }
 
+/// ### Subtypes
+/// 
+/// - ``BreakStmtSyntax``
+/// - ``ContinueStmtSyntax``
+/// - ``DeferStmtSyntax``
+/// - ``DiscardStmtSyntax``
+/// - ``DoStmtSyntax``
+/// - ``ExpressionStmtSyntax``
+/// - ``FallThroughStmtSyntax``
+/// - ``ForStmtSyntax``
+/// - ``GuardStmtSyntax``
+/// - ``LabeledStmtSyntax``
+/// - ``MissingStmtSyntax``
+/// - ``RepeatStmtSyntax``
+/// - ``ReturnStmtSyntax``
+/// - ``ThenStmtSyntax``
+/// - ``ThrowStmtSyntax``
+/// - ``WhileStmtSyntax``
+/// - ``YieldStmtSyntax``
 public struct StmtSyntax: StmtSyntaxProtocol, SyntaxHashable {
   public let _syntaxNode: Syntax
   
@@ -1262,6 +1370,26 @@ public extension Syntax {
   }
 }
 
+/// ### Subtypes
+/// 
+/// - ``ArrayTypeSyntax``
+/// - ``AttributedTypeSyntax``
+/// - ``ClassRestrictionTypeSyntax``
+/// - ``CompositionTypeSyntax``
+/// - ``DictionaryTypeSyntax``
+/// - ``FunctionTypeSyntax``
+/// - ``IdentifierTypeSyntax``
+/// - ``ImplicitlyUnwrappedOptionalTypeSyntax``
+/// - ``MemberTypeSyntax``
+/// - ``MetatypeTypeSyntax``
+/// - ``MissingTypeSyntax``
+/// - ``NamedOpaqueReturnTypeSyntax``
+/// - ``OptionalTypeSyntax``
+/// - ``PackElementTypeSyntax``
+/// - ``PackExpansionTypeSyntax``
+/// - ``SomeOrAnyTypeSyntax``
+/// - ``SuppressedTypeSyntax``
+/// - ``TupleTypeSyntax``
 public struct TypeSyntax: TypeSyntaxProtocol, SyntaxHashable {
   public let _syntaxNode: Syntax