Merge pull request #2016 from ahoppen/ahoppen/node-documentation

Add some documentation for nodes that have unintuitive behavior on first sight

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/AttributeNodes.swift

@@ -16,6 +16,20 @@ public let ATTRIBUTE_NODES: [Node] = [
     kind: .attributeList,
     base: .syntaxCollection,
     nameForDiagnostics: "attributes",
+    documentation: """
+      A list of attributes that can be attached to a declaration.
+
+      An element in this collection can either be an attribute itself or an ``IfConfigDeclSyntax``
+      that contains attributes. This is because attributes can be added conditional on compilcation
+      conditions, for example.
+
+      ```swift
+      #if !DISABLE_DEPRECATIONS
+      @available(*, deprecated)
+      #endif
+      func myFunction() {}
+      ```
+      """,
     elementChoices: [.attribute, .ifConfigDecl]
   ),
 

CodeGeneration/Sources/SyntaxSupport/AvailabilityNodes.swift

@@ -125,6 +125,13 @@ public let AVAILABILITY_NODES: [Node] = [
         name: "Version",
         kind: .node(kind: .versionTuple),
         nameForDiagnostics: "version",
+        documentation: """
+          The version of this platform.
+
+          This parameter is optional because a custom platform alias can be specified using the `-define-availability` 
+          argument to the Swift compiler. For example, when passing `-define-availability "_iOS8Aligned:macOS 10.10, iOS 8.0"`
+          to the Swift compiler, then `@available(_iOS8Aligned, *)` is interpreted as `@available(macOS 10.10, iOS 8.0, *)`.
+          """,
         isOptional: true
       ),
     ]

CodeGeneration/Sources/generate-swiftsyntax/templates/swiftsyntaxbuilder/BuildableCollectionNodesFile.swift

@@ -22,14 +22,8 @@ let buildableCollectionNodesFile = SourceFileSyntax(leadingTrivia: copyrightHead
   for node in SYNTAX_NODES.compactMap(\.collectionNode) {
     let elementType = node.collectionElementType
 
-    let docComment =
-      node.documentation.isEmpty
-      ? [.docLineComment("/// `\(node.kind.syntaxType)` represents a collection of `\(elementType.syntaxBaseName)`")]
-      : node.documentation
-    // Generate collection node struct
     try! ExtensionDeclSyntax(
       """
-      \(docComment)
       extension \(raw: node.type.syntaxBaseName): ExpressibleByArrayLiteral
       """
     ) {

Sources/SwiftSyntax/Documentation.docc/Glossary.md

@@ -13,6 +13,8 @@ To avoid ongoing repetition of common long terms, SwiftSyntax uses a couple of a
 
 **Expr** Abbreviation for *Expression*
 
+**IfConfig** Abbrevation for *If Configuration*. Refers to `#if` clauses in the source code.
+
 **Layout Node** A layout node can have an arbitrary number of children and provides structure to the syntax tree. All ``Syntax`` nodes that aren’t ``TokenSyntax`` are layout nodes. For example a ``StructDeclSyntax`` consists of, among others, of the `struct` keyword, the name and the `memberBlock`. The latter is again a layout node that contains multiple children. Layout nodes never represent any source code in the syntax tree by themselves. All source code within the syntax tree is represented by *tokens*.
 
 **Node** A *layout node* or *token*

Sources/SwiftSyntax/generated/SyntaxCollections.swift

@@ -56,6 +56,19 @@ public struct ArrayElementListSyntax: SyntaxCollection, SyntaxHashable {
   public static let syntaxKind = SyntaxKind.arrayElementList
 }
 
+/// A list of attributes that can be attached to a declaration.
+/// 
+/// An element in this collection can either be an attribute itself or an ``IfConfigDeclSyntax``
+/// that contains attributes. This is because attributes can be added conditional on compilcation
+/// conditions, for example.
+/// 
+/// ```swift
+/// #if !DISABLE_DEPRECATIONS
+/// @available(*, deprecated)
+/// #endif
+/// func myFunction() {}
+/// ```
+///
 /// ### Children
 /// 
 /// (``AttributeSyntax`` | ``IfConfigDeclSyntax``) `*`

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodes.swift

@@ -14481,6 +14481,7 @@ public struct PlatformVersionSyntax: SyntaxProtocol, SyntaxHashable {
   /// - Parameters:
   ///   - leadingTrivia: Trivia to be prepended to the leading trivia of the node’s first token. If the node is empty, there is no token to attach the trivia to and the parameter is ignored.
   ///   - platform: The name of the OS on which the availability should be restricted or 'swift' if the availability should be restricted based on a Swift version.
+  ///   - version: The version of this platform.
   ///   - trailingTrivia: Trivia to be appended to the trailing trivia of the node’s last token. If the node is empty, there is no token to attach the trivia to and the parameter is ignored.
   public init(
       leadingTrivia: Trivia? = nil,
@@ -14549,6 +14550,11 @@ public struct PlatformVersionSyntax: SyntaxProtocol, SyntaxHashable {
     }
   }
 
+  /// The version of this platform.
+  /// 
+  /// This parameter is optional because a custom platform alias can be specified using the `-define-availability` 
+  /// argument to the Swift compiler. For example, when passing `-define-availability "_iOS8Aligned:macOS 10.10, iOS 8.0"`
+  /// to the Swift compiler, then `@available(_iOS8Aligned, *)` is interpreted as `@available(macOS 10.10, iOS 8.0, *)`.
   public var version: VersionTupleSyntax? {
     get {
       return data.child(at: 3, parent: Syntax(self)).map(VersionTupleSyntax.init)