<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><br class=""><div><blockquote type="cite" class=""><div class="">On Feb 1, 2016, at 3:45 PM, Radosław Pietruszewski <<a href="mailto:radexpl@gmail.com" class="">radexpl@gmail.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><meta http-equiv="Content-Type" content="text/html charset=utf-8" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><blockquote type="cite" class=""><div class=""><blockquote type="cite" class=""><div class=""><div class=""><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class=""><blockquote type="cite" class=""><div class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div class="">Exceptions:</div><div class="">- "fooWithOptions", but that's already caught by the default parameter rule.</div><div class="">- "fooWithLocale", which uses the locale to build the result.</div><div class="">- "commonPrefixWithString", where the "with" isn't <i class="">quite</i> vacuous.</div><div class=""><br class=""></div><div class="">But when "foo" is a verb (or when it's a later parameter that's just "withBar") it does seem pretty vacuous.</div></div></div></blockquote><br class=""></div><div class="">This is a great observation. Pull request here shows what this does:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space: pre;"> </span><a href="https://github.com/apple/swift-3-api-guidelines-review/pull/9" class="">https://github.com/apple/swift-3-api-guidelines-review/pull/9</a></div><div class=""><br class=""></div><div class="">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.</div></div></div></blockquote><br class=""></div><div class="">Oh no! Now I'm sad I added a new <i class="">automated</i> 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?”).</div></div></blockquote><div class=""><br class=""></div><div class="">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.</div><br class=""><blockquote type="cite" class=""><div class=""><div class="">I'm looking at the diff but it's hard to tell what <i class="">didn't</i> change. Are there branches that differentiate the two different "with" heuristics?</div></div></blockquote><br class=""></div><div class="">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:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space: pre;"> </span><a href="https://github.com/apple/swift-3-api-guidelines-review/compare/swift-3-first-argument-labels...swift-3-first-argument-labels-verb" class="">https://github.com/apple/swift-3-api-guidelines-review/compare/swift-3-first-argument-labels...swift-3-first-argument-labels-verb</a></div></blockquote></div><div class=""><br class=""></div><div class="">Ah, interesting!</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">I can see more methods of this kind in the diff, and they seem to benefit the most.</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">Having said that, a lot of the changes seem like a step back:</div><div class=""><br class=""></div><div class=""><br class=""><blockquote type="cite" class=""> func highlight(level val: CGFloat) -> NSColor?<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span> func highlight(level val: CGFloat) -> NSColor?<br class="">- func shadow(level val: CGFloat) -> NSColor?<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func shadowWithLevel(val: CGFloat) -> NSColor?</blockquote><br class=""></div><div class="">Inconsistency. Highlight analyzed as as a verb, shadow as a noun, even though those are obviously related.</div></div></div></blockquote><div><br class=""></div><div>Yes, this is an inconsistency we would need to deal with via NS_SWIFT_NAME. “highlight” is acting as an adjective here, although it’s predominantly a verb in Cocoa APIs.</div><br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><br class=""></div><div class=""><blockquote type="cite" class="">- func blendedColor(fraction fraction: CGFloat, of color: NSColor) -> NSColor?<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func blendedColorWithFraction(fraction: CGFloat, of color: NSColor) -> NSColor?</blockquote><br class=""></div><div class="">This doesn’t seem like an improvement. “fraction” and “color” seem very much like parameters to be separated from the name.</div></div></div></blockquote><div><br class=""></div><div>Note that this is the intent of the change, however: blendedColor is a noun phrase describing the result, and “withFraction” is a characteristic of the resulting color.</div><br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><br class=""></div><div class=""><blockquote type="cite" class="">- class func availableColorSpaces(model model: NSColorSpaceModel) -> [NSColorSpace]<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ class func availableColorSpacesWith(model: NSColorSpaceModel) -> [NSColorSpace]</blockquote><blockquote type="cite" class=""> func indexOfItem(objectValue object: AnyObject) -> Int<span class="Apple-tab-span" style="white-space: pre;"> </span><span class="Apple-tab-span" style="white-space: pre;"> </span>+ func indexOfItemWithObjectValue(object: AnyObject) -> Int</blockquote><br class=""></div><div class="">Same…</div></div></div></blockquote><div><br class=""></div>With the same answer: both start with noun phrases describing the result, so the “with” is acting more like “having”, indicating that the parameter is describing the characteristics of the result.</div><div><br class=""></div><div><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><br class=""></div><div class=""><br class=""><blockquote type="cite" class="">- func reviewUnsavedDocuments(alertTitle title: String?, cancellable: Bool, delegate: AnyObject?, didReviewAllSelector: Selector, contextInfo: UnsafeMutablePointer<Void>)<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span>+ func reviewUnsavedDocumentsWithAlertTitle(title: String?, cancellable: Bool, delegate: AnyObject?, didReviewAllSelector: Selector, contextInfo: UnsafeMutablePointer<Void>)</blockquote><br class=""></div><div class="">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.</div></div></div></blockquote><div><br class=""></div><div>Somehow, “review” wasn’t in my list of verbs. I’ll fix this.</div><br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><blockquote type="cite" class="">- 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?<span class="Apple-tab-span" style="white-space:pre"> </span><span class="Apple-tab-span" style="white-space:pre"> </span></blockquote><blockquote type="cite" class="">+ 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?</blockquote><br class=""></div><div class="">This one’s weird. “With” was added, but without “type” in the name.</div></div></div></blockquote><div><br class=""></div><div>“type” is redundant with the type info, so it has been pruned.</div><div><br class=""></div><br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><br class=""></div><div class="">* * *</div><div class=""><br class=""></div><div class="">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….</div></div></div></blockquote></div><div class=""><br class=""></div>There is definitely a mindset difference between this diff and the diff corresponding to with-as-separator. This diff produces fewer first argument labels, but maintains many cases where the “with” is useful for describing the characteristics of the results.<br class=""><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span>- Doug</div><div class=""><br class=""></div></body></html>