Merge pull request #1702 from ahoppen/ahoppen/backticks

Wrap references to public types in comments in double backticks

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/CommonNodes.swift

@@ -152,13 +152,13 @@ public let COMMON_NODES: [Node] = [
       Child(
         name: "Attributes",
         kind: .collection(kind: .attributeList, collectionElementName: "Attribute"),
-        documentation: "If there were standalone attributes without a declaration to attach them to, the `MissingDeclSyntax` will contain these.",
+        documentation: "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"),
-        documentation: "If there were standalone modifiers without a declaration to attach them to, the `MissingDeclSyntax` will contain these.",
+        documentation: "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

@@ -707,7 +707,7 @@ public let EXPR_NODES: [Node] = [
     kind: .exprList,
     base: .syntaxCollection,
     nameForDiagnostics: nil,
-    documentation: "A list of expressions connected by operators. This list is contained by a `SequenceExprSyntax`.",
+    documentation: "A list of expressions connected by operators. This list is contained by a ``SequenceExprSyntax``.",
     elementChoices: [.expr]
   ),
 

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

@@ -21,10 +21,10 @@ public enum SyntaxOrTokenNodeKind: Hashable {
   case token(tokenKind: String)
 }
 
-/// 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 {
     let buildableKind: SyntaxOrTokenNodeKind
@@ -96,7 +96,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(kind: .node(kind: kind))
   }
 
