Address warnings about retroactively conforming types from other modules to protocols (#957)

d-ronnqvist · web-flow · commit 4d42f13ab503 · 2024-06-18T15:15:42.000+02:00
* Add @retroactive annotations with explanatory comments to address warnings * Fix false-positive warning about inner function not throwing * Use backwards compatible syntax for retroactive protocol conformance * Update comments about retroactive protocol conformances
diff --git a/Sources/SwiftDocC/DocumentationService/Convert/Symbol Link Resolution/DocCSymbolRepresentable.swift b/Sources/SwiftDocC/DocumentationService/Convert/Symbol Link Resolution/DocCSymbolRepresentable.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -164,6 +164,15 @@ public extension Collection where Element: DocCSymbolRepresentable {
     }
 }
 
+#if compiler(>=6)
+// DocCSymbolRepresentable inherits from Equatable. If SymbolKit added Equatable conformance in the future, this could behave differently.
+// It's reasonable to expect that symbols with the same unique ID would be equal but it's possible that SymbolKit's implementation would consider more symbol properties.
+//
+// In the long term we should try to phase out DocCSymbolRepresentable since it doesn't reflect how DocC resolves links or disambiguated symbols in links.
+extension SymbolGraph.Symbol: @retroactive Equatable {}
+extension UnifiedSymbolGraph.Symbol: @retroactive Equatable {}
+#endif
+
 extension SymbolGraph.Symbol: DocCSymbolRepresentable {
     public var preciseIdentifier: String? {
         self.identifier.precise
diff --git a/Sources/SwiftDocC/Infrastructure/Symbol Graph/AccessControl+Comparable.swift b/Sources/SwiftDocC/Infrastructure/Symbol Graph/AccessControl+Comparable.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -10,7 +10,12 @@
 
 import SymbolKit
 
-extension SymbolGraph.Symbol.AccessControl: Comparable {
+// Use fully-qualified types to silence a warning about retroactively conforming a type from another module to a new protocol (SE-0364).
+// The `@retroactive` attribute is new in the Swift 6 compiler. The backwards compatible syntax for a retroactive conformance is fully-qualified types.
+//
+// SymbolKit doesn't define any access control values ("open", "public", "internal", "filePrivate", and "private", are defined in SwiftDocC).
+// Because AccessControl only has a string raw value, it's unlikely that SymbolKit would add a Comparable conformance and default implementation.
+extension SymbolKit.SymbolGraph.Symbol.AccessControl: Swift.Comparable {
     private var level: Int? {
         switch self {
         case .private : return 1
diff --git a/Sources/SwiftDocC/Utility/SemanticVersion+Comparable.swift b/Sources/SwiftDocC/Utility/SemanticVersion+Comparable.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -11,7 +11,14 @@
 import Foundation
 import SymbolKit
 
-extension SymbolGraph.SemanticVersion: Comparable {
+// Use fully-qualified types to silence a warning about retroactively conforming a type from another module to a new protocol (SE-0364).
+// The `@retroactive` attribute is new in the Swift 6 compiler. The backwards compatible syntax for a retroactive conformance is fully-qualified types.
+//
+// If SymbolKit adds Comparable conformance it's reasonable to expect that its behavior would be compatible.
+//
+// As long as a hypothetical future SymbolKit implementation considers "major", "minor", and "patch" before comparing the "prerelease" and "buildMetadata"
+// components, the behavior will remain compatible with what SwiftDocC expects.
+extension SymbolKit.SymbolGraph.SemanticVersion: Swift.Comparable {
     /// Compares two semantic versions.
     public static func < (lhs: SymbolGraph.SemanticVersion, rhs: SymbolGraph.SemanticVersion) -> Bool {
         return (lhs.major, lhs.minor, lhs.patch) < (rhs.major, rhs.minor, rhs.patch)
diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/Options/DocumentationCoverageOptionsArgument.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/Options/DocumentationCoverageOptionsArgument.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -85,9 +85,15 @@ public struct DocumentationCoverageOptionsArgument: ParsableArguments {
     }
 }
 
-// SwiftDocCUtilities imports SwiftDocC. SwiftDocC does not link against ArgumentParser (because it isn't about CLI). We conform here because this is the first place that we can. We implement in DocC.
-extension DocumentationCoverageLevel: ExpressibleByArgument {}
-extension DocumentationCoverageOptions.KindFilterOptions.BitFlagRepresentation: ExpressibleByArgument {}
+// Use fully-qualified types to silence a warning about retroactively conforming a type from another module to a new protocol (SE-0364).
+// The `@retroactive` attribute is new in the Swift 6 compiler. The backwards compatible syntax for a retroactive conformance is fully-qualified types.
+//
+// It is safe to add a retroactively conformance here because the other module (SwiftDocC) is in the same package.
+//
+// These conforming types are defined in SwiftDocC and extended in SwiftDocCUtilities, because SwiftDocC doesn't link against ArgumentParse (since it isn't about CLI).
+// We conform here because this is the first place that we can add the conformance. The implementation is in SwiftDocC.
+extension SwiftDocC.DocumentationCoverageLevel: ArgumentParser.ExpressibleByArgument {}
+extension SwiftDocC.DocumentationCoverageOptions.KindFilterOptions.BitFlagRepresentation: ArgumentParser.ExpressibleByArgument {}
 
 extension DocumentationCoverageOptions {
     public init(from arguments: DocumentationCoverageOptionsArgument) {
diff --git a/Sources/generate-symbol-graph/main.swift b/Sources/generate-symbol-graph/main.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -57,7 +57,11 @@ func directiveUSR(_ directiveName: String) -> String {
     "__docc_universal_symbol_reference_$\(directiveName)"
 }
 
-extension SymbolGraph.Symbol.DeclarationFragments.Fragment: ExpressibleByStringInterpolation {
+// Use fully-qualified types to silence a warning about retroactively conforming a type from another module to a new protocol (SE-0364).
+// The `@retroactive` attribute is new in the Swift 6 compiler. The backwards compatible syntax for a retroactive conformance is fully-qualified types.
+//
+// This conformance it only relevant to the `generate-symbol-graph` script.
+extension SymbolKit.SymbolGraph.Symbol.DeclarationFragments.Fragment: Swift.ExpressibleByStringInterpolation {
     public init(stringLiteral value: String) {
         self.init(kind: .text, spelling: value, preciseIdentifier: nil)
     }
@@ -71,7 +75,11 @@ extension SymbolGraph.Symbol.DeclarationFragments.Fragment: ExpressibleByStringI
     }
 }
 
-extension SymbolGraph.LineList.Line: ExpressibleByStringInterpolation {
+// Use fully-qualified types to silence a warning about retroactively conforming a type from another module to a new protocol (SE-0364).
+// The `@retroactive` attribute is new in the Swift 6 compiler. The backwards compatible syntax for a retroactive conformance is fully-qualified types.
+//
+// This conformance it only relevant to the `generate-symbol-graph` script. 
+extension SymbolKit.SymbolGraph.LineList.Line: Swift.ExpressibleByStringInterpolation {
     public init(stringLiteral value: String) {
         self.init(text: value, range: nil)
     }
diff --git a/Tests/SwiftDocCTests/Model/RenderNodeSerializationTests.swift b/Tests/SwiftDocCTests/Model/RenderNodeSerializationTests.swift
@@ -225,7 +225,7 @@ class RenderNodeSerializationTests: XCTestCase {
             let kind: RenderNode.Kind
         }
         func decodeKind(jsonString: String) throws -> RenderNode.Kind {
-            return try JSONDecoder().decode(Wrapper.self, from: "{ \"kind\" : \(jsonString) }".data(using: .utf8)!).kind
+            return try JSONDecoder().decode(RenderNode.Kind.self, from: Data(jsonString.utf8))
         }
         
         // Both values can be decoded
diff --git a/Tests/SwiftDocCTests/Semantics/Reference/RowTests.swift b/Tests/SwiftDocCTests/Semantics/Reference/RowTests.swift
@@ -283,7 +283,11 @@ class RowTests: XCTestCase {
 
 }
 
-extension RenderBlockContent: ExpressibleByStringLiteral {
+// Use fully-qualified types to silence a warning about retroactively conforming a type from another module to a new protocol (SE-0364).
+// The `@retroactive` attribute is new in the Swift 6 compiler. The backwards compatible syntax for a retroactive conformance is fully-qualified types.
+//
+// It is safe to add a retroactively conformance here because the other module (SwiftDocC) is in the same package.
+extension SwiftDocC.RenderBlockContent: Swift.ExpressibleByStringLiteral {
     public init(stringLiteral value: String) {
         self = RenderBlockContent.paragraph(Paragraph(inlineContent: [.text(value)]))
     }

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`/*`
`2`	`2`	`This source file is part of the Swift.org open source project`
`3`	`3`
`4`		`- Copyright (c) 2021 Apple Inc. and the Swift project authors`
	`4`	`+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors`
`5`	`5`	`Licensed under Apache License v2.0 with Runtime Library Exception`
`6`	`6`
`7`	`7`	`See https://swift.org/LICENSE.txt for license information`
`@@ -57,7 +57,11 @@ func directiveUSR(_ directiveName: String) -> String {`
`57`	`57`	`"__docc_universal_symbol_reference_$\(directiveName)"`
`58`	`58`	`}`
`59`	`59`
`60`		`-extension SymbolGraph.Symbol.DeclarationFragments.Fragment: ExpressibleByStringInterpolation {`
	`60`	`+// Use fully-qualified types to silence a warning about retroactively conforming a type from another module to a new protocol (SE-0364).`
	`61`	+// The `@retroactive` attribute is new in the Swift 6 compiler. The backwards compatible syntax for a retroactive conformance is fully-qualified types.
	`62`	`+//`
	`63`	+// This conformance it only relevant to the `generate-symbol-graph` script.
	`64`	`+extension SymbolKit.SymbolGraph.Symbol.DeclarationFragments.Fragment: Swift.ExpressibleByStringInterpolation {`
`61`	`65`	`public init(stringLiteral value: String) {`
`62`	`66`	`self.init(kind: .text, spelling: value, preciseIdentifier: nil)`
`63`	`67`	`}`
`@@ -71,7 +75,11 @@ extension SymbolGraph.Symbol.DeclarationFragments.Fragment: ExpressibleByStringI`
`71`	`75`	`}`
`72`	`76`	`}`
`73`	`77`
`74`		`-extension SymbolGraph.LineList.Line: ExpressibleByStringInterpolation {`
	`78`	`+// Use fully-qualified types to silence a warning about retroactively conforming a type from another module to a new protocol (SE-0364).`
	`79`	+// The `@retroactive` attribute is new in the Swift 6 compiler. The backwards compatible syntax for a retroactive conformance is fully-qualified types.
	`80`	`+//`
	`81`	+// This conformance it only relevant to the `generate-symbol-graph` script.
	`82`	`+extension SymbolKit.SymbolGraph.LineList.Line: Swift.ExpressibleByStringInterpolation {`
`75`	`83`	`public init(stringLiteral value: String) {`
`76`	`84`	`self.init(text: value, range: nil)`
`77`	`85`	`}`
Original file line number	Diff line number	Diff line change
`@@ -225,7 +225,7 @@ class RenderNodeSerializationTests: XCTestCase {`
`225`	`225`	`let kind: RenderNode.Kind`
`226`	`226`	`}`
`227`	`227`	`func decodeKind(jsonString: String) throws -> RenderNode.Kind {`
`228`		`- return try JSONDecoder().decode(Wrapper.self, from: "{ \"kind\" : \(jsonString) }".data(using: .utf8)!).kind`
	`228`	`+ return try JSONDecoder().decode(RenderNode.Kind.self, from: Data(jsonString.utf8))`
`229`	`229`	`}`
`230`	`230`
`231`	`231`	`// Both values can be decoded`
Original file line number	Diff line number	Diff line change
`@@ -283,7 +283,11 @@ class RowTests: XCTestCase {`
`283`	`283`
`284`	`284`	`}`
`285`	`285`
`286`		`-extension RenderBlockContent: ExpressibleByStringLiteral {`
	`286`	`+// Use fully-qualified types to silence a warning about retroactively conforming a type from another module to a new protocol (SE-0364).`
	`287`	+// The `@retroactive` attribute is new in the Swift 6 compiler. The backwards compatible syntax for a retroactive conformance is fully-qualified types.
	`288`	`+//`
	`289`	`+// It is safe to add a retroactively conformance here because the other module (SwiftDocC) is in the same package.`
	`290`	`+extension SwiftDocC.RenderBlockContent: Swift.ExpressibleByStringLiteral {`
`287`	`291`	`public init(stringLiteral value: String) {`
`288`	`292`	`self = RenderBlockContent.paragraph(Paragraph(inlineContent: [.text(value)]))`
`289`	`293`	`}`