allow arbitrary platform strings in the @Available directive

QuietMisdreavus · QuietMisdreavus · commit 2503c0d8c515 · 2023-01-26T16:35:29.000-07:00
rdar://104224866
diff --git a/Sources/SwiftDocC/Model/Rendering/Symbol/AvailabilitySortOrder.swift b/Sources/SwiftDocC/Model/Rendering/Symbol/AvailabilitySortOrder.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-2023 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
@@ -23,6 +23,10 @@ enum AvailabilityRenderOrder {
     /// Sort two availability render items based on their platform name.
     static func compare(lhs: AvailabilityRenderItem, rhs: AvailabilityRenderItem) -> Bool {
         guard let lhsName = lhs.name, let rhsName = rhs.name else { return false }
-        return platformsOrder[lhsName, default: Int.max] < platformsOrder[rhsName, default: Int.max]
+        if platformsOrder.keys.contains(lhsName) || platformsOrder.keys.contains(rhsName) {
+            return platformsOrder[lhsName, default: Int.max] < platformsOrder[rhsName, default: Int.max]
+        } else {
+            return lhsName < rhsName
+        }
     }
 }
diff --git a/Sources/SwiftDocC/Semantics/Metadata/Availability.swift b/Sources/SwiftDocC/Semantics/Metadata/Availability.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Copyright (c) 2022-2023 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
@@ -22,7 +22,15 @@ extension Metadata {
     /// @Available(macOS, introduced: "12.0")
     /// ```
     ///
-    /// The available platforms are `macOS`, `iOS`, `watchOS`, and `tvOS`.
+    /// Any text can be given to the first argument, and will be displayed in the page's
+    /// availability data. The platforms `iOS`, `macOS`, `watchOS`, and `tvOS` will be matched
+    /// case-insensitively, but anything else will be printed verbatim.
+    ///
+    /// To provide a platform name with spaces in it, provide it as a quoted string:
+    ///
+    /// ```markdown
+    /// @Available("My Package", introduced: "1.0")
+    /// ```
     ///
     /// This directive is available on both articles and documentation extension files. In extension
     /// files, the information overrides any information from the symbol itself.
@@ -38,19 +46,42 @@ extension Metadata {
     public final class Availability: Semantic, AutomaticDirectiveConvertible {
         static public let directiveName: String = "Available"
 
-        public enum Platform: String, RawRepresentable, CaseIterable, DirectiveArgumentValueConvertible {
+        public enum Platform: RawRepresentable, Hashable, DirectiveArgumentValueConvertible {
             // FIXME: re-add `case any = "*"` when `isBeta` and `isDeprecated` are implemented
             // cf. https://github.com/apple/swift-docc/issues/441
             case macOS, iOS, watchOS, tvOS
 
+            case other(String)
+
+            static var defaultCases: [Platform] = [.macOS, .iOS, .watchOS, .tvOS]
+
             public init?(rawValue: String) {
-                for platform in Self.allCases {
+                for platform in Self.defaultCases {
                     if platform.rawValue.lowercased() == rawValue.lowercased() {
                         self = platform
                         return
                     }
                 }
-                return nil
+                if rawValue == "*" {
+                    // Reserve the `*` platform for when `isBeta` and `isDeprecated` can be implemented
+                    return nil
+                } else {
+                    self = .other(rawValue)
+                }
+            }
+
+            public var rawValue: String {
+                switch self {
+                case .macOS: return "macOS"
+                case .iOS: return "iOS"
+                case .watchOS: return "watchOS"
+                case .tvOS: return "tvOS"
+                case .other(let platform): return platform
+                }
+            }
+
+            static func allowedValues() -> [String]? {
+                nil
             }
         }
 
diff --git a/Sources/SwiftDocC/Semantics/Symbol/PlatformName.swift b/Sources/SwiftDocC/Semantics/Symbol/PlatformName.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-2023 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
@@ -109,6 +109,11 @@ public struct PlatformName: Codable, Hashable, Equatable {
         // Note: This is still an optional initializer to prevent source breakage when
         // `Availability.Platform` re-introduces the `.any` case
         // cf. https://github.com/apple/swift-docc/issues/441
-        self = .init(operatingSystemName: platform.rawValue)
+        if let knowDomain = Self.platformNamesIndex[platform.rawValue.lowercased()] {
+            self = knowDomain
+        } else {
+            let identifier = platform.rawValue.lowercased().replacingOccurrences(of: " ", with: "")
+            self.init(rawValue: identifier, displayName: platform.rawValue)
+        }
     }
 }
diff --git a/Tests/SwiftDocCTests/Rendering/PlatformAvailabilityTests.swift b/Tests/SwiftDocCTests/Rendering/PlatformAvailabilityTests.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-2023 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
@@ -106,4 +106,30 @@ class PlatformAvailabilityTests: XCTestCase {
             item.name == "watchOS" && item.introduced == "7.0"
         }))
     }
+
+    func testArbitraryPlatformAvailability() throws {
+        let (bundle, context) = try testBundleAndContext(named: "AvailabilityBundle")
+        let reference = ResolvedTopicReference(
+            bundleIdentifier: bundle.identifier,
+            path: "/documentation/AvailabilityBundle/ArbitraryPlatforms",
+            sourceLanguage: .swift
+        )
+        let article = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
+        var translator = RenderNodeTranslator(
+            context: context,
+            bundle: bundle,
+            identifier: reference,
+            source: nil
+        )
+        let renderNode = try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
+        let availability = try XCTUnwrap(renderNode.metadata.platformsVariants.defaultValue)
+        XCTAssertEqual(availability.count, 2)
+
+        XCTAssert(availability.contains(where: { item in
+            item.name == "SomePackage" && item.introduced == "1.0"
+        }))
+        XCTAssert(availability.contains(where: { item in
+            item.name == "My Package" && item.introduced == "2.0"
+        }))
+    }
 }
