[swift-evolution] [Review] SE-0005 Better Translation of Objective-C APIs Into Swift

[Radosław Pietruszewski]

>>>> Exceptions:
>>>> - "fooWithOptions", but that's already caught by the default parameter rule.
>>>> - "fooWithLocale", which uses the locale to build the result.
>>>> - "commonPrefixWithString", where the "with" isn't quite vacuous.
>>>> 
>>>> But when "foo" is a verb (or when it's a later parameter that's just "withBar") it does seem pretty vacuous.
>>> 
>>> This is a great observation. Pull request here shows what this does:
>>> 
>>> 	https://github.com/apple/swift-3-api-guidelines-review/pull/9 <https://github.com/apple/swift-3-api-guidelines-review/pull/9>
>>> 
>>> and, from the cases we’ve looked at, does a fantastic job of distinguishing the cases where “with” is a separator vs. “with” meaning some kind of selection criteria.
>> 
>> Oh no! Now I'm sad I added a new automated rule based on parts of speech. As I've said before, these rules are necessarily incomplete, difficult for non-native speakers, and problematic when a word can be either a noun or a verb (cf. "displayNameWithLocale(_: NSLocale) -> String" and "highlightWithLevel(_: CGFloat) -> NSColor?”).
> 
> And they are (still) most of the basis for the automatic translation described in SE-0005. Frankly, I don’t think we can avoid using parts-of-speech analysis to transform Objective-C APIs into Swift APIs.
> 
>> I'm looking at the diff but it's hard to tell what didn't change. Are there branches that differentiate the two different "with" heuristics?
> 
> The swift-3-first-argument-labels branch is the initial “with” heuristic Radek proposed. You can see the diffs between that heuristic and the “verb” heuristic here:
> 
> 	https://github.com/apple/swift-3-api-guidelines-review/compare/swift-3-first-argument-labels...swift-3-first-argument-labels-verb <https://github.com/apple/swift-3-api-guidelines-review/compare/swift-3-first-argument-labels...swift-3-first-argument-labels-verb>

Ah, interesting!

I definitely see the rationale for this. Calling a method like `tracks` seems a bit confusing, it doesn’t capture the intent at all. The ObjC-convention version, say, `tracksWithMediaType(…)`, though less clear, makes a better job at this.

I can see more methods of this kind in the diff, and they seem to benefit the most.

I mentioned this before, but the way I would prefer this named is `findTracks(…)`, and skip the “with” in the name. The intent is captured better than the original, we start with a verb, and the method name is separated from its parameters. But obviously this is unlikely to work as an automated translation.

Having said that, a lot of the changes seem like a step back:


>    func highlight(level val: CGFloat) -> NSColor?		   func highlight(level val: CGFloat) -> NSColor?
> -  func shadow(level val: CGFloat) -> NSColor?		+  func shadowWithLevel(val: CGFloat) -> NSColor?

Inconsistency. Highlight analyzed as as a verb, shadow as a noun, even though those are obviously related.

> -  func blendedColor(fraction fraction: CGFloat, of color: NSColor) -> NSColor?		+  func blendedColorWithFraction(fraction: CGFloat, of color: NSColor) -> NSColor?

This doesn’t seem like an improvement. “fraction” and “color” seem very much like parameters to be separated from the name.

> -  class func availableColorSpaces(model model: NSColorSpaceModel) -> [NSColorSpace]		+  class func availableColorSpacesWith(model: NSColorSpaceModel) -> [NSColorSpace]
>  func indexOfItem(objectValue object: AnyObject) -> Int		+  func indexOfItemWithObjectValue(object: AnyObject) -> Int

Same…


> -  func reviewUnsavedDocuments(alertTitle title: String?, cancellable: Bool, delegate: AnyObject?, didReviewAllSelector: Selector, contextInfo: UnsafeMutablePointer<Void>)		+  func reviewUnsavedDocumentsWithAlertTitle(title: String?, cancellable: Bool, delegate: AnyObject?, didReviewAllSelector: Selector, contextInfo: UnsafeMutablePointer<Void>)

This definitely seem like a step back, “reviewUnsavedDocuments” works really well as a name, without the sort of confusion that the “tracks” mentioned above has.


> -  class func mouseEvent(type type: NSEventType, location: Point, modifierFlags flags: NSEventModifierFlags, timestamp time: TimeInterval, windowNumber wNum: Int, context: NSGraphicsContext?, eventNumber eNum: Int, clickCount cNum: Int, pressure: Float) -> NSEvent?		
> +  class func mouseEventWith(type: NSEventType, location: Point, modifierFlags flags: NSEventModifierFlags, timestamp time: TimeInterval, windowNumber wNum: Int, context: NSGraphicsContext?, eventNumber eNum: Int, clickCount cNum: Int, pressure: Float) -> NSEvent?

This one’s weird. “With” was added, but without “type” in the name.

* * *

Overall, I’m very conflicted about this diff. I’d obviously like the “with as a separator between method name and parameters” idea to go through, but not if there’s a lot of cases that seem more confusing for it. But I’m not convinced the heuristic suggested by Jordan can be implemented in a way it would work reliably. I can see more changes in the diff that seem worse than changes that seem like an improvement….

Best,
— Radek

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160202/64ac3f34/attachment.html>