Render references to experimental syntax nodes in code font instead of as docc links

Docc doesn’t like references to SPI types because they are not part of the public API.

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/GrammarGenerator.swift

@@ -37,12 +37,12 @@ struct GrammarGenerator {
     let optionality = child.isOptional ? "?" : ""
     switch child.kind {
     case .node(let kind):
-      return "``\(kind.syntaxType)``\(optionality)"
+      return "\(kind.doccLink)\(optionality)"
     case .nodeChoices(let choices):
       let choicesDescriptions = choices.map { grammar(for: $0) }
       return "(\(choicesDescriptions.joined(separator: " | ")))\(optionality)"
     case .collection(kind: let kind, _, _, _):
-      return "``\(kind.syntaxType)``\(optionality)"
+      return "\(kind.doccLink)\(optionality)"
     case .token(let choices, _, _):
       if choices.count == 1 {
         return "\(grammar(for: choices.first!))\(optionality)"

CodeGeneration/Sources/SyntaxSupport/Node.swift

@@ -224,9 +224,9 @@ public class Node {
           // This will repeat the syntax type before and after the dot, which is
           // a little unfortunate, but it's the only way I found to get docc to
           // generate a fully-qualified type + member.
-          return " - ``\($0.node.syntaxType)``.``\($0.node.syntaxType)/\(childName)``"
+          return " - \($0.node.doccLink).``\($0.node.syntaxType)/\(childName)``"
         } else {
-          return " - ``\($0.node.syntaxType)``"
+          return " - \($0.node.doccLink)"
         }
       }
       .joined(separator: "\n")
@@ -249,7 +249,7 @@ public class Node {
     let list =
       SYNTAX_NODES
       .filter { $0.base == self.kind && !$0.isExperimental }
-      .map { "- ``\($0.kind.syntaxType)``" }
+      .map { "- \($0.kind.doccLink)" }
       .joined(separator: "\n")
 
     guard !list.isEmpty else {
@@ -392,9 +392,9 @@ public struct CollectionNode {
   public var grammar: SwiftSyntax.Trivia {
     let grammar: String
     if let onlyElement = elementChoices.only {
-      grammar = "``\(onlyElement.syntaxType)`` `*`"
+      grammar = "\(onlyElement.doccLink) `*`"
     } else {
-      grammar = "(\(elementChoices.map { "``\($0.syntaxType)``" }.joined(separator: " | "))) `*`"
+      grammar = "(\(elementChoices.map { "\($0.doccLink)" }.joined(separator: " | "))) `*`"
     }
 
     return .docCommentTrivia(
@@ -421,7 +421,3 @@ fileprivate extension Child {
     }
   }
 }
-
-fileprivate extension Node {
-
-}

CodeGeneration/Sources/SyntaxSupport/SyntaxNodeKind.swift

@@ -355,6 +355,17 @@ public enum SyntaxNodeKind: String, CaseIterable {
     }
   }
 
+  /// If this node is non-experimental a docc link wrapped in two backticks.
+  ///
+  /// For experimental nodes, the node's type name in code font.
+  public var doccLink: String {
+    if let node = SYNTAX_NODE_MAP[self], node.isExperimental {
+      return "`\(syntaxType)`"
+    } else {
+      return "``\(syntaxType)``"
+    }
+  }
+
   /// For base nodes, the name of the corresponding protocol to which all the
   /// concrete nodes that have this base kind, conform.
   public var protocolType: TypeSyntax {

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxBaseNodesFile.swift

@@ -25,9 +25,9 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       """
       // MARK: - \(node.kind.syntaxType)
 
-      /// Protocol to which all ``\(node.kind.syntaxType)`` nodes conform. 
+      /// Protocol to which all \(raw: node.kind.doccLink) nodes conform.
       ///
-      /// Extension point to add common methods to all ``\(node.kind.syntaxType)`` nodes.
+      /// Extension point to add common methods to all \(raw: node.kind.doccLink) nodes.
       ///
       ///  - Warning: Do not conform to this protocol yourself.
       \(node.apiAttributes())\
@@ -77,23 +77,23 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
           return self.as(S.self)!
         }
 
-        /// Checks if the current syntax node can be upcast to its base node type (``\#(node.kind.syntaxType)``).
+        /// Checks if the current syntax node can be upcast to its base node type (\#(raw: node.kind.doccLink)).
         ///
         /// - Returns: `true` since the node can always be upcast to its base node.
         @available(*, deprecated, message: "This cast will always succeed")
         public func `is`(_ syntaxType: \#(node.kind.syntaxType).Type) -> Bool {
           return true
         }
 
-        /// Attempts to upcast the current syntax node to its base node type (``\#(node.kind.syntaxType)``).
+        /// Attempts to upcast the current syntax node to its base node type (\#(raw: node.kind.doccLink)).
         ///
         /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
         @available(*, deprecated, message: "Use `\#(node.kind.syntaxType).init` for upcasting")
         public func `as`(_ syntaxType: \#(node.kind.syntaxType).Type) -> \#(node.kind.syntaxType)? {
           return \#(node.kind.syntaxType)(self)
         }
 
-        /// Force-upcast the current syntax node to its base node type (``\#(node.kind.syntaxType)``).
+        /// Force-upcast the current syntax node to its base node type (\#(raw: node.kind.doccLink)).
         ///
         /// - Returns: The base node created from the current syntax node, as the node can always be upcast to its base type.
         @available(*, deprecated, message: "Use `\#(node.kind.syntaxType).init` for upcasting")
@@ -182,7 +182,7 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Create a ``\(node.kind.syntaxType)`` node from a specialized syntax node.
+        /// Create a \(raw: node.kind.doccLink) node from a specialized syntax node.
         public init(_ syntax: some \(node.kind.protocolType)) {
           // We know this cast is going to succeed. Go through init(_: SyntaxData)
           // to do a sanity check and verify the kind matches in debug builds and get
@@ -194,7 +194,7 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Create a ``\(node.kind.syntaxType)`` node from a specialized optional syntax node.
+        /// Create a \(raw: node.kind.doccLink) node from a specialized optional syntax node.
         public init?(_ syntax: (some \(node.kind.protocolType))?) {
           guard let syntax = syntax else { return nil }
           self.init(syntax)
@@ -215,7 +215,7 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Create a ``\(node.kind.syntaxType)`` node from a specialized optional syntax node.
+        /// Create a \(raw: node.kind.doccLink) node from a specialized optional syntax node.
         public init?(fromProtocol syntax: \(node.kind.protocolType)?) {
           guard let syntax = syntax else { return nil }
           self.init(fromProtocol: syntax)

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxNodeCasting.swift

@@ -57,7 +57,7 @@ func choiceNodeCastingMethods(for syntaxNodeKind: SyntaxNodeKind) -> MemberBlock
   } else {
     DeclSyntax(
       """
-      /// Checks if the current syntax node can be cast to ``\(syntaxNodeKind.syntaxType)``.
+      /// Checks if the current syntax node can be cast to \(raw: syntaxNodeKind.doccLink).
       ///
       /// - Returns: `true` if the node can be cast, `false` otherwise.
       \(apiAttributes)\
@@ -69,9 +69,9 @@ func choiceNodeCastingMethods(for syntaxNodeKind: SyntaxNodeKind) -> MemberBlock
 
     DeclSyntax(
       """
-      /// Attempts to cast the current syntax node to ``\(syntaxNodeKind.syntaxType)``.
+      /// Attempts to cast the current syntax node to \(raw: syntaxNodeKind.doccLink).
       ///
-      /// - Returns: An instance of ``\(syntaxNodeKind.syntaxType)``, or `nil` if the cast fails.
+      /// - Returns: An instance of \(raw: syntaxNodeKind.doccLink), or `nil` if the cast fails.
       \(apiAttributes)\
       public func `as`(_ syntaxType: \(syntaxNodeKind.syntaxType).Type) -> \(syntaxNodeKind.syntaxType)? {
         return \(syntaxNodeKind.syntaxType).init(self)
@@ -81,9 +81,9 @@ func choiceNodeCastingMethods(for syntaxNodeKind: SyntaxNodeKind) -> MemberBlock
 
     DeclSyntax(
       """
-      /// Force-casts the current syntax node to ``\(syntaxNodeKind.syntaxType)``.
+      /// Force-casts the current syntax node to \(raw: syntaxNodeKind.doccLink).
       ///
-      /// - Returns: An instance of ``\(syntaxNodeKind.syntaxType)``.
+      /// - Returns: An instance of \(raw: syntaxNodeKind.doccLink).
       /// - Warning: This function will crash if the cast is not possible. Use `as` to safely attempt a cast.
       \(apiAttributes)\
       public func cast(_ syntaxType: \(syntaxNodeKind.syntaxType).Type) -> \(syntaxNodeKind.syntaxType) {

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxRewriterFile.swift

@@ -122,7 +122,7 @@ let syntaxRewriterFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       if (node.base == .syntax || node.base == .syntaxCollection) && node.kind != .missing {
         DeclSyntax(
           """
-          /// Visit a ``\(node.kind.syntaxType)``.
+          /// Visit a \(raw: node.kind.doccLink).
           ///   - Parameter node: the node that is being visited
           ///   - Returns: the rewritten node
           \(node.apiAttributes())\
@@ -134,7 +134,7 @@ let syntaxRewriterFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       } else {
         DeclSyntax(
           """
-          /// Visit a ``\(node.kind.syntaxType)``.
+          /// Visit a \(raw: node.kind.doccLink).
           ///   - Parameter node: the node that is being visited
           ///   - Returns: the rewritten node
           \(node.apiAttributes())\

CodeGeneration/Sources/generate-swift-syntax/templates/swiftsyntax/SyntaxVisitorFile.swift

@@ -53,7 +53,7 @@ let syntaxVisitorFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
     for node in SYNTAX_NODES where !node.kind.isBase {
       DeclSyntax(
         """
-        /// Visiting ``\(node.kind.syntaxType)`` specifically.
+        /// Visiting \(raw: node.kind.doccLink) specifically.
         ///   - Parameter node: the node we are visiting.
         ///   - Returns: how should we continue visiting.
         \(node.apiAttributes())\
@@ -65,7 +65,7 @@ let syntaxVisitorFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// The function called after visiting ``\(node.kind.syntaxType)`` and its descendants.
+        /// The function called after visiting \(raw: node.kind.doccLink) and its descendants.
         ///   - node: the node we just finished visiting.
         \(node.apiAttributes())\
         open func visitPost(_ node: \(node.kind.syntaxType)) {}

Sources/SwiftSyntax/generated/SyntaxBaseNodes.swift

@@ -14,7 +14,7 @@
 
 // MARK: - DeclSyntax
 
-/// Protocol to which all ``DeclSyntax`` nodes conform. 
+/// Protocol to which all ``DeclSyntax`` nodes conform.
 ///
 /// Extension point to add common methods to all ``DeclSyntax`` nodes.
 ///
@@ -315,7 +315,7 @@ public extension _LeafDeclSyntaxNodeProtocol {
 
 // MARK: - ExprSyntax
 
-/// Protocol to which all ``ExprSyntax`` nodes conform. 
+/// Protocol to which all ``ExprSyntax`` nodes conform.
 ///
 /// Extension point to add common methods to all ``ExprSyntax`` nodes.
 ///
@@ -673,7 +673,7 @@ public extension _LeafExprSyntaxNodeProtocol {
 
 // MARK: - PatternSyntax
 
-/// Protocol to which all ``PatternSyntax`` nodes conform. 
+/// Protocol to which all ``PatternSyntax`` nodes conform.
 ///
 /// Extension point to add common methods to all ``PatternSyntax`` nodes.
 ///
@@ -940,7 +940,7 @@ public extension _LeafPatternSyntaxNodeProtocol {
 
 // MARK: - StmtSyntax
 
-/// Protocol to which all ``StmtSyntax`` nodes conform. 
+/// Protocol to which all ``StmtSyntax`` nodes conform.
 ///
 /// Extension point to add common methods to all ``StmtSyntax`` nodes.
 ///
@@ -1226,7 +1226,7 @@ public extension _LeafStmtSyntaxNodeProtocol {
 
 // MARK: - TypeSyntax
 
-/// Protocol to which all ``TypeSyntax`` nodes conform. 
+/// Protocol to which all ``TypeSyntax`` nodes conform.
 ///
 /// Extension point to add common methods to all ``TypeSyntax`` nodes.
 ///

Sources/SwiftSyntax/generated/SyntaxCollections.swift

@@ -880,7 +880,7 @@ public struct LabeledExprListSyntax: SyntaxCollection, SyntaxHashable {
 ///
 /// ### Children
 /// 
-/// ``LifetimeSpecifierArgumentSyntax`` `*`
+/// `LifetimeSpecifierArgumentSyntax` `*`
 #if compiler(>=5.8)
 @_spi(ExperimentalLanguageFeatures)
 #endif
@@ -1675,7 +1675,7 @@ public struct TupleTypeElementListSyntax: SyntaxCollection, SyntaxHashable {
 
 /// ### Children
 /// 
-/// (``SimpleTypeSpecifierSyntax`` | ``LifetimeTypeSpecifierSyntax``) `*`
+/// (``SimpleTypeSpecifierSyntax`` | `LifetimeTypeSpecifierSyntax`) `*`
 ///
 /// ### Contained in
 /// 
@@ -1748,7 +1748,7 @@ public struct TypeSpecifierListSyntax: SyntaxCollection, SyntaxHashable {
       return self.as(SimpleTypeSpecifierSyntax.self)!
     }
 
-    /// Checks if the current syntax node can be cast to ``LifetimeTypeSpecifierSyntax``.
+    /// Checks if the current syntax node can be cast to `LifetimeTypeSpecifierSyntax`.
     ///
     /// - Returns: `true` if the node can be cast, `false` otherwise.
     #if compiler(>=5.8)
@@ -1758,19 +1758,19 @@ public struct TypeSpecifierListSyntax: SyntaxCollection, SyntaxHashable {
       return self.as(syntaxType) != nil
     }
 
-    /// Attempts to cast the current syntax node to ``LifetimeTypeSpecifierSyntax``.
+    /// Attempts to cast the current syntax node to `LifetimeTypeSpecifierSyntax`.
     ///
-    /// - Returns: An instance of ``LifetimeTypeSpecifierSyntax``, or `nil` if the cast fails.
+    /// - Returns: An instance of `LifetimeTypeSpecifierSyntax`, or `nil` if the cast fails.
     #if compiler(>=5.8)
     @_spi(ExperimentalLanguageFeatures)
     #endif
     public func `as`(_ syntaxType: LifetimeTypeSpecifierSyntax.Type) -> LifetimeTypeSpecifierSyntax? {
       return LifetimeTypeSpecifierSyntax.init(self)
     }
 
-    /// Force-casts the current syntax node to ``LifetimeTypeSpecifierSyntax``.
+    /// Force-casts the current syntax node to `LifetimeTypeSpecifierSyntax`.
     ///
-    /// - Returns: An instance of ``LifetimeTypeSpecifierSyntax``.
+    /// - Returns: An instance of `LifetimeTypeSpecifierSyntax`.
     /// - Warning: This function will crash if the cast is not possible. Use `as` to safely attempt a cast.
     #if compiler(>=5.8)
     @_spi(ExperimentalLanguageFeatures)

Sources/SwiftSyntax/generated/SyntaxRewriter.swift

@@ -668,7 +668,7 @@ open class SyntaxRewriter {
     return StmtSyntax(visitChildren(node))
   }
 
-  /// Visit a ``DoExprSyntax``.
+  /// Visit a `DoExprSyntax`.
   ///   - Parameter node: the node that is being visited
   ///   - Returns: the rewritten node
   #if compiler(>=5.8)
@@ -1203,7 +1203,7 @@ open class SyntaxRewriter {
     return visitChildren(node)
   }
 
-  /// Visit a ``LifetimeSpecifierArgumentListSyntax``.
+  /// Visit a `LifetimeSpecifierArgumentListSyntax`.
   ///   - Parameter node: the node that is being visited
   ///   - Returns: the rewritten node
   #if compiler(>=5.8)
@@ -1213,7 +1213,7 @@ open class SyntaxRewriter {
     return visitChildren(node)
   }
 
-  /// Visit a ``LifetimeSpecifierArgumentSyntax``.
+  /// Visit a `LifetimeSpecifierArgumentSyntax`.
   ///   - Parameter node: the node that is being visited
   ///   - Returns: the rewritten node
   #if compiler(>=5.8)
@@ -1223,7 +1223,7 @@ open class SyntaxRewriter {
     return visitChildren(node)
   }
 
-  /// Visit a ``LifetimeSpecifierArgumentsSyntax``.
+  /// Visit a `LifetimeSpecifierArgumentsSyntax`.
   ///   - Parameter node: the node that is being visited
   ///   - Returns: the rewritten node
   #if compiler(>=5.8)
@@ -1233,7 +1233,7 @@ open class SyntaxRewriter {
     return visitChildren(node)
   }
 
-  /// Visit a ``LifetimeTypeSpecifierSyntax``.
+  /// Visit a `LifetimeTypeSpecifierSyntax`.
   ///   - Parameter node: the node that is being visited
   ///   - Returns: the rewritten node
   #if compiler(>=5.8)
@@ -1838,7 +1838,7 @@ open class SyntaxRewriter {
     return ExprSyntax(visitChildren(node))
   }
 
-  /// Visit a ``ThenStmtSyntax``.
+  /// Visit a `ThenStmtSyntax`.
   ///   - Parameter node: the node that is being visited
   ///   - Returns: the rewritten node
   #if compiler(>=5.8)