Adding deprecated to @available directive (#851)

Adding deprecated argument to the directive @available and updates documentation to include the new argument

Author: mustiikhalil

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

@@ -147,6 +147,7 @@ public struct AvailabilityRenderItem: Codable, Hashable, Equatable {
         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

@@ -16,10 +16,12 @@ extension Metadata {
     ///
     /// `@Available` is analogous to the `@available` attribute in Swift: It allows you to specify a
     /// platform version that the page relates to. To specify a platform and version, list the platform
-    /// name and use the `introduced` argument:
+    /// name and use the `introduced` argument. In addition, you can also specify a deprecated
+    /// version, using the `deprecated` argument:
     ///
     /// ```markdown
     /// @Available(macOS, introduced: "12.0")
+    /// @Available(macOS, introduced: "12.0", deprecated: "14.0")
     /// ```
     ///
     /// Any text can be given to the first argument, and will be displayed in the page's
@@ -48,8 +50,6 @@ 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 other(String)
@@ -90,16 +90,18 @@ extension Metadata {
         @DirectiveArgumentWrapped(name: .unnamed)
         public var platform: Platform
 
-        /// The platform version that this page applies to.
+        /// The platform version that this page was introduced in.
         @DirectiveArgumentWrapped
         public var introduced: String
 
-        // FIXME: `isBeta` and `isDeprecated` properties/arguments
-        // cf. https://github.com/apple/swift-docc/issues/441
+        /// The platform version that this page was deprecated in.
+        @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

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: \"1.0\"",
         ]
         // separate those that give a version so we can test the `*` platform separately
         var validArgumentsWithVersion = ["introduced: \"1.0\""]
@@ -90,17 +87,12 @@ class MetadataAvailabilityTests: XCTestCase {
             try assertValidAvailability(source: "@Available(\"My Package\", \(args))")
         }
 
-        // also test for giving no platform
-        for args in validArguments {
-            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("My Package", introduced: "0.1", deprecated: "1.0")
         }
         """
         try assertValidMetadata(source: source)