"by" not described

[abellgithub]

The "Functions and methods" section has many examples using what seems to be a keyword "by" in arguments. I can find no place where this keyword is described, such as here preceding delta:

fun offset_let(_ v: Vector2, by delta: Vector2)

[dabrahams]

That's not a keyword; it's an argument label; a mandatory part of the function call syntax. Any identifier works there; with this one it's called as offset_let(someVector2, by: someOtherVector2)

[abellgithub]

That's fine, but I don't think it's described. Or maybe there are typos?

fun offset_let(_ v: let Vector2, by delta: let Vector2) -> Vector2 {
  (x: v.x + delta.x, y: v.y + delta.y)
}

Here there is "by delta:" delta is the name of the argument. How is by used?

[kyouko-taiga]

You use argument labels at call sites. For example:

fun offset_let(_ v: let Vector2, by delta: let Vector2) -> Vector2 {
  (x: v.x + delta.x, y: v.y + delta.y)
}

public fun main() {
  let v = Vector2(x: 1, y: 1)
  offset_let(v, by: Vector2(x: 2, y:, 0))
  //            ^^ here it is
}

[abellgithub]

So you use the label at the call site and the argument name in the function? But they refer to the same argument? This needs some good description and explanation IMO.

[dabrahams]

The label doesn't refer to anything, actually. It's just part of the syntax used in the function call, often used for clarifying words that distinguish the roles of the arguments when it is not identical to the parameter name, e.g. x.insert(a, into: b).

This comes directly from Swift, which see. The only difference is that Swift uses inconsistent rules for determining the implied argument label, when none is specified at the declaration site: for functions, it's the parameter name, but for subscripts and operators, it's _ (no label). While ultimately, it's our responsibility to document everything completely, the biggest reason to write documentation at this point is to make sure we understand what we're doing, and in this case we're confident, so it's not a super-high priority. If our documentation of this part of the language is incomplete or missing, though, thanks for pointing out the gap. We'd be very happy to accept a PR to that fixes the problem sooner than we'll get to it. There's really nothing more to know than I have explained here.