search

swiftlang / swift-docc

Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.
https://swift.org/documentation/docc
Apache License 2.0
1.17k stars 123 forks source link

Add `*` support for `@Available` directive #969

Open anferbui opened 2 months ago

anferbui commented 2 months ago

Feature Name

Support platform name * in @Available directive

Description

We've added support for introduced and deprecated for the @Available directive in https://github.com/apple/swift-docc/pull/440 and https://github.com/apple/swift-docc/issues/441.

We should also add support for * as a value for the platform name, as currently it's not supported: https://github.com/apple/swift-docc/blob/f019ab8e2e0370d8f95921d4b8f1f7309c4eedbc/Sources/SwiftDocC/Semantics/Metadata/Availability.swift#L66-L69

This would potentially be used like:

@Available(*, introduced: "1.0")

Motivation

We should add support for * as a platform name to better reflect that a large number of packages work on Linux and Windows and anywhere else where Swift is supported.

More context here: https://github.com/apple/swift-docc/pull/851#issuecomment-2163550785

Importance

The @Available directive is missing some functionality until we implement this feature.

Alternatives Considered

No response

mustiikhalil commented 2 months ago

Hej, I would love to complete the work I started at #441 however I would also love to know the specs that are required for this feature to be viable. Since from my understanding the team working on DocC hasn't reached to an agreement on how its supposed to work and how its represented within the docs

sofiaromorales commented 2 months ago

Hi @mustiikhalil

I would also love to know the specs that are required for this feature to be viable.

The specs for this are still not defined, we have hade some discussion about it here https://forums.swift.org/t/documentation-workgroup-meeting-june-3rd-2024/72160/5 but nothing else has been decided since then.

As a first step this needs to be discussed in the forums so the community can agree on which is the best solution, until then there's no implementation that can be done.

If you are interested in kicking off the conversation by pitching a proposal in the forums, I could review a draft of the pitch before posting it, or you could bring this topic into the documentation workgroup.