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

* 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

Author: d-ronnqvist

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

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

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)

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) {

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)
     }

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

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)]))
     }