Adding deprecated to @Available directive

[mustiikhalil]

Summary

Adding deprecated argument to the directive @Available, this is done by adding a field deprecated to the Metadata.Availability and also addressing all the comments that are related to the issue within the codebase.

This PR also include the .any platform for @Available, which can be used as follows:

@Available(*, introduced: "1.0")
@Available(*, introduced: "1.0", deprecated: "10.0")

Closes #441

Testing

Adding the following metadata into SwiftDocC/Directives.md

@Metadata {
    @Available("Swift DocC", introduced: "1.0", deprecated: "2.0")
}

Using swift-docc-render-artifact

Steps:

1. Add the above metadata to Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Directives.md.

2. ./bin/preview-docs SwiftDocC

3. Ensure that in the documentation list the "Directives" shows a deprecated tag

4. Ensure that the "Directives" page is printed with an availability callout for "Swift DocC" which contains a introduced and deprecated versions

Checklist

• Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary
  (Not sure how to update the docs properly)

[sofiaromorales]

@mustiikhalil Could you please add the Steps to reproduce section to the PR template, including the expected behaviour and a test DocC catalog that uses the new deprecated keyword?

[mustiikhalil]

Could you please add the Steps to reproduce section to the PR template, including the expected behaviour

Yes, i can do that later today.

@sofiaromorales regarding the test bundle i thought it would be enough to include it within the current test bundle which can be found in AvailabilityBundle.docc since its just an arguement to the same directive

[mustiikhalil]

@sofiaromorales sorry for the ping, but would love to know what's next to get this PR moving forward

[sofiaromorales]

Are we sure this is how we want to display any?

@mustiikhalil can you attach an screenshot on how does this looks on the rendered documentation?

[mustiikhalil]

It would look something like the screenshot below:

[d-ronnqvist]

I don't know how this is meant to work but I don't think we'd want this to display * here.

It's a bit odd that the wildcard specifies a version at all because that version may not align across the various platforms.

[mustiikhalil]

If that's the case what would be the correct representation to say that it is deprecated on all platforms?

Where as a specific case of deprecation might look like this for example:

[d-ronnqvist]

I would probably say that the correct way would be to list the deprecation on platform where the symbol is known to be available.

However, like I said above, it's a bit odd that we allow specifying a deprecation version for all platforms since the different platforms don't need to align their versions and in practice don't do so.

[mustiikhalil]

Ah that makes sense, I'll update the PR as soon as possible with removing the *. And thus aligning with screenshot sent below/ in the previous comment:

[mustiikhalil]

Should be fixed now

[sofiaromorales]

@sofiaromorales sorry for the ping, but would love to know what's next to get this PR moving forward

Sorry for the wait. I left some initial feedback and in the upcoming days I'll do another round of reviews.

[sofiaromorales]

Updated documentation if necessary
(Not sure how to update the docs properly)

@mustiikhalil please update the Availability DocC comment to properly document this change.

[mustiikhalil]

I'll look at it during the weekend.