Wrap references to public types in comments in double backticks

This makes the types show up as links in the generated docc documentation

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift

@@ -154,13 +154,13 @@ public let COMMON_NODES: [Node] = [
       Child(
         name: "Attributes",
         kind: .collection(kind: "AttributeList", collectionElementName: "Attribute"),
-        description: "If there were standalone attributes without a declaration to attach them to, the `MissingDeclSyntax` will contain these.",
+        description: "If there were standalone attributes without a declaration to attach them to, the ``MissingDeclSyntax`` will contain these.",
         isOptional: true
       ),
       Child(
         name: "Modifiers",
         kind: .collection(kind: "ModifierList", collectionElementName: "Modifier"),
-        description: "If there were standalone modifiers without a declaration to attach them to, the `MissingDeclSyntax` will contain these.",
+        description: "If there were standalone modifiers without a declaration to attach them to, the ``MissingDeclSyntax`` will contain these.",
         isOptional: true
       ),
       Child(

CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift

@@ -710,7 +710,7 @@ public let EXPR_NODES: [Node] = [
   Node(
     name: "ExprList",
     nameForDiagnostics: nil,
-    description: "A list of expressions connected by operators. This list is contained by a `SequenceExprSyntax`.",
+    description: "A list of expressions connected by operators. This list is contained by a ``SequenceExprSyntax``.",
     kind: "SyntaxCollection",
     element: "Expr",
     elementName: "Expression"

CodeGeneration/Sources/Utils/CodeGenerationFormat.swift

@@ -92,7 +92,7 @@ public class CodeGenerationFormat: BasicFormat {
   // MARK: - Private
 
   private func shouldBeSeparatedByTwoNewlines(node: CodeBlockItemSyntax) -> Bool {
-    // First item in the `CodeBlockItemListSyntax` don't need a newline or identation if the parent is a `SourceFileSyntax`.
+    // First item in the ``CodeBlockItemListSyntax`` don't need a newline or identation if the parent is a ``SourceFileSyntax``.
     // We want to group imports so newline between them should be omitted
     return node.parent?.as(CodeBlockItemListSyntax.self)?.first == node || node.item.is(ImportDeclSyntax.self)
   }

CodeGeneration/Sources/Utils/SyntaxBuildableChild.swift

@@ -14,10 +14,10 @@ import SwiftSyntax
 import SwiftSyntaxBuilder
 import SyntaxSupport
 
-/// Extension to the `Child` type to provide functionality specific to
+/// Extension to the ``Child`` type to provide functionality specific to
 /// SwiftSyntaxBuilder.
 public extension Child {
-  /// The type of this child, represented by a `SyntaxBuildableType`, which can
+  /// The type of this child, represented by a ``SyntaxBuildableType``, which can
   /// be used to create the corresponding `Buildable` and `ExpressibleAs` types.
   var type: SyntaxBuildableType {
     SyntaxBuildableType(
@@ -81,7 +81,7 @@ public extension Child {
 
   /// If this node is a token that can't contain arbitrary text, generate a Swift
   /// `precondition` statement that verifies the variable with name var_name and of type
-  /// `TokenSyntax` contains one of the supported text options. Otherwise return `nil`.
+  /// ``TokenSyntax`` contains one of the supported text options. Otherwise return `nil`.
   func generateAssertStmtTextChoices(varName: String) -> FunctionCallExprSyntax? {
     guard case .token(choices: let choices, requiresLeadingSpace: _, requiresTrailingSpace: _) = kind else {
       return nil

CodeGeneration/Sources/Utils/SyntaxBuildableNode.swift

@@ -12,15 +12,15 @@
 
 import SyntaxSupport
 
-/// Extension to the `Node` type to provide functionality specific to
+/// Extension to the ``Node`` type to provide functionality specific to
 /// SwiftSyntaxBuilder.
 public extension Node {
-  /// The node's syntax kind as `SyntaxBuildableType`.
+  /// The node's syntax kind as ``SyntaxBuildableType``.
   var type: SyntaxBuildableType {
     SyntaxBuildableType(syntaxKind: syntaxKind)
   }
 
-  /// The node's syntax kind as `SyntaxBuildableType`.
+  /// The node's syntax kind as ``SyntaxBuildableType``.
   var baseType: SyntaxBuildableType {
     if baseKind == "SyntaxCollection" {
       return SyntaxBuildableType(syntaxKind: "Syntax")

CodeGeneration/Sources/Utils/SyntaxBuildableType.swift

@@ -85,7 +85,7 @@ public struct SyntaxBuildableType: Hashable {
   /// These names look as follows:
   ///  - For nodes: The node name, e.g. `IdentifierExpr` (these are implemented as structs)
   ///  - For base kinds: `<BaseKind>Buildable`, e.g. `ExprBuildable` (these are implemented as protocols)
-  ///  - For token: `TokenSyntax` (tokens don't have a dedicated type in SwiftSyntaxBuilder)
+  ///  - For token: ``TokenSyntax`` (tokens don't have a dedicated type in SwiftSyntaxBuilder)
   /// If the type is optional, the type is wrapped in an `OptionalType`.
   public var buildable: TypeSyntax {
     optionalWrapped(type: SimpleTypeIdentifierSyntax(name: .identifier(syntaxBaseName)))

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

@@ -54,7 +54,7 @@ let keywordFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       /// This is really unfortunate. Really, we should have a `switch` in
       /// `Keyword.defaultText` to return the keyword's kind but the constant lookup
       /// table is significantly faster. Ideally, we could also get the compiler to
-      /// constant-evaluate `Keyword.spi.defaultText` to a `SyntaxText` but I don't
+      /// constant-evaluate `Keyword.spi.defaultText` to a ``SyntaxText`` but I don't
       /// see how that's possible right now.
       private static let keywordTextLookupTable: [SyntaxText] = \(lookupTable)
       """

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

@@ -18,7 +18,7 @@ import Utils
 let syntaxAnyVisitorFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
   try! ClassDeclSyntax(
     """
-    /// A `SyntaxVisitor` that can visit the nodes as generic `Syntax` values.
+    /// A `SyntaxVisitor` that can visit the nodes as generic ``Syntax`` values.
     ///
     /// This subclass of `SyntaxVisitor` is slower than the type-specific visitation
     /// of `SyntaxVisitor`. Use `SyntaxAnyVisitor` if the `visitAny(_)` function

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

@@ -21,8 +21,8 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       """
       // MARK: - \(raw: node.name)
 
-      /// Protocol to which all `\(raw: node.name)` nodes conform. Extension point to add
-      /// common methods to all `\(raw: node.name)` nodes.
+      /// Protocol to which all ``\(raw: node.name)`` nodes conform. Extension point to add
+      /// common methods to all ``\(raw: node.name)`` nodes.
       /// DO NOT CONFORM TO THIS PROTOCOL YOURSELF!
       public protocol \(raw: node.name)Protocol: \(raw: node.baseType.baseName)Protocol {}
       """
@@ -62,7 +62,7 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Create a `\(raw: node.name)` node from a specialized syntax node.
+        /// Create a ``\(raw: node.name)`` node from a specialized syntax node.
         public init(_ syntax: some \(raw: node.name)Protocol) {
           // 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
@@ -74,7 +74,7 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Create a `\(raw: node.name)` node from a specialized optional syntax node.
+        /// Create a ``\(raw: node.name)`` node from a specialized optional syntax node.
         public init?(_ syntax: (some \(raw: node.name)Protocol)?) {
           guard let syntax = syntax else { return nil }
           self.init(syntax)
@@ -95,7 +95,7 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Create a `\(raw: node.name)` node from a specialized optional syntax node.
+        /// Create a ``\(raw: node.name)`` node from a specialized optional syntax node.
         public init?(fromProtocol syntax: \(raw: node.name)Protocol?) {
           guard let syntax = syntax else { return nil }
           self.init(fromProtocol: syntax)
@@ -131,8 +131,8 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       try InitializerDeclSyntax(
         """
-        /// Creates a `\(raw: node.name)` node from the given `SyntaxData`. This assumes
-        /// that the `SyntaxData` is of the correct kind. If it is not, the behaviour
+        /// Creates a ``\(raw: node.name)`` node from the given ``SyntaxData``. This assumes
+        /// that the ``SyntaxData`` is of the correct kind. If it is not, the behaviour
         /// is undefined.
         internal init(_ data: SyntaxData)
         """

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

@@ -41,8 +41,8 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
     let documentation =
       node.description.map { "/// " + $0 }
         ?? """
-        /// `\(node.name)` represents a collection of one or more
-        /// `\(node.collectionElement)` nodes. \(node.name) behaves
+        /// ``\(node.name)`` represents a collection of one or more
+        /// `\(node.collectionElement)` nodes. ``\(node.name)`` behaves
         /// as a regular Swift collection, and has accessors that return new
         /// versions of the collection with different children.
         """
@@ -186,12 +186,12 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(raw: node.name)` by replacing the underlying layout with
+        /// Creates a new ``\(raw: node.name)`` by replacing the underlying layout with
         /// a different set of raw syntax nodes.
         ///
         /// - Parameter layout: The new list of raw syntax nodes underlying this
         ///                     collection.
-        /// - Returns: A new `\(raw: node.name)` with the new layout underlying it.
+        /// - Returns: A new ``\(raw: node.name)`` with the new layout underlying it.
         internal func replacingLayout(_ layout: [RawSyntax?]) -> \(raw: node.name) {
           let arena = SyntaxArena()
           let newRaw = layoutView.replacingLayout(with: layout, arena: arena)
@@ -203,11 +203,11 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(raw: node.name)` by appending the provided syntax element
+        /// Creates a new ``\(raw: node.name)`` by appending the provided syntax element
         /// to the children.
         ///
         /// - Parameter syntax: The element to append.
-        /// - Returns: A new `\(raw: node.name)` with that element appended to the end.
+        /// - Returns: A new ``\(raw: node.name)`` with that element appended to the end.
         public func appending(_ syntax: Element) -> \(raw: node.name) {
           var newLayout = layoutView.formLayoutArray()
           newLayout.append(syntax.raw)
@@ -218,11 +218,11 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(raw: node.name)` by prepending the provided syntax element
+        /// Creates a new ``\(raw: node.name)`` by prepending the provided syntax element
         /// to the children.
         ///
         /// - Parameter syntax: The element to prepend.
-        /// - Returns: A new `\(raw: node.name)` with that element prepended to the
+        /// - Returns: A new ``\(raw: node.name)`` with that element prepended to the
         ///            beginning.
         public func prepending(_ syntax: Element) -> \(raw: node.name) {
           return inserting(syntax, at: 0)
@@ -232,14 +232,14 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(raw: node.name)` by inserting the provided syntax element
+        /// Creates a new ``\(raw: node.name)`` by inserting the provided syntax element
         /// at the provided index in the children.
         ///
         /// - Parameters:
         ///   - syntax: The element to insert.
         ///   - index: The index at which to insert the element in the collection.
         ///
-        /// - Returns: A new `\(raw: node.name)` with that element appended to the end.
+        /// - Returns: A new ``\(raw: node.name)`` with that element appended to the end.
         public func inserting(_ syntax: Element, at index: Int) -> \(raw: node.name) {
           var newLayout = layoutView.formLayoutArray()
           /// Make sure the index is a valid insertion index (0 to 1 past the end)
@@ -253,14 +253,14 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(raw: node.name)` by replacing the syntax element
+        /// Creates a new ``\(raw: node.name)`` by replacing the syntax element
         /// at the provided index.
         ///
         /// - Parameters:
         ///   - index: The index at which to replace the element in the collection.
         ///   - syntax: The element to replace with.
         ///
-        /// - Returns: A new `\(raw: node.name)` with the new element at the provided index.
+        /// - Returns: A new ``\(raw: node.name)`` with the new element at the provided index.
         public func replacing(childAt index: Int, with syntax: Element) -> \(raw: node.name) {
           var newLayout = layoutView.formLayoutArray()
           /// Make sure the index is a valid index for replacing
@@ -274,11 +274,11 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(raw: node.name)` by removing the syntax element at the
+        /// Creates a new ``\(raw: node.name)`` by removing the syntax element at the
         /// provided index.
         ///
         /// - Parameter index: The index of the element to remove from the collection.
-        /// - Returns: A new `\(raw: node.name)` with the element at the provided index
+        /// - Returns: A new ``\(raw: node.name)`` with the element at the provided index
         ///            removed.
         public func removing(childAt index: Int) -> \(raw: node.name) {
           var newLayout = layoutView.formLayoutArray()
@@ -290,9 +290,9 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(raw: node.name)` by removing the first element.
+        /// Creates a new ``\(raw: node.name)`` by removing the first element.
         ///
-        /// - Returns: A new `\(raw: node.name)` with the first element removed.
+        /// - Returns: A new ``\(raw: node.name)`` with the first element removed.
         public func removingFirst() -> \(raw: node.name) {
           var newLayout = layoutView.formLayoutArray()
           newLayout.removeFirst()
@@ -303,9 +303,9 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(raw: node.name)` by removing the last element.
+        /// Creates a new ``\(raw: node.name)`` by removing the last element.
         ///
-        /// - Returns: A new `\(raw: node.name)` with the last element removed.
+        /// - Returns: A new ``\(raw: node.name)`` with the last element removed.
         public func removingLast() -> \(raw: node.name) {
           var newLayout = layoutView.formLayoutArray()
           newLayout.removeLast()
@@ -317,7 +317,7 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
     try! ExtensionDeclSyntax(
       """
-      /// Conformance for `\(raw: node.name)` to the `BidirectionalCollection` protocol.
+      /// Conformance for ``\(raw: node.name)`` to the `BidirectionalCollection` protocol.
       extension \(raw: node.name): BidirectionalCollection
       """
     ) {

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

@@ -67,7 +67,7 @@ func syntaxNode(emitKind: String) -> SourceFileSyntax {
 
         DeclSyntax(
           """
-          /// Creates a `\(raw: node.name)` node from the given `SyntaxData`. This assumes
+          /// Creates a ``\(raw: node.name)`` node from the given ``SyntaxData``. This assumes
           /// that the `SyntaxData` is of the correct kind. If it is not, the behaviour
           /// is undefined.
           internal init(_ data: SyntaxData) {
@@ -194,7 +194,7 @@ func syntaxNode(emitKind: String) -> SourceFileSyntax {
 
             DeclSyntax(
               """
-              /// Adds the provided `\(raw: childElt)` to the node's `\(raw: child.swiftName)`
+              /// Adds the provided `element` to the node's `\(raw: child.swiftName)`
               /// collection.
               /// - param element: The new `\(raw: childElt)` to add to the node's
               ///                  `\(raw: child.swiftName)` collection.

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

@@ -36,7 +36,7 @@ let syntaxRewriterFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       if node.baseType.baseName == "Syntax" && node.name != "MissingSyntax" {
         DeclSyntax(
           """
-          /// Visit a `\(raw: node.name)`.
+          /// Visit a ``\(raw: node.name)``.
           ///   - Parameter node: the node that is being visited
           ///   - Returns: the rewritten node
           open func visit(_ node: \(raw: node.name)) -> \(raw: node.name) {
@@ -47,7 +47,7 @@ let syntaxRewriterFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       } else {
         DeclSyntax(
           """
-          /// Visit a `\(raw: node.name)`.
+          /// Visit a ``\(raw: node.name)``.
           ///   - Parameter node: the node that is being visited
           ///   - Returns: the rewritten node
           open func visit(_ node: \(raw: node.name)) -> \(raw: node.baseType.syntaxBaseName) {
@@ -60,7 +60,7 @@ let syntaxRewriterFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
     DeclSyntax(
       """
-      /// Visit a `TokenSyntax`.
+      /// Visit a ``TokenSyntax``.
       ///   - Parameter node: the node that is being visited
       ///   - Returns: the rewritten node
       open func visit(_ token: TokenSyntax) -> TokenSyntax {

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

@@ -26,7 +26,7 @@ let syntaxTransformFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
     for node in SYNTAX_NODES where node.isVisitable {
       DeclSyntax(
         """
-        /// Visiting `\(raw: node.name)` specifically.
+        /// Visiting ``\(raw: node.name)`` specifically.
         ///   - Parameter node: the node we are visiting.
         ///   - Returns: the sum of whatever the child visitors return.
         func visit(_ node: \(raw: node.name)) -> ResultType
@@ -47,7 +47,7 @@ let syntaxTransformFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
     for node in SYNTAX_NODES where node.isVisitable {
       DeclSyntax(
         """
-        /// Visiting `\(raw: node.name)` specifically.
+        /// Visiting ``\(raw: node.name)`` specifically.
         ///   - Parameter node: the node we are visiting.
         ///   - Returns: nil by default.
         public func visit(_ node: \(raw: node.name)) -> ResultType {

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

@@ -53,7 +53,7 @@ let syntaxVisitorFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
     for node in SYNTAX_NODES where node.isVisitable {
       DeclSyntax(
         """
-        /// Visiting `\(raw: node.name)` specifically.
+        /// Visiting ``\(raw: node.name)`` specifically.
         ///   - Parameter node: the node we are visiting.
         ///   - Returns: how should we continue visiting.
         open func visit(_ node: \(raw: node.name)) -> SyntaxVisitorContinueKind {
@@ -64,7 +64,7 @@ let syntaxVisitorFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// The function called after visiting `\(raw: node.name)` and its descendents.
+        /// The function called after visiting ``\(raw: node.name)`` and its descendents.
         ///   - node: the node we just finished visiting.
         open func visitPost(_ node: \(raw: node.name)) {}
         """
@@ -73,7 +73,7 @@ let syntaxVisitorFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
     DeclSyntax(
       """
-      /// Visiting `TokenSyntax` specifically.
+      /// Visiting ``TokenSyntax`` specifically.
       ///   - Parameter node: the node we are visiting.
       ///   - Returns: how should we continue visiting.
       open func visit(_ token: TokenSyntax) -> SyntaxVisitorContinueKind {