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

[Matthew Johnson]

> On Jan 27, 2016, at 1:22 PM, Ben Rimmington via swift-evolution <swift-evolution at swift.org> wrote:
> 
> Doug,
> 
>> On 27 Jan 2016, at 07:50, Douglas Gregor via swift-evolution <swift-evolution at swift.org> wrote:
>> 
>> Another random interesting example I encountered:
>> 
>> -  func addArcWithCenter(center: CGPoint, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)
>> +  func addArc(center center: CGPoint, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)
>> 
>> which seems to match the idea behind Erica’s "semantic relationship between the parameters is stronger than their relation to the operation” (or Paul Cantrell’s similar notion of "the direct object is several args taken together”, which feels more in line with the way the API guidelines are written).
> 
> The related AppKit.NSBezierPath method contains two possible "With" separators:
> 
>> - (void)appendBezierPathWithArcWithCenter:(NSPoint)center
>>                                   radius:(CGFloat)radius
>>                               startAngle:(CGFloat)startAngle
>>                                 endAngle:(CGFloat)endAngle
>>                                clockwise:(BOOL)clockwise
> 
> Your patch replaces the second "With" separator, but the alternative might be better:
> 
>> // YOUR PATCH:
>> func appendWithArc(center center: Point, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)
>> 
>> // THE ALTERNATIVE:
>> func append(arcWithCenter center: Point, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)

This is better IMO:

func appendArc(center center: Point, radius: CGFloat, startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)

However, I think this is an example of where explicit annotation is probably necessary to get the best result.  A heuristic can’t always do the right thing and I think this example is past the point of diminishing returns for heuristics.

-Matthew

> 
> -- Ben
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution