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

Douglas_Gregor · March 3, 2016, 9:57pm

The review of SE-0005 "Better Translation of Objective-C APIs Into Swift" ran from January 22...February 5, 2016, with the discussion continuing long afterward. We were thrilled with the scope and depth of the community response to this proposal. The proposal is accepted with some significant modifications, detailed below. The proposal document has been updated at:

swift-evolution/0005-objective-c-name-translation.md at master · apple/swift-evolution · GitHub

as have the automatically-generated results for Cocoa APIs:

GitHub - apple/swift-3-api-guidelines-review

Most of the modifications to the proposal involve tracking changes to the Swift API Design Guidelines (SE-0023), especially:

* The Clang importer will "split" the first selector piece of a method before the last preposition, producing a base name (the words that precede the last preposition) and an argument label for the first argument (the preposition and the words that follow it). For example, the following Objective-C method:

- (void)exchangeSubviewAtIndex:(NSInteger)index1
withSubviewAtIndex:(NSInteger)index2

will be imported as

func exchangeSubview(at index1: Int, withSubviewAt index2: Int)

* The Clang importer will change enum cases to lowerCamelCase

* The Clang importer will lowercase initialisms at the beginning of non-type identifiers (e.g., "var UTF8String" becomes "var utf8String")

One significant part of the proposal was the removal of the "NS" prefix from Foundation APIs in Swift. This name change was considered problematic for several reasons, the most-often-cited one being that the reference-semantic nature of many Foundation types conflicted with the Swift standard library's value-semantic types. The "NS" prefix removal part of this proposal has been removed from the accepted proposal. A revised version of this will come back as its own proposal, taking into account the feedback received.

Another interesting aspect of the discussion centered on the naming of methods in delegates. It was observed that the naming of Cocoa delegates isn't captured in the Swift API Design Guidelines. There are a number of potential solutions, including extending the guidelines or [more Clang importer heuristics](http://thread.gmane.org/gmane.comp.lang.swift.evolution/4178/focus=5258\). We consider this to be an important but separable problem, so we consider this a reasonable follow-up investigation and won't try to tackle it within this proposal.

Thank you!
Doug Gregor
Review Manager

Radek_Pietruszewski · March 3, 2016, 11:00pm

Woohoo! This has been a great process discussing all the nitpicks to get it right, and I’m quite happy with the result.

Thanks Doug & all,
— Radek

···

On 03 Mar 2016, at 22:57, Douglas Gregor via swift-evolution <swift-evolution@swift.org> wrote:

The review of SE-0005 "Better Translation of Objective-C APIs Into Swift" ran from January 22...February 5, 2016, with the discussion continuing long afterward. We were thrilled with the scope and depth of the community response to this proposal. The proposal is accepted with some significant modifications, detailed below. 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:

GitHub - apple/swift-3-api-guidelines-review

Most of the modifications to the proposal involve tracking changes to the Swift API Design Guidelines (SE-0023), especially:

* The Clang importer will "split" the first selector piece of a method before the last preposition, producing a base name (the words that precede the last preposition) and an argument label for the first argument (the preposition and the words that follow it). For example, the following Objective-C method:

   - (void)exchangeSubviewAtIndex:(NSInteger)index1
               withSubviewAtIndex:(NSInteger)index2

will be imported as

   func exchangeSubview(at index1: Int, withSubviewAt index2: Int)

* The Clang importer will change enum cases to lowerCamelCase

* The Clang importer will lowercase initialisms at the beginning of non-type identifiers (e.g., "var UTF8String" becomes "var utf8String")

One significant part of the proposal was the removal of the "NS" prefix from Foundation APIs in Swift. This name change was considered problematic for several reasons, the most-often-cited one being that the reference-semantic nature of many Foundation types conflicted with the Swift standard library's value-semantic types. The "NS" prefix removal part of this proposal has been removed from the accepted proposal. A revised version of this will come back as its own proposal, taking into account the feedback received.

Another interesting aspect of the discussion centered on the naming of methods in delegates. It was observed that the naming of Cocoa delegates isn't captured in the Swift API Design Guidelines. There are a number of potential solutions, including extending the guidelines or [more Clang importer heuristics](http://thread.gmane.org/gmane.comp.lang.swift.evolution/4178/focus=5258\). We consider this to be an important but separable problem, so we consider this a reasonable follow-up investigation and won't try to tackle it within this proposal.

Thank you!
Doug Gregor
Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

benrimmington · March 4, 2016, 6:55am

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:

GitHub - 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

···

On 3 Mar 2016, at 21:57, Douglas Gregor via swift-evolution <swift-evolution@swift.org> wrote:

hlovatt · March 3, 2016, 10:36pm

Just wanted to say how well I think this review went. There was a lot of
feedback and you have handled all the competing opinions skilfully. Thanks,
-- Howard.

···

On Friday, 4 March 2016, Douglas Gregor via swift-evolution < swift-evolution@swift.org> wrote:

The review of SE-0005 "Better Translation of Objective-C APIs Into Swift"
ran from January 22...February 5, 2016, with the discussion continuing long
afterward. We were thrilled with the scope and depth of the community
response to this proposal. The proposal is accepted with some significant
modifications, detailed below. 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:

  GitHub - apple/swift-3-api-guidelines-review

Most of the modifications to the proposal involve tracking changes to the
Swift API Design Guidelines (SE-0023), especially:

* The Clang importer will "split" the first selector piece of a method
before the last preposition, producing a base name (the words that precede
the last preposition) and an argument label for the first argument (the
preposition and the words that follow it). For example, the following
Objective-C method:

    - (void)exchangeSubviewAtIndex:(NSInteger)index1
                withSubviewAtIndex:(NSInteger)index2

  will be imported as

    func exchangeSubview(at index1: Int, withSubviewAt index2: Int)

* The Clang importer will change enum cases to lowerCamelCase

* The Clang importer will lowercase initialisms at the beginning of
non-type identifiers (e.g., "var UTF8String" becomes "var utf8String")

One significant part of the proposal was the removal of the "NS" prefix
from Foundation APIs in Swift. This name change was considered problematic
for several reasons, the most-often-cited one being that the
reference-semantic nature of many Foundation types conflicted with the
Swift standard library's value-semantic types. The "NS" prefix removal part
of this proposal has been removed from the accepted proposal. A revised
version of this will come back as its own proposal, taking into account the
feedback received.

Another interesting aspect of the discussion centered on the naming of
methods in delegates. It was observed that the naming of Cocoa delegates
isn't captured in the Swift API Design Guidelines. There are a number of
potential solutions, including extending the guidelines or [more Clang
importer heuristics](
http://thread.gmane.org/gmane.comp.lang.swift.evolution/4178/focus=5258\).
We consider this to be an important but separable problem, so we consider
this a reasonable follow-up investigation and won't try to tackle it within
this proposal.

Thank you!
Doug Gregor
Review Manager

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <javascript:;>
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-- Howard.