Generate documentation for traits

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/Traits.swift

@@ -10,15 +10,19 @@
 //
 //===----------------------------------------------------------------------===//
 
+import SwiftSyntax
+
 public class Trait {
   public let traitName: String
+  public let protocolName: TokenSyntax
+  public let documentation: SwiftSyntax.Trivia
   public let children: [Child]
-  public let description: String?
 
-  init(traitName: String, children: [Child], description: String? = nil) {
+  init(traitName: String, documentation: String? = nil, children: [Child]) {
     self.traitName = traitName
+    self.protocolName = .identifier("\(traitName)Syntax")
+    self.documentation = docCommentTrivia(from: documentation)
     self.children = children
-    self.description = description
   }
 }
 

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

@@ -61,7 +61,7 @@ let nodesSections: String = {
 
   addSection(heading: "Miscellaneous Syntax", types: SYNTAX_NODES.map(\.kind.syntaxType.description).filter({ !handledSyntaxTypes.contains($0) }))
 
-  addSection(heading: "Traits", types: TRAITS.map { "\($0.traitName)Syntax" })
+  addSection(heading: "Traits", types: TRAITS.map { "\($0.protocolName)" })
 
   return result
 }()

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

@@ -19,24 +19,30 @@ let syntaxTraitsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
   for trait in TRAITS {
     try! ProtocolDeclSyntax(
       """
-      // MARK: - \(raw: trait.traitName)Syntax
+      // MARK: - \(trait.protocolName)
 
-      public protocol \(raw: trait.traitName)Syntax: SyntaxProtocol
+      \(raw: trait.documentation)
+      public protocol \(trait.protocolName): SyntaxProtocol
       """
     ) {
       for child in trait.children {
-        DeclSyntax("var \(raw: child.varName): \(child.syntaxNodeKind.syntaxType)\(raw: child.isOptional ? "?" : "") { get set }")
+        DeclSyntax(
+          """
+          \(raw: child.docComment)
+          var \(raw: child.varName): \(child.syntaxNodeKind.syntaxType)\(raw: child.isOptional ? "?" : "") { get set }
+          """
+        )
       }
     }
 
-    try! ExtensionDeclSyntax("public extension \(raw: trait.traitName)Syntax") {
+    try! ExtensionDeclSyntax("public extension \(trait.protocolName)") {
       DeclSyntax(
         """
         /// Without this function, the `with` function defined on `SyntaxProtocol`
         /// does not work on existentials of this protocol type.
         @_disfavoredOverload
-        func with<T>(_ keyPath: WritableKeyPath<\(raw: trait.traitName)Syntax, T>, _ newChild: T) -> \(raw: trait.traitName)Syntax {
-          var copy: \(raw: trait.traitName)Syntax = self
+        func with<T>(_ keyPath: WritableKeyPath<\(trait.protocolName), T>, _ newChild: T) -> \(trait.protocolName) {
+          var copy: \(trait.protocolName) = self
           copy[keyPath: keyPath] = newChild
           return copy
         }
@@ -48,21 +54,21 @@ let syntaxTraitsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       DeclSyntax(
         """
         /// Check whether the non-type erased version of this syntax node conforms to
-        /// `\(raw: trait.traitName)Syntax`.
+        /// `\(trait.protocolName)`.
         /// Note that this will incur an existential conversion.
-        func isProtocol(_: \(raw: trait.traitName)Syntax.Protocol) -> Bool {
-          return self.asProtocol(\(raw: trait.traitName)Syntax.self) != nil
+        func isProtocol(_: \(trait.protocolName).Protocol) -> Bool {
+          return self.asProtocol(\(trait.protocolName).self) != nil
         }
         """
       )
 
       DeclSyntax(
         """
         /// Return the non-type erased version of this syntax node if it conforms to
-        /// `\(raw: trait.traitName)Syntax`. Otherwise return `nil`.
+        /// `\(trait.protocolName)`. Otherwise return `nil`.
         /// Note that this will incur an existential conversion.
-        func asProtocol(_: \(raw: trait.traitName)Syntax.Protocol) -> \(raw: trait.traitName)Syntax? {
-          return Syntax(self).asProtocol(SyntaxProtocol.self) as? \(raw: trait.traitName)Syntax
+        func asProtocol(_: \(trait.protocolName).Protocol) -> \(trait.protocolName)? {
+          return Syntax(self).asProtocol(SyntaxProtocol.self) as? \(trait.protocolName)
         }
         """
       )

Sources/SwiftSyntax/generated/SyntaxTraits.swift

@@ -14,6 +14,7 @@
 
 // MARK: - BracedSyntax
 
+
 public protocol BracedSyntax: SyntaxProtocol {
   var leftBrace: TokenSyntax {
     get
@@ -55,6 +56,7 @@ public extension SyntaxProtocol {
 
 // MARK: - DeclGroupSyntax
 
+
 public protocol DeclGroupSyntax: SyntaxProtocol {
   var attributes: AttributeListSyntax? {
     get
@@ -111,6 +113,7 @@ public extension SyntaxProtocol {
 
 // MARK: - EffectSpecifiersSyntax
 
+
 public protocol EffectSpecifiersSyntax: SyntaxProtocol {
   var unexpectedBeforeAsyncSpecifier: UnexpectedNodesSyntax? {
     get
@@ -167,6 +170,7 @@ public extension SyntaxProtocol {
 
 // MARK: - FreestandingMacroExpansionSyntax
 
+
 public protocol FreestandingMacroExpansionSyntax: SyntaxProtocol {
   var poundToken: TokenSyntax {
     get
@@ -238,6 +242,7 @@ public extension SyntaxProtocol {
 
 // MARK: - IdentifiedDeclSyntax
 
+
 public protocol IdentifiedDeclSyntax: SyntaxProtocol {
   var identifier: TokenSyntax {
     get
@@ -274,6 +279,7 @@ public extension SyntaxProtocol {
 
 // MARK: - ParenthesizedSyntax
 
+
 public protocol ParenthesizedSyntax: SyntaxProtocol {
   var leftParen: TokenSyntax {
     get
@@ -315,6 +321,7 @@ public extension SyntaxProtocol {
 
 // MARK: - WithAttributesSyntax
 
+
 public protocol WithAttributesSyntax: SyntaxProtocol {
   var attributes: AttributeListSyntax? {
     get
@@ -351,6 +358,7 @@ public extension SyntaxProtocol {
 
 // MARK: - WithCodeBlockSyntax
 
+
 public protocol WithCodeBlockSyntax: SyntaxProtocol {
   var body: CodeBlockSyntax {
     get
@@ -387,6 +395,7 @@ public extension SyntaxProtocol {
 
 // MARK: - WithModifiersSyntax
 
+
 public protocol WithModifiersSyntax: SyntaxProtocol {
   var modifiers: ModifierListSyntax? {
     get
@@ -423,6 +432,7 @@ public extension SyntaxProtocol {
 
 // MARK: - WithStatementsSyntax
 
+
 public protocol WithStatementsSyntax: SyntaxProtocol {
   var statements: CodeBlockItemListSyntax {
     get
@@ -459,6 +469,7 @@ public extension SyntaxProtocol {
 
 // MARK: - WithTrailingCommaSyntax
 
+
 public protocol WithTrailingCommaSyntax: SyntaxProtocol {
   var trailingComma: TokenSyntax? {
     get