<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">&lt;<a href="mailto:swift-evolution@swift.org" target="_blank">swift-evolution@swift.org</a>&gt;</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&#39;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&#39;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 &quot;a grammatical phrase including [the base name and] the first argument&quot; 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&#39;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&#39;t it? (Though without this rule, the guidelines wouldn&#39;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: [&quot;fox&quot;, &quot;box&quot;, &quot;lox&quot;])<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&#39;t totally clear is when there are multiple prepositions (as highlighted in Jacob&#39;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>