<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Feb 9, 2016 at 2:18 PM, Dave Abrahams via swift-evolution <span dir="ltr"><<a href="mailto:swift-evolution@swift.org" target="_blank">swift-evolution@swift.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid"><br>
Hi everybody,<br>
<br>
Having looked at some examples, the API guidelines working group members<br>
that were present this morning agreed we really want prepositions inside<br>
the parentheses of method calls.<br>
<br>
Here are some results for the importer; we're still tuning some of the<br>
heuristics but overall we feel very good about the preposition<br>
placement:<br>
<br>
<a href="https://github.com/apple/swift-3-api-guidelines-review/commit/da7e512cf75688e6da148dd2a8b27ae9efcb8821?diff=split" target="_blank" rel="noreferrer">https://github.com/apple/swift-3-api-guidelines-review/commit/da7e512cf75688e6da148dd2a8b27ae9efcb8821?diff=split</a><br>
<br>
Note that this is not final wording, but here are the guidelines we're<br>
working with for first argument labels:<br>
<br>
A. Try to form a grammatical phrase including the first argument and<br>
describing the primary semantics at the call site.<br></blockquote><div><br></div><div>I assume that A is intended to cover:</div><div><br></div><div>a.addObserver(b) // yes</div><div>a.add(observer: b) // no</div><div><br></div><div>I believe I can read this behavior into A by inferring "a grammatical phrase including [the base name and] the first argument" but I want to make sure this is the intent.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid">
<br>
B. The first argument gets a label when and only when:<br>
<br>
1. It does not form part of a grammatical phrase describing the<br>
primary semantics. For example,<br>
```<br>
x.dismiss(animated: y)<br>
```<br>
[more examples needed]<br>
Note that parameters with defaults never describe the primary<br>
semantics. so are always labeled.<br>
```<br>
func invert(options options: SomeOptionSet = []) // yes<br>
func invert(_ options: SomeOptionSet = []) // no<br>
```<br>
<br>
2. The method is a factory method; such calls should mirror<br>
initializers, with no preposition. For example,<br>
```<br>
let x = UIColor(red: r, green: g, blue: b)<br>
let y = monitor.makeColor(red: r, green: g, blue: b)<br>
```<br></blockquote><div> </div><div>If rule B.2 didn't exist </div><div><br></div><div>let y = monitor.makeColor(red: r, green: g, blue: b)</div><div><br></div><div>would still have the first argument labeled by B.1 wouldn't it? (Though without this rule, the guidelines wouldn't be clear on whether or not to include prepositions in the argument labels.)</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid">
<br>
3. It is part of a prepositional phrase<br>
<br>
a. The label normally starts with the preposition.<br>
For example,<br>
```<br>
x.move(from: a, to: b)<br>
x.loadValues(forKeys: ["fox", "box", "lox"])<br>
```<br>
b. ...unless the preposition would break a very tight association<br>
between parameters:<br>
```<br>
x.moveTo(x: a, y: b)<br>
```<br>
[encourage grouping parameters into higher-level concepts,<br>
e.g. Point, in these cases]<br>
<br></blockquote><div> </div><div>This seems clear and straightforward to apply. The only place where this isn't totally clear is when there are multiple prepositions (as highlighted in Jacob's response), but I think B.3 provides the right level of guidance... much more detail will start being too many guidelines and special cases.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid">
<br>
Feedback most welcome, of course.<br>
<span><font color="#888888">--<br>
-Dave<br>
<br>
_______________________________________________<br>
swift-evolution mailing list<br>
<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a><br>
<a href="https://lists.swift.org/mailman/listinfo/swift-evolution" target="_blank" rel="noreferrer">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br>
</font></span></blockquote></div><br></div></div>