averello/swift-mirror
1
0
Fork 0
mirror of https://github.com/apple/swift.git synced 2025-12-14 20:36:38 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into rebranch

Browse Source
This commit is contained in:
swift-ci
2021-09-24 14:53:19 -07:00
parent f88c495c88 910b4eed59
commit bc61e6adee
1 changed files with 13 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/StandardLibraryProgrammersManual.md
View File

@@ -72,17 +72,28 @@ For historical reasons, the existing codebase generally uses `internal` as the c
Every entry point in the standard library that has an ABI impact must be applied an `@available` attribute that describes the earliest ABI-stable OS releases that it can be deployed on. (Currently this only applies to macOS, iOS, watchOS and tvOS, since Swift isn't ABI stable on other platforms yet.)
Unlike access control modifiers, we prefer to put `@available` attributes on the extension context rather than duplicating them on every individual entry point. This is an effort to fight against information overload: the `@available` attribute is information dense and it's generally easier to review/maintain if applied to a group of entry points all at once.
Just like access control modifiers, we prefer to put `@available` attributes on each individual access point, rather than just the extension in which they are defined.
```swift
// 👍
// 😢👎
@available(macOS 10.6, iOS 10, watchOS 3, tvOS 12, *)
extension String {
public func blanch() { ... }
public func roast() { ... }
}
// 🥲👍
extension String {
@available(macOS 10.6, iOS 10, watchOS 3, tvOS 12, *)
public func blanch() { ... }
@available(macOS 10.6, iOS 10, watchOS 3, tvOS 12, *)
public func roast() { ... }
}
```
This coding style is enforced by the ABI checker -- it will complain if an extension member declaration that needs an availability doesn't have it directly attached.
Features under development that haven't been released yet must be marked with the placeholder version number `9999`. This special version is always considered available in custom builds of the Swift toolchain (including development snapshots), but not in any ABI-stable production release.
```swift