Skip to content

Commit 8b7bf95

Browse files
committed
Merge pull request #1 from gribozavr/apply-api-guidelines-to-the-standard-library
Add a new proposal: 0006 Apply API Guidelines to the Standard Library
2 parents d3f50b5 + 4d4ef04 commit 8b7bf95

File tree

1 file changed

+54
-0
lines changed

1 file changed

+54
-0
lines changed
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
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

Comments
 (0)