[swift-evolution] [Accepted with modification] SE-0005 "Better Translation of Objective-C APIs Into Swift"

[Ben Rimmington]

> On 3 Mar 2016, at 21:57, Douglas Gregor via swift-evolution <swift-evolution at swift.org> wrote:
> 
> The proposal document has been updated at:
> 
>  https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md
> 
> as have the automatically-generated results for Cocoa APIs:
> 
>  https://github.com/apple/swift-3-api-guidelines-review

I like your choice of always using both the argument label and parameter name. "Clarity is more important than brevity."

<https://github.com/apple/swift-3-api-guidelines-review/commit/525e68966fb618c5be10b2a106d61c69e13f1311>

The existing API documentation already displays both, but the parameter name is italicized. If the Xcode source editor did the same, it would make one type of shadowing clearer.

Other comments and questions:

1. Adding default arguments will sometimes create ambiguities.

> extension NSData {
>   init(bytesNoCopy bytes: UnsafeMutablePointer<Void>, length length: Int)
> 
>   @available(iOS 7.0, *)
>   init(bytesNoCopy bytes: UnsafeMutablePointer<Void>, length length: Int, deallocator deallocator: ((UnsafeMutablePointer<Void>, Int) -> Void)? = nil)
> }

<https://github.com/apple/swift-3-api-guidelines-review/blob/swift-3/Platforms/iOS/Foundation/NSData.swift>

> error: ambiguous use of 'init(bytesNoCopy:length:)'
> NSData(bytesNoCopy: nil, length: 0)
> ^

2. Could you add labels to closure parameters, without changing the swift-corelibs-foundation ABI?

> - func enumerateByteRanges(_ block: (UnsafePointer<Void>, NSRange, UnsafeMutablePointer<ObjCBool>) -> Void)
> 
> + func enumerateByteRanges(_ block: (bytes: UnsafePointer<Void>, byteRange: NSRange, stop: UnsafeMutablePointer<ObjCBool>) -> Void)

3. Should first arguments with default values always be labelled?

> extension NSData {
>   @available(iOS 7.0, *)
>   func base64EncodedData(_ options: NSDataBase64EncodingOptions = []) -> NSData
> }

4. Your example UIBezierPath interface in "Proposed solution" doesn't match the latest results.

<https://github.com/apple/swift-3-api-guidelines-review/commit/64e3132a6a383b4a4603605180ded31efd37dcdc>

(i.e. Retain "with" after splitting more regularly.)

-- Ben