Adding deprecated to @available directive

Adding deprecated argument to the directive @available

Sources/SwiftDocC/Model/Rendering/Symbol/AvailabilityRenderMetadataItem.swift

@@ -141,12 +141,10 @@ public struct AvailabilityRenderItem: Codable, Hashable, Equatable {
  }
 
  init?(_ availability: Metadata.Availability, current: PlatformVersion?) {
- // FIXME: Deprecated/Beta markings need platform versions to display properly in Swift-DocC-Render (rdar://56897597)
- // Fill in the appropriate values here when that's fixed (https://github.com/apple/swift-docc/issues/441)
-
  let platformName = PlatformName(metadataPlatform: availability.platform)
  name = platformName?.displayName
  introduced = availability.introduced
+ deprecated = availability.deprecated
  }
 
  /// Creates a new item with the given platform name and version string.

Sources/SwiftDocC/Semantics/Metadata/Availability.swift

@@ -48,9 +48,7 @@ extension Metadata {
  public static let introducedVersion = "5.8"
 
  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 macOS, iOS, watchOS, tvOS, any
 
  case other(String)
 
@@ -64,8 +62,7 @@ extension Metadata {
  }
  }
  if rawValue == "*" {
- // Reserve the `*` platform for when `isBeta` and `isDeprecated` can be implemented
- return nil
+ self = .any
  } else {
  self = .other(rawValue)
  }
@@ -77,6 +74,7 @@ extension Metadata {
  case .iOS: return "iOS"
  case .watchOS: return "watchOS"
  case .tvOS: return "tvOS"
+ case .any: return "*"
  case .other(let platform): return platform
  }
  }
@@ -92,14 +90,16 @@ extension Metadata {
 
  /// The platform version that this page applies to.
  @DirectiveArgumentWrapped
- public var introduced: String
+ public var introduced: String? = nil
 
- // FIXME: `isBeta` and `isDeprecated` properties/arguments
- // cf. https://github.com/apple/swift-docc/issues/441
+ /// The platform version that this page applies to.
+ @DirectiveArgumentWrapped
+ public var deprecated: String? = nil
 
  static var keyPaths: [String : AnyKeyPath] = [
  "platform" : \Availability._platform,
  "introduced" : \Availability._introduced,
+ "deprecated" : \Availability._deprecated,
  ]
 
  public let originalMarkup: Markdown.BlockDirective

Sources/SwiftDocC/Semantics/Symbol/PlatformName.swift

@@ -106,9 +106,6 @@ public struct PlatformName: Codable, Hashable, Equatable {
  ///
  /// Returns `nil` if the given platform was ``Metadata/Availability/Platform/any``.
  init?(metadataPlatform platform: Metadata.Availability.Platform) {
- // 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
  if let knowDomain = Self.platformNamesIndex[platform.rawValue.lowercased()] {
  self = knowDomain
  } else {

Tests/SwiftDocCTests/Rendering/PlatformAvailabilityTests.swift

@@ -107,6 +107,41 @@ class PlatformAvailabilityTests: XCTestCase {
  }))
  }
 
+ func testMultiplePlatformAvailabilityDeprecatedFromArticle() throws {
+ let (bundle, context) = try testBundleAndContext(named: "AvailabilityBundle")
+ let reference = ResolvedTopicReference(
+ bundleIdentifier: bundle.identifier,
+ path: "/documentation/AvailabilityBundle/ComplexAvailableDeprecated",
+ 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, 5)
+
+ XCTAssert(availability.contains(where: { item in
+ item.name == "iOS" && item.introduced == "11.0" && item.deprecated == "17.0"
+ }))
+ XCTAssert(availability.contains(where: { item in
+ item.name == "macOS" && item.introduced == "11.0" && item.deprecated == "14.0"
+ }))
+ XCTAssert(availability.contains(where: { item in
+ item.name == "watchOS" && item.deprecated == "7.0"
+ }))
+ XCTAssert(availability.contains(where: { item in
+ item.name == "MyPackage" && item.deprecated == "2.0"
+ }))
+ XCTAssert(availability.contains(where: { item in
+ item.name == "*" && item.deprecated == "1.0"
+ }))
+ }
+
  func testArbitraryPlatformAvailability() throws {
  let (bundle, context) = try testBundleAndContext(named: "AvailabilityBundle")
  let reference = ResolvedTopicReference(
@@ -132,7 +167,7 @@ class PlatformAvailabilityTests: XCTestCase {
  item.name == "My Package" && item.introduced == "2.0"
  }))
  }
- 
+
  // Test that the Info.plist default availability does not affect the deprecated/unavailable availabilities provided by the symbol graph.
  func testAvailabilityParserWithInfoPlistDefaultAvailability() throws {
  let (bundle, context) = try testBundleAndContext(named: "AvailabilityOverrideBundle")

Tests/SwiftDocCTests/Semantics/MetadataAvailabilityTests.swift

@@ -63,10 +63,7 @@ class MetadataAvailabilityTests: XCTestCase {
  func testValidDirective() throws {
  // assemble all the combinations of arguments you could give
  let validArguments: [String] = [
- // FIXME: isBeta and isDeprecated are unused (https://github.com/apple/swift-docc/issues/441)
-// "isBeta: true",
-// "isDeprecated: true",
-// "isBeta: true, isDeprecated: true",
+ "deprecated: \"0.1\"",
  ]
  // separate those that give a version so we can test the `*` platform separately
  var validArgumentsWithVersion = ["introduced: \"1.0\""]
@@ -76,10 +73,9 @@ class MetadataAvailabilityTests: XCTestCase {
 
  var checkPlatforms = Metadata.Availability.Platform.defaultCases.map({ $0.rawValue })
  checkPlatforms.append("Package")
+ checkPlatforms.append("*")
 
  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), \(args))")
  }
@@ -92,15 +88,15 @@ class MetadataAvailabilityTests: XCTestCase {
 
  // also test for giving no platform
  for args in validArguments {
- try assertValidAvailability(source: "@Available(\(args))")
+ try assertValidAvailability(source: "@Available(*, \(args))")
  }
 
- // basic validity test for giving several directives
- // FIXME: re-add isBeta after that is implemented (https://github.com/apple/swift-docc/issues/441)
  let source = """
  @Metadata {
  @Available(macOS, introduced: "11.0")
  @Available(iOS, introduced: "15.0")
+ @Available(watchOS, introduced: "7.0", deprecated: "9.0")
+ @Available(*, deprecated: "1.0")
  }
  """
  try assertValidMetadata(source: source)

Tests/SwiftDocCTests/Test Bundles/AvailabilityBundle.docc/AvailableArticle.md

@@ -12,6 +12,7 @@ Here's a cool framework that I'm offering to the world.
 ### Cool Articles
 
 - <doc:ComplexAvailable>
+- <doc:ComplexAvailableDeprecated>
 - <doc:ArbitraryPlatforms>
 
 <!-- Copyright (c) 2022-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Tests/SwiftDocCTests/Test Bundles/AvailabilityBundle.docc/ComplexAvailableDeprecated.md

@@ -0,0 +1,13 @@
+# Complex Available Deprecated Article
+
+@Metadata {
+ @Available(macOS, introduced: "11.0", deprecated: "14.0")
+ @Available(iOS, introduced: "11.0", deprecated: "17.0")
+ @Available(watchOS, deprecated: "7.0")
+ @Available(MyPackage, deprecated: "2.0")
+ @Available(*, deprecated: "1.0")
+}
+
+This applies to three different platforms!
+
+<!-- Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->