[swift-evolution] When to use argument labels, part DEUX (was: when to use argument labels (a new approach))

[Dave Abrahams]

Given all the awesome feedback I've gotten on this thread, I went back
to the drawing board and came up with something new; I think this one
works.  The previously-stated goals still apply:

* describe when and where to use argument labels
* require labels in many of the cases people have asked for them
* are understandable by humans (this means relatively simple)
* preserve important semantics communicated by existing APIs.

Please keep in mind that it is a non-goal to capture considerations we
think have a bearing on good names (such as relatedness of parameters):
it's to create simple guidelines that have the right effect in nearly
all cases.

A. When arguments can't be usefully distinguished from one another, none
   should have argument labels, e.g. min(x,y), zip(x,y,z).  

B. Otherwise,

  1. At the call site, a first parameter that has no argument label must
     form part of a grammatical phrase that starts with the basename, less
     any trailing nouns.  

       print(x)
       a.contains(b)
       a.mergeWith(b)
       a.addGestureRecognizer(x)
            ^~~~~~~~~~~~~~~~~ trailing noun

     This phrase must have the correct semantic implications, so, e.g.

       a.dismiss(b)           // no, unless a is really dismissing b
       a.dismissAnimated(b)   // no, not grammatical
       a.dismiss(animated: b) // yes, using a label

  2. If the first argument is part of a prepositional phrase, put the
     parenthesis immediately after the preposition. 

       a.encodeWith(b)
       a.moveFrom(b, to: c)

     Thus, if words are required for any reason between the preposition
     and the first argument, they go into the first argument label.

       a.tracksWith(mediaType: b, composer: c)
       a.moveTo(x: 22, y: 99)

Notes: 

a. I would recommend prepositions other than "with" in nearly all
   cases, but that's not the point of these rules.
b. I can understand the aesthetic appeal of

    a.move(from: b, to: c)

   but I believe it is not a clear enough improvement to justify
   additional complexity in the guidelines.

Questions:

1. I'm not expecting these guidelines to make everybody optimally happy,
   all the time, but they shouldn't be harmful.  Are there any cases for
   which they produce results you couldn't live with?

2. Are there any cases where you'd be confused about how to apply these
   guidelines?
                               
Thanks in advance for all your valuable input!

P.S. Doug is presently working on generating new importer results, based
     on these guidelines, for your perusal.  They should be ready soon.

-- 
-Dave