Adding deprecated to @Available directive #851

mustiikhalil · 2024-03-05T18:44:00Z

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:

Add the above metadata to Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/Directives.md.
./bin/preview-docs SwiftDocC
Ensure that in the documentation list the "Directives" shows a deprecated tag

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 · 2024-03-08T11:56:12Z

@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 · 2024-03-08T12:16:00Z

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 · 2024-03-18T23:28:28Z

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

Sources/SwiftDocC/Semantics/Metadata/Availability.swift

sofiaromorales · 2024-03-19T18:52:46Z

Sources/SwiftDocC/Semantics/Metadata/Availability.swift

@@ -77,6 +74,7 @@ extension Metadata {
                case .iOS: return "iOS"
                case .watchOS: return "watchOS"
                case .tvOS: return "tvOS"
+                case .any: return "*"


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?

It would look something like the screenshot below:

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.

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:

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.

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:

Should be fixed now

Tests/SwiftDocCTests/Rendering/PlatformAvailabilityTests.swift

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

sofiaromorales · 2024-03-19T19:11:05Z

@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 · 2024-03-19T19:14:17Z

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 · 2024-03-22T02:04:04Z

I'll look at it during the weekend.

mustiikhalil · 2024-05-25T11:21:19Z

@d-ronnqvist what can I do to make this PR move forward?

d-ronnqvist · 2024-06-12T17:19:56Z

@d-ronnqvist what can I do to make this PR move forward?

Sorry for the very, very long delay.

In the Documentation Workgroup meeting on June 3, one of the topics that we discussed was how "*" availability should be displayed on the page to better reflect that a large number of packages work on Linux and Windows and anywhere else where Swift is supported. We didn't come to any specific conclusions about how it should be displayed but decided that it should be pitched on the Swift Forums where the broader community can be part of the conversation.

The goal is to discuss and hopefully implement those changes in the 6.0 timeframe but it may still take a few weeks before everyone agrees on how it should be displayed and how it should behave.

If you don't want to wait for that discussion to happen, it may be good to separate the any platform changes and limit this PR to the new support for the "deprecated" argument to the @Available directive.

mustiikhalil · 2024-06-12T21:39:02Z

Sorry for the very, very long delay.

No worries

If you don't want to wait for that discussion to happen, it may be good to separate the any platform changes and limit this PR to the new support for the "deprecated" argument to the @available directive.

If that's the case let's keep this PR tiny, as in adding support for deprecated. And create an issue for the "any" which I would be happy to work on when the Specs for it are ready.

I will simply revert the changes when parsing the "*" operator in the platforms enum. And revert a couple of the tests, comments that removed the mention of .any/*

What do you think?

d-ronnqvist · 2024-06-14T17:12:56Z

Sorry for the very, very long delay.

No worries

If you don't want to wait for that discussion to happen, it may be good to separate the any platform changes and limit this PR to the new support for the "deprecated" argument to the @available directive.

If that's the case let's keep this PR tiny, as in adding support for deprecated. And create an issue for the "any" which I would be happy to work on when the Specs for it are ready.

I will simply revert the changes when parsing the "*" operator in the platforms enum. And revert a couple of the tests, comments that removed the mention of .any/*

What do you think?

That sounds like a good plan

@available

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

mustiikhalil · 2024-06-25T22:02:24Z

Tests/SwiftDocCTests/Semantics/MetadataAvailabilityTests.swift


-        // also test for giving no platform
-        for args in validArguments {
-            try assertValidAvailability(source: "@Available(\(args))")
-        }


Removed this code since it was never called because validArguments was always empty before. However now we have deprecated as a value within the array

Nice. It looks like this loop wasn't really testing what the comment says.

It also seems unnecessary to have 3 loops in this test. The entire "My Package" loop could be removed if there was an checkPlatforms.append("\"My Package\"") before the first loop.

mustiikhalil · 2024-06-25T22:03:58Z

That sounds like a good plan

@d-ronnqvist Super sorry for the late update, but this should be good now. Only added a simple parameter and reverted all the instances where I removed the wild card "*" comments.

d-ronnqvist · 2024-06-27T14:58:23Z

Tests/SwiftDocCTests/Semantics/MetadataAvailabilityTests.swift


-        // also test for giving no platform
-        for args in validArguments {
-            try assertValidAvailability(source: "@Available(\(args))")
-        }


Nice. It looks like this loop wasn't really testing what the comment says.

It also seems unnecessary to have 3 loops in this test. The entire "My Package" loop could be removed if there was an checkPlatforms.append("\"My Package\"") before the first loop.

d-ronnqvist · 2024-06-27T14:59:49Z

@swift-ci please test

This PR no longer adds support for "any" / "*" availability

d-ronnqvist · 2024-06-27T16:17:06Z

@swift-ci please test

@available

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

Adding deprecated argument to the directive `@available`. rdar://130516145

mustiikhalil force-pushed the issue-441-add-deprecated-argument branch from a80b723 to c2d167f Compare March 5, 2024 18:44

mustiikhalil mentioned this pull request Mar 5, 2024

Add deprecated version argument to the @Available directive #441

Closed

mustiikhalil force-pushed the issue-441-add-deprecated-argument branch 2 times, most recently from d688517 to 8fff1c0 Compare March 7, 2024 17:28

mustiikhalil marked this pull request as ready for review March 7, 2024 17:28

mustiikhalil force-pushed the issue-441-add-deprecated-argument branch 2 times, most recently from 552c4bf to 86da846 Compare March 12, 2024 17:32

mustiikhalil force-pushed the issue-441-add-deprecated-argument branch 2 times, most recently from 02e741d to b5cc26e Compare March 18, 2024 23:27

sofiaromorales previously requested changes Mar 19, 2024

View reviewed changes

mustiikhalil force-pushed the issue-441-add-deprecated-argument branch 2 times, most recently from dda5175 to 57141c6 Compare March 22, 2024 16:47

sofiaromorales requested a review from d-ronnqvist March 28, 2024 13:35

mustiikhalil force-pushed the issue-441-add-deprecated-argument branch from c9d5867 to 4e8cb9d Compare April 4, 2024 15:16

mustiikhalil requested a review from sofiaromorales May 15, 2024 05:34

mustiikhalil force-pushed the issue-441-add-deprecated-argument branch from 4e8cb9d to f096f6a Compare May 15, 2024 05:35

mustiikhalil force-pushed the issue-441-add-deprecated-argument branch from f096f6a to 0b394a2 Compare May 25, 2024 11:21

Adding deprecated to @available directive

2fcf1fd

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

mustiikhalil force-pushed the issue-441-add-deprecated-argument branch from 0b394a2 to 2fcf1fd Compare June 25, 2024 22:01

mustiikhalil commented Jun 25, 2024

View reviewed changes

d-ronnqvist approved these changes Jun 27, 2024

View reviewed changes

Merge branch 'main' into issue-441-add-deprecated-argument

f5f09dd

d-ronnqvist merged commit d6e1217 into swiftlang:main Jun 27, 2024
2 checks passed

anferbui mentioned this pull request Jun 28, 2024

Add * support for @Available directive #969

Open

sofiaromorales pushed a commit to sofiaromorales/swift-docc that referenced this pull request Jul 3, 2024

Adding deprecated to @available directive (swiftlang#851)

1d5cd2b

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

sofiaromorales mentioned this pull request Jul 3, 2024

[6.0] Adding deprecated to @Available directive (#851) #971

Merged

sofiaromorales added a commit that referenced this pull request Jul 4, 2024

Adding deprecated to @available directive (#851) (#971)

422e9a5

Adding deprecated argument to the directive `@available`. rdar://130516145

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding deprecated to @Available directive #851

Adding deprecated to @Available directive #851

mustiikhalil commented Mar 5, 2024 •

edited

Loading

sofiaromorales commented Mar 8, 2024 •

edited

Loading

mustiikhalil commented Mar 8, 2024 •

edited

Loading

mustiikhalil commented Mar 18, 2024

sofiaromorales Mar 19, 2024

mustiikhalil Mar 22, 2024

d-ronnqvist Mar 28, 2024

mustiikhalil Mar 28, 2024

d-ronnqvist Apr 2, 2024

mustiikhalil Apr 2, 2024

mustiikhalil Apr 4, 2024

sofiaromorales commented Mar 19, 2024

sofiaromorales commented Mar 19, 2024

mustiikhalil commented Mar 22, 2024

mustiikhalil commented May 25, 2024

d-ronnqvist commented Jun 12, 2024

mustiikhalil commented Jun 12, 2024

d-ronnqvist commented Jun 14, 2024

mustiikhalil Jun 25, 2024

d-ronnqvist Jun 27, 2024

mustiikhalil commented Jun 25, 2024

d-ronnqvist Jun 27, 2024

d-ronnqvist commented Jun 27, 2024

d-ronnqvist commented Jun 27, 2024

Adding deprecated to @Available directive #851

Adding deprecated to @Available directive #851

Conversation

mustiikhalil commented Mar 5, 2024 • edited Loading

Summary

Checklist

sofiaromorales commented Mar 8, 2024 • edited Loading

mustiikhalil commented Mar 8, 2024 • edited Loading

mustiikhalil commented Mar 18, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sofiaromorales commented Mar 19, 2024

sofiaromorales commented Mar 19, 2024

mustiikhalil commented Mar 22, 2024

mustiikhalil commented May 25, 2024

d-ronnqvist commented Jun 12, 2024

mustiikhalil commented Jun 12, 2024

d-ronnqvist commented Jun 14, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mustiikhalil commented Jun 25, 2024

Choose a reason for hiding this comment

d-ronnqvist commented Jun 27, 2024

d-ronnqvist commented Jun 27, 2024

mustiikhalil commented Mar 5, 2024 •

edited

Loading

sofiaromorales commented Mar 8, 2024 •

edited

Loading

mustiikhalil commented Mar 8, 2024 •

edited

Loading