|
| 1 | +# Apply API Guidelines to the Standard Library |
| 2 | + |
| 3 | +* Proposal: [SE-0006](https://github.com/apple/swift-evolution/proposals/0006-apply-api-guidelines-to-the-standard-library.md) |
| 4 | +* Author(s): [Dave Abrahams](https://github.com/dabrahams), [Dmitri Gribenko](https://github.com/gribozavr), [Maxim Moiseev](https://github.com/moiseev) |
| 5 | +* Status: **Awaiting Review** |
| 6 | +* Review manager: [Doug Gregor](https://github.com/DougGregor) |
| 7 | + |
| 8 | +## Introduction |
| 9 | + |
| 10 | +[Swift API Design Guidelines][api-design-guidelines] being developed as |
| 11 | +part of Swift 3. It is important that the Standard Library is an exemplar of |
| 12 | +Swift API Design Guidelines: the APIs from the Standard Library are, probably, |
| 13 | +the most frequently used Swift APIs in any application domain; the Standard |
| 14 | +Library also sets precedent for other libraries. |
| 15 | + |
| 16 | +In this project, we are reviewing the entire Standard Library and updating it |
| 17 | +to follow the guidelines. |
| 18 | + |
| 19 | +## Proposed solution |
| 20 | + |
| 21 | +The actual work is being performed on the [swift-3-api-guidelines |
| 22 | +branch][swift-3-api-guidelines-branch] of the [Swift repository][swift-repo]. |
| 23 | +On high level, the changes can be summarized as follows. |
| 24 | + |
| 25 | +* Strip `Type` suffix from remaining protocol names. In a few special cases |
| 26 | + this means adding a `Protocol` suffix to get out of the way of type |
| 27 | + names that are primary (though most of these we expect to be |
| 28 | + obsoleted by Swift 3 language features). |
| 29 | + |
| 30 | +* The concept of `generator` is renamed to `iterator`. |
| 31 | + |
| 32 | +* `IndexingGenerator` is renamed to `DefaultCollectionIterator`. |
| 33 | + |
| 34 | +**More changes will be summarized here as they are implemented.** |
| 35 | + |
| 36 | +## API diffs |
| 37 | + |
| 38 | +Differences between Swift 2.2 Standard library API and the proposed API are |
| 39 | +added to this section as they are being implemented on the |
| 40 | +[swift-3-api-guidelines branch][swift-3-api-guidelines-repo]. |
| 41 | + |
| 42 | +## Impact on existing code |
| 43 | + |
| 44 | +The proposed changes are massively source-breaking for Swift code, and will |
| 45 | +require a migrator to translate Swift 2 code into Swift 3 code. The API diffs |
| 46 | +from this proposal will be the primary source of the information about the |
| 47 | +required transformations. In addition, to the extent the language allows, the |
| 48 | +library will keep old names as unavailable symbols with a `renamed` annotation, |
| 49 | +that allows the compiler to produce good error messages and emit Fix-Its. |
| 50 | + |
| 51 | +[api-design-guidelines]: https://swift.org/documentation/api-design-guidelines.html "API Design Guidelines" |
| 52 | +[swift-repo]: https://github.com/apple/swift "Swift repository" |
| 53 | +[swift-3-api-guidelines-branch]: https://github.com/apple/swift/tree/swift-3-api-guidelines "Swift 3 API Design Guidelines preview" |
| 54 | + |
0 commit comments