diff --git a/Tests/SwiftDocCTests/Semantics/MetadataAvailabilityTests.swift b/Tests/SwiftDocCTests/Semantics/MetadataAvailabilityTests.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2022 Apple Inc. and the Swift project authors
+ Copyright (c) 2022-2023 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
@@ -49,7 +49,7 @@ class MetadataAvailabilityTests: XCTestCase {
             }
         }
 
-        for platform in Metadata.Availability.Platform.allCases {
+        for platform in Metadata.Availability.Platform.defaultCases {
             let source = """
             @Metadata {
                 @Available(\(platform.rawValue), introduced: \"1.0\")
@@ -74,14 +74,22 @@ class MetadataAvailabilityTests: XCTestCase {
             validArgumentsWithVersion.append("introduced: \"1.0\", \(arg)")
         }
 
-        for platform in Metadata.Availability.Platform.allCases {
+        var checkPlatforms = Metadata.Availability.Platform.defaultCases.map({ $0.rawValue })
+        checkPlatforms.append("Package")
+
+        for platform in checkPlatforms {
             // FIXME: Test validArguments with the `*` platform once that's introduced
             // cf. https://github.com/apple/swift-docc/issues/441
             for args in validArgumentsWithVersion {
-                try assertValidAvailability(source: "@Available(\(platform.rawValue), \(args))")
+                try assertValidAvailability(source: "@Available(\(platform), \(args))")
             }
         }
 
+        // also check a platform with spaces in the name
+        for args in validArgumentsWithVersion {
+            try assertValidAvailability(source: "@Available(\"My Package\", \(args))")
+        }
+
         // also test for giving no platform
         for args in validArguments {
             try assertValidAvailability(source: "@Available(\(args))")
diff --git a/Tests/SwiftDocCTests/Test Bundles/AvailabilityBundle.docc/ArbitraryPlatforms.md b/Tests/SwiftDocCTests/Test Bundles/AvailabilityBundle.docc/ArbitraryPlatforms.md
@@ -0,0 +1,10 @@
+# Arbitrary Platforms
+
+@Metadata {
+    @Available(SomePackage, introduced: "1.0")
+    @Available("My Package", introduced: "2.0")
+}
+
+This page applies to platforms that aren't even operating systems!
+
+<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->
diff --git a/Tests/SwiftDocCTests/Test Bundles/AvailabilityBundle.docc/AvailableArticle.md b/Tests/SwiftDocCTests/Test Bundles/AvailabilityBundle.docc/AvailableArticle.md
@@ -12,5 +12,6 @@ Here's a cool framework that I'm offering to the world.
 ### Cool Articles
 
 - <doc:ComplexAvailable>
+- <doc:ArbitraryPlatforms>
 
-<!-- Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2022-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->
