Merge pull request #2034 from ahoppen/ahoppen/format-documentation

Format doc comments so they render better in docc

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/DeclNodes.swift

@@ -242,7 +242,9 @@ public let DECL_NODES: [Node] = [
     base: .decl,
     nameForDiagnostics: "associatedtype declaration",
     documentation: """
-      An associated type declaration like the following.
+      An `associatedtype` declaration
+
+      An example of an associatedtype declaration is
 
       ```swift
       associatedtype Item
@@ -332,7 +334,9 @@ public let DECL_NODES: [Node] = [
     base: .decl,
     nameForDiagnostics: "class",
     documentation: """
-      A class declaration like the following.
+      A `class` declaration
+
+      An example of a class declaration is
 
       ```swift
       class SomeClass {
@@ -498,7 +502,9 @@ public let DECL_NODES: [Node] = [
     base: .decl,
     nameForDiagnostics: "deinitializer",
     documentation: """
-      A deinitializer declaration like the following.
+      A `deint` declaration
+
+      An example of a deinitializer is
 
       ```swift
       deinit {
@@ -1135,7 +1141,9 @@ public let DECL_NODES: [Node] = [
     base: .decl,
     nameForDiagnostics: "import",
     documentation: """
-      An import declaration like the following.
+      An `import` declaration
+
+      An example of an import declaration is
 
       ```swift
       import Foundation
@@ -1180,7 +1188,11 @@ public let DECL_NODES: [Node] = [
           .keyword(text: "func"),
           .keyword(text: "inout"),
         ]),
-        documentation: "The kind of declaration being imported. For example, a struct can be imported from a specific module.",
+        documentation: """
+          The kind of declaration being imported. 
+
+          A struct can be imported from a specific module.
+          """,
         isOptional: true
       ),
       Child(
@@ -1241,7 +1253,9 @@ public let DECL_NODES: [Node] = [
     base: .decl,
     nameForDiagnostics: "initializer",
     documentation: """
-      An initializer declaration like the following.
+      An `init` declaration
+
+      An example of an initializer is
 
       ```swift
       init(someParameter: Int) {
@@ -1927,7 +1941,9 @@ public let DECL_NODES: [Node] = [
     base: .decl,
     nameForDiagnostics: "protocol",
     documentation: """
-      A protocol declaration like the following.
+      A `protocol` declaration
+
+      An example of a protocol declaration is
 
       ```swift
       protocol Example {
@@ -2048,61 +2064,63 @@ public let DECL_NODES: [Node] = [
     base: .decl,
     nameForDiagnostics: "struct",
     documentation: """
-          A struct declaration like the following.
+      A `struct` declaration
 
-          ```swift
-          struct SomeStruct {
-            let someMember: String
-            var anotherMember: Int
-
-            func foo() {
-              print(someMember)
-            }
-
-            mutating func bar() {
-              anotherMember = 42
-            }
-          }
-          ```
+      An example of a struct declaration is
 
-          A struct declaration may be declared without any members.
+      ```swift
+      struct SomeStruct {
+        let someMember: String
+        var anotherMember: Int
 
-          ```swift
-          struct EmptyStruct {
+        func foo() {
+          print(someMember)
+        }
 
-          }
-          ```
+        mutating func bar() {
+          anotherMember = 42
+        }
+      }
+      ```
 
-          A struct declaration may include a type inheritance clause listing
-          one or more protocols the struct conforms to.
+      A struct declaration may be declared without any members.
 
-          The example below uses Hashable and Equatable protocols whose members
-          are automatically synthesized by the compiler if the struct contains
-          stored members that are themselves `Hashable` and `Equatable`.
+      ```swift
+      struct EmptyStruct {
 
-          ```swift
-          struct AdvancedStruct: Hashable, Equatable {
-            let someMember: String
-            var anotherMember: Int
-          }
-          ```
+      }
+      ```
 
-          A struct declaration may include a generic parameter clause as well
-          as a generic where clause.
+      A struct declaration may include a type inheritance clause listing
+      one or more protocols the struct conforms to.
 
-          ```swift
-          struct Stack<Element> {
-            var items: [Element] = []
-
-            mutating func push(_ item: Element) {
-              items.append(item)
-            }
-
-            mutating func pop() -> Element {
-              return items.removeLast()
-            }
-         }
-         ```
+      The example below uses Hashable and Equatable protocols whose members
+      are automatically synthesized by the compiler if the struct contains
+      stored members that are themselves `Hashable` and `Equatable`.
+
+      ```swift
+      struct AdvancedStruct: Hashable, Equatable {
+        let someMember: String
+        var anotherMember: Int
+      }
+      ```
+
+      A struct declaration may include a generic parameter clause as well
+      as a generic where clause.
+
+      ```swift
+      struct Stack<Element> {
+        var items: [Element] = []
+
+        mutating func push(_ item: Element) {
+          items.append(item)
+        }
+
+        mutating func pop() -> Element {
+          return items.removeLast()
+        }
+      }
+      ```
       """,
     traits: [
       "DeclGroup",

CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift

@@ -981,7 +981,9 @@ public let EXPR_NODES: [Node] = [
     base: .expr,
     nameForDiagnostics: "'is'",
     documentation: """
-      An `is` expression like the following.
+      Checks if an expression is of a given type.
+
+      An example of an `is` expression is
 
       ```swift
       value is Double

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

@@ -21,9 +21,11 @@ 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.
-      /// DO NOT CONFORM TO THIS PROTOCOL YOURSELF!
+      /// Protocol to which all ``\(node.kind.syntaxType)`` nodes conform. 
+      ///
+      /// Extension point to add common methods to all ``\(node.kind.syntaxType)`` nodes.
+      ///
+      ///  - Warning: Do not conform to this protocol yourself.
       public protocol \(node.kind.protocolType): \(raw: node.base.protocolType) {}
       """
     )
@@ -33,7 +35,8 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
         """
         /// Check whether the non-type erased version of this syntax node conforms to
         /// \(node.kind.protocolType).
-        /// Note that this will incur an existential conversion.
+        ///
+        ///  - Note:  This will incur an existential conversion.
         func isProtocol(_: \(node.kind.protocolType).Protocol) -> Bool {
           return self.asProtocol(\(node.kind.protocolType).self) != nil
         }
@@ -44,7 +47,8 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
         """
         /// Return the non-type erased version of this syntax node if it conforms to
         /// \(node.kind.protocolType). Otherwise return nil.
-        /// Note that this will incur an existential conversion.
+        ///
+        ///  - Note:  This will incur an existential conversion.
         func asProtocol(_: \(node.kind.protocolType).Protocol) -> \(node.kind.protocolType)? {
           return self.asProtocol(SyntaxProtocol.self) as? \(node.kind.protocolType)
         }
@@ -131,9 +135,10 @@ 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
-        /// is undefined.
+        /// Creates a ``\(node.kind.syntaxType)`` node from the given ``SyntaxData``.
+        ///
+        ///  - Warning: This assumes  that the ``SyntaxData`` is of the correct kind.
+        ///    If it is not, the behaviour is undefined.
         internal init(_ data: SyntaxData)
         """
       ) {
@@ -192,7 +197,8 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
         """
         /// Syntax nodes always conform to `\(node.kind.protocolType)`. This API is just
         /// added for consistency.
-        /// Note that this will incur an existential conversion.
+        ///
+        ///  - Note:  This will incur an existential conversion.
         @available(*, deprecated, message: "Expression always evaluates to true")
         public func isProtocol(_: \(raw: node.kind.protocolType).Protocol) -> Bool {
           return true
@@ -203,7 +209,8 @@ let syntaxBaseNodesFile = SourceFileSyntax(leadingTrivia: copyrightHeader) {
       DeclSyntax(
         """
         /// Return the non-type erased version of this syntax node.
-        /// Note that this will incur an existential conversion.
+        ///
+        ///  - Note:  This will incur an existential conversion.
         public func asProtocol(_: \(node.kind.protocolType).Protocol) -> \(node.kind.protocolType) {
           return Syntax(self).asProtocol(\(node.kind.protocolType).self)!
         }

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

@@ -66,9 +66,10 @@ func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {
 
         DeclSyntax(
           """
-          /// 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.
+          /// Creates a ``\(node.kind.syntaxType)`` node from the given ``SyntaxData``. 
+          ///
+          ///  - Warning: This assumes that the `SyntaxData` is of the correct kind.
+          ///    If it is not, the behaviour is undefined.
           internal init(_ data: SyntaxData) {
             precondition(data.raw.kind == .\(raw: node.varOrCaseName))
             self._syntaxNode = Syntax(data)
@@ -199,6 +200,7 @@ func syntaxNode(emitKind: SyntaxNodeKind) -> SourceFileSyntax {
               """
               /// Adds the provided `element` to the node's `\(child.varOrCaseName)`
               /// collection.
+              ///
               /// - param element: The new `\(raw: childElt)` to add to the node's
               ///                  `\(child.varOrCaseName)` collection.
               /// - returns: A copy of the receiver with the provided `\(raw: childElt)`