-  /// The node's syntax kind as `SyntaxBuildableType`.
+  /// The node's syntax kind as ``SyntaxBuildableType``.
   var baseType: SyntaxBuildableType {
     if base == .syntaxCollection {
       return SyntaxBuildableType(kind: .node(kind: .syntax))

CodeGeneration/Sources/Utils/SyntaxBuildableType.swift

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

@@ -42,8 +42,8 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       !node.documentation.isEmpty
       ? node.documentation
       : """
-      /// `\(node.kind.syntaxType)` represents a collection of one or more
-      /// `\(node.collectionElementType.syntaxBaseName)` nodes. \(node.kind.syntaxType) behaves
+      /// ``\(node.kind.syntaxType)`` represents a collection of one or more
+      /// ``\(node.collectionElementType.syntaxBaseName)`` nodes. ``\(node.kind.syntaxType)`` behaves
       /// as a regular Swift collection, and has accessors that return new
       /// versions of the collection with different children.
       """
@@ -187,12 +187,12 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(node.kind.syntaxType)` by replacing the underlying layout with
+        /// Creates a new ``\(node.kind.syntaxType)`` 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 `\(node.kind.syntaxType)` with the new layout underlying it.
+        /// - Returns: A new ``\(node.kind.syntaxType)`` with the new layout underlying it.
         internal func replacingLayout(_ layout: [RawSyntax?]) -> \(node.kind.syntaxType) {
           let arena = SyntaxArena()
           let newRaw = layoutView.replacingLayout(with: layout, arena: arena)
@@ -204,11 +204,11 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(node.kind.syntaxType)` by appending the provided syntax element
+        /// Creates a new ``\(node.kind.syntaxType)`` by appending the provided syntax element
         /// to the children.
         ///
         /// - Parameter syntax: The element to append.
-        /// - Returns: A new `\(node.kind.syntaxType)` with that element appended to the end.
+        /// - Returns: A new ``\(node.kind.syntaxType)`` with that element appended to the end.
         public func appending(_ syntax: Element) -> \(node.kind.syntaxType) {
           var newLayout = layoutView.formLayoutArray()
           newLayout.append(syntax.raw)
@@ -219,11 +219,11 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(node.kind.syntaxType)` by prepending the provided syntax element
+        /// Creates a new ``\(node.kind.syntaxType)`` by prepending the provided syntax element
         /// to the children.
         ///
         /// - Parameter syntax: The element to prepend.
-        /// - Returns: A new `\(node.kind.syntaxType)` with that element prepended to the
+        /// - Returns: A new ``\(node.kind.syntaxType)`` with that element prepended to the
         ///            beginning.
         public func prepending(_ syntax: Element) -> \(node.kind.syntaxType) {
           return inserting(syntax, at: 0)
@@ -233,14 +233,14 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(node.kind.syntaxType)` by inserting the provided syntax element
+        /// Creates a new ``\(node.kind.syntaxType)`` 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 `\(node.kind.syntaxType)` with that element appended to the end.
+        /// - Returns: A new ``\(node.kind.syntaxType)`` with that element appended to the end.
         public func inserting(_ syntax: Element, at index: Int) -> \(node.kind.syntaxType) {
           var newLayout = layoutView.formLayoutArray()
           /// Make sure the index is a valid insertion index (0 to 1 past the end)
@@ -254,14 +254,14 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(node.kind.syntaxType)` by replacing the syntax element
+        /// Creates a new ``\(node.kind.syntaxType)`` 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 `\(node.kind.syntaxType)` with the new element at the provided index.
+        /// - Returns: A new ``\(node.kind.syntaxType)`` with the new element at the provided index.
         public func replacing(childAt index: Int, with syntax: Element) -> \(node.kind.syntaxType) {
           var newLayout = layoutView.formLayoutArray()
           /// Make sure the index is a valid index for replacing
@@ -275,11 +275,11 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(node.kind.syntaxType)` by removing the syntax element at the
+        /// Creates a new ``\(node.kind.syntaxType)`` by removing the syntax element at the
         /// provided index.
         ///
         /// - Parameter index: The index of the element to remove from the collection.
-        /// - Returns: A new `\(node.kind.syntaxType)` with the element at the provided index
+        /// - Returns: A new ``\(node.kind.syntaxType)`` with the element at the provided index
         ///            removed.
         public func removing(childAt index: Int) -> \(node.kind.syntaxType) {
           var newLayout = layoutView.formLayoutArray()
@@ -291,9 +291,9 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(node.kind.syntaxType)` by removing the first element.
+        /// Creates a new ``\(node.kind.syntaxType)`` by removing the first element.
         ///
-        /// - Returns: A new `\(node.kind.syntaxType)` with the first element removed.
+        /// - Returns: A new ``\(node.kind.syntaxType)`` with the first element removed.
         public func removingFirst() -> \(node.kind.syntaxType) {
           var newLayout = layoutView.formLayoutArray()
           newLayout.removeFirst()
@@ -304,9 +304,9 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
       DeclSyntax(
         """
-        /// Creates a new `\(node.kind.syntaxType)` by removing the last element.
+        /// Creates a new ``\(node.kind.syntaxType)`` by removing the last element.
         ///
-        /// - Returns: A new `\(node.kind.syntaxType)` with the last element removed.
+        /// - Returns: A new ``\(node.kind.syntaxType)`` with the last element removed.
         public func removingLast() -> \(node.kind.syntaxType) {
           var newLayout = layoutView.formLayoutArray()
           newLayout.removeLast()
@@ -318,7 +318,7 @@ let syntaxCollectionsFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
 
     try! ExtensionDeclSyntax(
       """
-      /// Conformance for `\(node.kind.syntaxType)` to the `BidirectionalCollection` protocol.
+      /// Conformance for ``\(node.kind.syntaxType)`` to the `BidirectionalCollection` protocol.
       extension \(node.kind.syntaxType): BidirectionalCollection
       """
     ) {

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

@@ -66,7 +66,7 @@ func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {
 
         DeclSyntax(
           """
-          /// Creates a `\(node.kind.syntaxType)` node from the given `SyntaxData`. This assumes
+          /// Creates a ``\(node.kind.syntaxType)`` 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) {
@@ -192,7 +192,7 @@ func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {
 
             DeclSyntax(
               """
-              /// Adds the provided `\(raw: childElt)` to the node's `\(raw: child.varName)`
+              /// Adds the provided `element` to the node's `\(raw: child.varName)`
               /// collection.
               /// - param element: The new `\(raw: childElt)` to add to the node's
               ///                  `\(raw: child.varName)` collection.

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

@@ -36,7 +36,7 @@ let syntaxRewriterFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       if (node.base == .syntax || node.base == .syntaxCollection) && node.kind != .missing {
         DeclSyntax(
           """
-          /// Visit a `\(node.kind.syntaxType)`.
+          /// Visit a ``\(node.kind.syntaxType)``.
           ///   - Parameter node: the node that is being visited
           ///   - Returns: the rewritten node
           open func visit(_ node: \(node.kind.syntaxType)) -> \(node.kind.syntaxType) {
@@ -47,7 +47,7 @@ let syntaxRewriterFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       } else {
         DeclSyntax(
           """
-          /// Visit a `\(node.kind.syntaxType)`.
+          /// Visit a ``\(node.kind.syntaxType)``.
           ///   - Parameter node: the node that is being visited
           ///   - Returns: the rewritten node
           open func visit(_ node: \(node.kind.syntaxType)) -> \(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.kind.isBase {
       DeclSyntax(
         """
-        /// Visiting `\(node.kind.syntaxType)` specifically.
+        /// Visiting ``\(node.kind.syntaxType)`` specifically.
         ///   - Parameter node: the node we are visiting.
         ///   - Returns: the sum of whatever the child visitors return.
         func visit(_ node: \(node.kind.syntaxType)) -> ResultType
@@ -47,7 +47,7 @@ let syntaxTransformFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
     for node in SYNTAX_NODES where !node.kind.isBase {
       DeclSyntax(
         """
-        /// Visiting `\(node.kind.syntaxType)` specifically.
+        /// Visiting ``\(node.kind.syntaxType)`` specifically.
         ///   - Parameter node: the node we are visiting.
         ///   - Returns: nil by default.
         public func visit(_ node: \(node.kind.syntaxType)) -> ResultType {