<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Feb 10, 2016 at 9:05 PM, Matthew Judge <span dir="ltr">&lt;<a href="mailto:matthew.judge@gmail.com" target="_blank">matthew.judge@gmail.com</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"><span><br>
<br>
&gt; On Feb 10, 2016, at 18:17, Dave Abrahams &lt;<a href="mailto:dabrahams@apple.com">dabrahams@apple.com</a>&gt; wrote:<br>
&gt;<br>
&gt;<br>
&gt;&gt; on Wed Feb 10 2016, Matthew Judge &lt;<a href="http://matthew.judge-AT-gmail.com" target="_blank" rel="noreferrer">matthew.judge-AT-gmail.com</a>&gt; wrote:<br>
&gt;&gt;<br>
&gt;&gt; On Tue, Feb 9, 2016 at 2:18 PM, Dave Abrahams via swift-evolution &lt;<br>
&gt;&gt; <a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>&gt; wrote:<br>
&gt;&gt;<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; Hi everybody,<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; Having looked at some examples, the API guidelines working group members<br>
&gt;&gt;&gt; that were present this morning agreed we really want prepositions inside<br>
&gt;&gt;&gt; the parentheses of method calls.<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; Here are some results for the importer; we&#39;re still tuning some of the<br>
&gt;&gt;&gt; heuristics but overall we feel very good about the preposition<br>
&gt;&gt;&gt; placement:<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; <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>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; Note that this is not final wording, but here are the guidelines we&#39;re<br>
&gt;&gt;&gt; working with for first argument labels:<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; A. Try to form a grammatical phrase including the first argument and<br>
&gt;&gt;&gt;   describing the primary semantics at the call site.<br>
&gt;&gt;<br>
&gt;&gt; I assume that A is intended to cover:<br>
&gt;&gt;<br>
&gt;&gt; a.addObserver(b) // yes<br>
&gt;&gt; a.add(observer: b) // no<br>
&gt;<br>
&gt; I don&#39;t know what you mean by &quot;cover.&quot; It isn&#39;t intended to assign the<br>
&gt; &quot;yes/no&quot; decision to those; they both form (the same) grammatical phrase<br>
&gt; at the call site.  The choice between those two is governed by B, below.<br>
<br>
</span>By cover I meant assign the &quot;yes/no&quot; decision. So because the first argument is part of the primary semantics, it doesn&#39;t get an argument label (per B.1) and the word observer needs to be in the base name so as not to change the semantic meaning.<br>
<div><div class="h5"><br>
&gt;<br>
&gt;&gt; I believe I can read this behavior into A by inferring &quot;a grammatical<br>
&gt;&gt; phrase including [the base name and] the first argument&quot; but I want to make<br>
&gt;&gt; sure this is the intent.<br>
&gt;&gt;<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt; B. The first argument gets a label when and only when:<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt;   1. It does not form part of a grammatical phrase describing the<br>
&gt;&gt;&gt;      primary semantics.  For example,<br>
&gt;&gt;&gt;      ```<br>
&gt;&gt;&gt;      x.dismiss(animated: y)<br>
&gt;&gt;&gt;      ```<br>
&gt;&gt;&gt;      [more examples needed]<br>
&gt;&gt;&gt;      Note that parameters with defaults never describe the primary<br>
&gt;&gt;&gt;      semantics. so are always labeled.<br>
&gt;&gt;&gt;      ```<br>
&gt;&gt;&gt;      func invert(options options: SomeOptionSet = []) // yes<br>
&gt;&gt;&gt;      func invert(_ options: SomeOptionSet = [])       // no<br>
&gt;&gt;&gt;      ```<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt;   2. The method is a factory method; such calls should mirror<br>
&gt;&gt;&gt;      initializers, with no preposition.  For example,<br>
&gt;&gt;&gt;      ```<br>
&gt;&gt;&gt;      let x = UIColor(red: r, green: g, blue: b)<br>
&gt;&gt;&gt;      let y = monitor.makeColor(red: r, green: g, blue: b)<br>
&gt;&gt;&gt;      ```<br>
&gt;&gt;<br>
&gt;&gt; If rule B.2 didn&#39;t exist<br>
&gt;&gt;<br>
&gt;&gt; let y = monitor.makeColor(red: r, green: g, blue: b)<br>
&gt;&gt;<br>
&gt;&gt; would still have the first argument labeled by B.1 wouldn&#39;t it?<br>
&gt;<br>
&gt; Yes, but you could have done this grammatically, as<br>
&gt;<br>
&gt;     let y = monitor.makeColorHavingRed(r, green: g, blue: b)<br>
&gt;<br>
&gt; That&#39;s what B2 is designed to prevent.<br>
&gt;<br>
&gt;&gt; (Though without this rule, the guidelines wouldn&#39;t be clear on whether<br>
&gt;&gt; or not to include prepositions in the argument labels.)<br>
&gt;&gt;<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt;   3. It is part of a prepositional phrase<br>
&gt;&gt;&gt;<br>
&gt;&gt;&gt;     a. The label normally starts with the preposition.<br>
&gt;&gt;&gt;        For example,<br>
&gt;&gt;&gt;        ```<br>
&gt;&gt;&gt;        x.move(from: a, to: b)<br>
&gt;&gt;&gt;        x.loadValues(forKeys: [&quot;fox&quot;, &quot;box&quot;, &quot;lox&quot;])<br>
&gt;&gt;&gt;        ```<br>
&gt;&gt;&gt;     b. ...unless the preposition would break a very tight association<br>
&gt;&gt;&gt;        between parameters:<br>
&gt;&gt;&gt;        ```<br>
&gt;&gt;&gt;        x.moveTo(x: a, y: b)<br>
&gt;&gt;&gt;        ```<br>
&gt;&gt;&gt;        [encourage grouping parameters into higher-level concepts,<br>
&gt;&gt;&gt;        e.g. Point, in these cases]<br>
&gt;&gt; This seems clear and straightforward to apply. The only place where<br>
&gt;&gt; this isn&#39;t totally clear is when there are multiple prepositions (as<br>
&gt;&gt; highlighted in Jacob&#39;s response),<br>
&gt;<br>
&gt; Multiple prepositions before the first argument?<br>
<br>
</div></div>Yes, before and including the first argument label. For example (from Jacob&#39;s response):<br>
<span><br>
comparePositionInDecodeOrderWithPosition(of cursor: AVSampleCursor) -&gt; ComparisonResult<br>
<br>
</span>Jacob suggests spelling it:<br>
<br>
comparePositionInDecodeOrder(withPositionOf cursor: AVSampleCursor) -&gt; ComparisonResult<br>
<br>
I agree that Jacob&#39;s spelling is better, but not enough better to justify additional guidelines about prepositions.<br></blockquote><div><br></div><div>To clarify/be precise, the guidelines as written are clear on how to treat this: put the prepositional phrase completed by the first argument in the argument label (unless B.3.b applies). </div><div><br></div><div>Where the ambiguity arises  is in deciding whether the first argument completes the prepositional phrase &quot;of&quot; or &quot;withPositionOf&quot; (or &quot;inDecodeOrderWithPositionOf&quot;). </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">
<div><div class="h5"><br>
&gt;<br>
&gt;&gt; but I think B.3 provides the right level of guidance... much more<br>
&gt;&gt; detail will start being too many guidelines and special cases.<br>
&gt;<br>
&gt; Thanks!<br>
&gt; --<br>
&gt; -Dave<br>
</div></div></blockquote></div><br></div></div>