Merge remote-tracking branch 'upstream/main' into wasm32-wasi-test

CONTRIBUTING.md

@@ -71,6 +71,14 @@ We prefer to not squash commits when merging a PR because, especially for larger
 - During review, the commits can be reviewed individually, making each review chunk smaller
 - In case this PR introduced a bug that is identified later, it is possible to check if it resulted from the refactoring or the actual change, thereby making it easier find the lines that introduce the issue. 
 
+## Opening a PR
+
+To submit a PR you don't need permissions on this repo, instead you can fork the repo and create a PR through your forked version.
+
+For more information and instructions, read the GitHub docs on [forking a repo](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
+
+Once you've pushed your branch, you should see an option on this repository's page to create a PR from a branch in your fork.
+
 ## Review and CI Testing
 
 After you opened your PR, a maintainer will review it and test your changes in CI (*Continuous Integration*) by adding a `@swift-ci Please test` comment on the pull request. Once your PR is approved and CI has passed, the maintainer will merge your pull request.

CodeGeneration/Sources/SyntaxSupport/AttributeNodes.swift

@@ -203,7 +203,8 @@ public let ATTRIBUTE_NODES: [Node] = [
       Child(
         name: "platformVersion",
         deprecatedName: "availabilityVersionRestriction",
-        kind: .node(kind: .platformVersion)
+        kind: .node(kind: .platformVersion),
+        documentation: "The platform/version pair, e.g. `iOS 10.1`"
       ),
       Child(
         name: "trailingComma",
@@ -292,15 +293,19 @@ public let ATTRIBUTE_NODES: [Node] = [
     children: [
       Child(
         name: "witnessMethodLabel",
-        kind: .token(choices: [.keyword(.witness_method)])
+        kind: .token(choices: [.keyword(.witness_method)]),
+        documentation: #"The `witnessMethod` label."#
       ),
       Child(
         name: "colon",
-        kind: .token(choices: [.token(.colon)])
+        kind: .token(choices: [.token(.colon)]),
+        documentation: #"The colon separating the `witnessMethod` label and the original protocol name."#
+
       ),
       Child(
         name: "protocolName",
-        kind: .token(choices: [.token(.identifier)])
+        kind: .token(choices: [.token(.identifier)]),
+        documentation: "The original protocol name."
       ),
     ]
   ),
@@ -454,6 +459,7 @@ public let ATTRIBUTE_NODES: [Node] = [
         name: "kindSpecifier",
         deprecatedName: "diffKind",
         kind: .token(choices: [.keyword(._forward), .keyword(.reverse), .keyword(._linear)]),
+        documentation: "The differentiability kind, if it exists.",
         isOptional: true
       ),
       Child(
@@ -467,6 +473,7 @@ public let ATTRIBUTE_NODES: [Node] = [
         name: "arguments",
         deprecatedName: "diffParams",
         kind: .node(kind: .differentiabilityWithRespectToArgument),
+        documentation: "The differentiability arguments, if any exists.",
         isOptional: true
       ),
       Child(
@@ -675,11 +682,13 @@ public let ATTRIBUTE_NODES: [Node] = [
         name: "name",
         kind: .node(kind: .token),
         nameForDiagnostics: "name",
+        documentation: "The identifier name for a nullary selection, if it exists.",
         isOptional: true
       ),
       Child(
         name: "colon",
         kind: .token(choices: [.token(.colon)]),
+        documentation: "The colon separating the label and the value or a colon representing an unlabeled argument",
         isOptional: true
       ),
     ]

CodeGeneration/Sources/SyntaxSupport/ExprNodes.swift

@@ -214,9 +214,8 @@ public let EXPR_NODES: [Node] = [
   ),
 
   Node(
-    kind: .canImportExpr,
+    kind: ._canImportExpr,
     base: .expr,
-    deprecationMessage: "'canImport' directives are now represented as a `FunctionCallExpr`",
     nameForDiagnostics: "'canImport' expression",
     children: [
       Child(
@@ -233,7 +232,7 @@ public let EXPR_NODES: [Node] = [
       ),
       Child(
         name: "versionInfo",
-        kind: .node(kind: .canImportVersionInfo),
+        kind: .node(kind: ._canImportVersionInfo),
         isOptional: true
       ),
       Child(
@@ -244,9 +243,8 @@ public let EXPR_NODES: [Node] = [
   ),
 
   Node(
-    kind: .canImportVersionInfo,
+    kind: ._canImportVersionInfo,
     base: .expr,
-    deprecationMessage: "'canImport' directives are now represented as a `FunctionCallExpr`",
     nameForDiagnostics: nil,
     children: [
       Child(

CodeGeneration/Sources/SyntaxSupport/KeywordSpec.swift

@@ -43,8 +43,17 @@ public struct KeywordSpec {
   ///
   /// This is typically used to mark APIs as SPI when the keyword is part of an experimental language feature.
   public var apiAttributes: AttributeListSyntax {
-    guard isExperimental else { return "" }
-    return AttributeListSyntax("@_spi(ExperimentalLanguageFeatures)").with(\.trailingTrivia, .newline)
+    let attrList = AttributeListSyntax {
+      if isExperimental {
+        let experimentalSPI: AttributeListSyntax = """
+          #if compiler(>=5.8)
+          @_spi(ExperimentalLanguageFeatures)
+          #endif
+          """
+        experimentalSPI.with(\.trailingTrivia, .newline)
+      }
+    }
+    return attrList.with(\.trailingTrivia, attrList.isEmpty ? [] : .newline)
   }
 
   /// Initializes a new `KeywordSpec` instance.
@@ -108,9 +117,7 @@ public enum Keyword: CaseIterable {
   case _Class
   case _compilerInitialized
   case _const
-  case _consume
   case _consuming
-  case _copy
   case _documentation
   case _dynamicReplacement
   case _effects
@@ -121,7 +128,6 @@ public enum Keyword: CaseIterable {
   case _local
   case _modify
   case _move
-  case _mutate
   case _mutating
   case _NativeClass
   case _NativeRefCountedObject
@@ -186,6 +192,7 @@ public enum Keyword: CaseIterable {
   case `default`
   case `defer`
   case `deinit`
+  case dependsOn
   case deprecated
   case derivative
   case didSet
@@ -275,6 +282,7 @@ public enum Keyword: CaseIterable {
   case reverse
   case right
   case safe
+  case scoped
   case `self`
   case `Self`
   case Sendable
@@ -343,12 +351,8 @@ public enum Keyword: CaseIterable {
       return KeywordSpec("_compilerInitialized")
     case ._const:
       return KeywordSpec("_const")
-    case ._consume:
-      return KeywordSpec("_consume", experimentalFeature: .nonescapableTypes)
     case ._consuming:
       return KeywordSpec("_consuming", experimentalFeature: .referenceBindings)
-    case ._copy:
-      return KeywordSpec("_copy", experimentalFeature: .nonescapableTypes)
     case ._documentation:
       return KeywordSpec("_documentation")
     case ._dynamicReplacement:
@@ -369,8 +373,6 @@ public enum Keyword: CaseIterable {
       return KeywordSpec("_modify")
     case ._move:
       return KeywordSpec("_move")
-    case ._mutate:
-      return KeywordSpec("_mutate", experimentalFeature: .nonescapableTypes)
     case ._mutating:
       return KeywordSpec("_mutating", experimentalFeature: .referenceBindings)
     case ._NativeClass:
@@ -499,6 +501,8 @@ public enum Keyword: CaseIterable {
       return KeywordSpec("defer", isLexerClassified: true)
     case .deinit:
       return KeywordSpec("deinit", isLexerClassified: true)
+    case .dependsOn:
+      return KeywordSpec("dependsOn", experimentalFeature: .nonescapableTypes)
     case .deprecated:
       return KeywordSpec("deprecated")
     case .derivative:
@@ -675,6 +679,8 @@ public enum Keyword: CaseIterable {
       return KeywordSpec("right")
     case .safe:
       return KeywordSpec("safe")
+    case .scoped:
+      return KeywordSpec("scoped", experimentalFeature: .nonescapableTypes)
     case .self:
       return KeywordSpec("self", isLexerClassified: true)
     case .Self:

CodeGeneration/Sources/SyntaxSupport/Node.swift

@@ -40,9 +40,6 @@ public class Node {
   /// The kind of node’s supertype. This kind must have `isBase == true`
   public let base: SyntaxNodeKind
 
-  /// If this syntax node has been deprecated, a message that describes the deprecation.
-  public let deprecationMessage: String?
-
   /// The experimental feature the node is part of, or `nil` if this isn't
   /// for an experimental feature.
   public let experimentalFeature: ExperimentalFeature?
@@ -109,9 +106,6 @@ public class Node {
           """
         experimentalSPI.with(\.trailingTrivia, .newline)
       }
-      if let deprecationMessage {
-        "@available(*, deprecated, message: \(literal: deprecationMessage))"
-      }
       if forRaw {
         "@_spi(RawSyntax)"
       }
@@ -133,7 +127,6 @@ public class Node {
   init(
     kind: SyntaxNodeKind,
     base: SyntaxNodeKind,
-    deprecationMessage: String? = nil,
     experimentalFeature: ExperimentalFeature? = nil,
     nameForDiagnostics: String?,
     documentation: String? = nil,
@@ -146,7 +139,6 @@ public class Node {
 
     self.kind = kind
     self.base = base
-    self.deprecationMessage = deprecationMessage
     self.experimentalFeature = experimentalFeature
     self.nameForDiagnostics = nameForDiagnostics
     self.documentation = SwiftSyntax.Trivia.docCommentTrivia(from: documentation)
@@ -241,7 +233,11 @@ 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.doccLink).``\($0.node.syntaxType)/\(childName)``"
+          if $0.node.isAvailableInDocc {
+            return " - \($0.node.doccLink).``\($0.node.syntaxType)/\(childName)``"
+          } else {
+            return " - \($0.node.doccLink).`\($0.node.syntaxType)/\(childName)`"
+          }
         } else {
           return " - \($0.node.doccLink)"
         }
@@ -265,7 +261,7 @@ public class Node {
 
     let list =
       SYNTAX_NODES
-      .filter { $0.base == self.kind && !$0.isExperimental }
+      .filter { $0.base == self.kind && !$0.isExperimental && !$0.kind.isDeprecated }
       .map { "- \($0.kind.doccLink)" }
       .joined(separator: "\n")
 
@@ -288,7 +284,6 @@ public class Node {
   init(
     kind: SyntaxNodeKind,
     base: SyntaxNodeKind,
-    deprecationMessage: String? = nil,
     experimentalFeature: ExperimentalFeature? = nil,
     nameForDiagnostics: String?,
     documentation: String? = nil,
@@ -298,7 +293,6 @@ public class Node {
     self.kind = kind
     precondition(base == .syntaxCollection)
     self.base = base
-    self.deprecationMessage = deprecationMessage
     self.experimentalFeature = experimentalFeature
     self.nameForDiagnostics = nameForDiagnostics
     self.documentation = SwiftSyntax.Trivia.docCommentTrivia(from: documentation)

CodeGeneration/Sources/SyntaxSupport/String+Extensions.swift

@@ -11,8 +11,18 @@
 //===----------------------------------------------------------------------===//
 
 public extension StringProtocol {
-  var withFirstCharacterLowercased: String { prefix(1).lowercased() + dropFirst() }
-  var withFirstCharacterUppercased: String { prefix(1).uppercased() + dropFirst() }
+  var withFirstCharacterLowercased: String {
+    guard first?.isLetter ?? false else {
+      return String(first!) + dropFirst().withFirstCharacterLowercased
+    }
+    return prefix(1).lowercased() + dropFirst()
+  }
+  var withFirstCharacterUppercased: String {
+    guard first?.isLetter ?? false else {
+      return String(first!) + dropFirst().withFirstCharacterUppercased
+    }
+    return prefix(1).uppercased() + dropFirst()
+  }
   var backtickedIfNeeded: String {
     if Keyword.allCases.map(\.spec).contains(where: {
       $0.name == self && ($0.isLexerClassified || $0.name == "Type" || $0.name == "Protocol")
@@ -23,3 +33,12 @@ public extension StringProtocol {
     }
   }
 }
+
+extension String {
+  public var droppingLeadingUnderscores: String {
+    if first == "_" {
+      return String(self.dropFirst())
+    }
+    return self
+  }
+}

CodeGeneration/Sources/SyntaxSupport/SyntaxNodeKind.swift

@@ -20,6 +20,8 @@ import SwiftSyntaxBuilder
 public enum SyntaxNodeKind: String, CaseIterable {
   // Please keep this list sorted alphabetically
 
+  case _canImportExpr
+  case _canImportVersionInfo
   case accessorBlock
   case accessorDecl
   case accessorDeclList
@@ -47,8 +49,6 @@ public enum SyntaxNodeKind: String, CaseIterable {
   case booleanLiteralExpr
   case borrowExpr
   case breakStmt
-  case canImportExpr
-  case canImportVersionInfo
   case catchClause
   case catchClauseList
   case catchItem
@@ -355,14 +355,25 @@ public enum SyntaxNodeKind: String, CaseIterable {
     }
   }
 
+  /// Whether the node is public API and not underscored/deprecated and can thus be referenced in docc links.
+  public var isAvailableInDocc: Bool {
+    if let node = SYNTAX_NODE_MAP[self], node.isExperimental {
+      return false
+    } else if isDeprecated {
+      return false
+    } else {
+      return true
+    }
+  }
+
   /// 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 {
+    if isAvailableInDocc {
       return "``\(syntaxType)``"
+    } else {
+      return "`\(syntaxType)`"
     }
   }
 
@@ -405,6 +416,8 @@ public enum SyntaxNodeKind: String, CaseIterable {
   /// deprecated.
   public var deprecatedRawValue: String? {
     switch self {
+    case ._canImportExpr: return "canImportExpr"
+    case ._canImportVersionInfo: return "canImportVersionInfo"
     case .accessorDeclList: return "accessorList"
     case .accessorParameters: return "accessorParameter"
     case .associatedTypeDecl: return "associatedtypeDecl"
@@ -475,4 +488,24 @@ public enum SyntaxNodeKind: String, CaseIterable {
     default: return nil
     }
   }
+
+  public var deprecationMessage: String? {
+    switch self {
+    case ._canImportExpr: return "'canImport' directives are now represented as a `FunctionCallExpr`"
+    case ._canImportVersionInfo: return "'canImport' directives are now represented as a `FunctionCallExpr`"
+    default: return nil
+    }
+  }
+
+  public var isDeprecated: Bool {
+    return rawValue.first == "_"
+  }
+
+  var deprecationAttribute: AttributeSyntax? {
+    if let deprecationMessage = deprecationMessage {
+      AttributeSyntax("@available(*, deprecated, message: \(literal: deprecationMessage)")
+    } else {
+      AttributeSyntax(#"@available(*, deprecated, renamed: "\#(syntaxType)")"#)
+    }
+  }
 }