docs: add an example to -Yindent-colons section

[SethTisue]

At least, I think this is the recommendation....... is it?

I admit this came up when I was intentionally expunging all braces from a repo of mine as an exercise, in an attempt to form an opinion on the future of -Yindent-colons

never using braces could be a pointless exercise, or it could be good pedagogically actually. it's simpler for learning if the answer to "do I ever actually need braces?" is "no"

in any case, I like knowing I have the option with locally

[soronpo]

it's simpler for learning if the answer to "do I ever actually need braces?" is "no"

As discussed on gitter, for the record, here is a counter example.

  extension (src : => Unit) def ==> (dst : => Unit) : Unit = ()
  locally {
    println("hi")    
  } ==>
  locally {
    println("there")
  }

There is no option to do so with indentation only.

[LPTK]

@soronpo you can do this:

locally:
  println("hi")    
.==> :
  println("there")

[LPTK]

@SethTisue I don't think the example you gave is a good one, as you can just write:

val dinner =
  val s1 = "fish"
  val s2 = "chips"
  List(s1, s2)

instead of:

val dinner = locally:
  val s1 = "fish"
  val s2 = "chips"
  List(s1, s2)

[SethTisue]

@LPTK well, dang. I thought I'd tried that? okay, I'll take a second look at the places in my codebase I thought I needed locally

[SethTisue]

better example now

[LPTK]

@SethTisue but you can just write this:

credentials ++ :
  val file = Path.userHome / ".credentials"
  if file.exists
  then Seq(Credentials(file))
  else Seq()

😄

[SethTisue]

okay, so the remaining use case is this kind of thing:

locally:
  println("hi")    
.==> :
  println("there")

which seems too niche to even cover, so I've revised this not to mention or use locally at all

my real mission here was to get my questions about -Yindent-colons answered, so, mission accomplished :-)

[LPTK]

Yes, I think the only use for locally is to open sub-scopes within the enclosing block. It's sometimes useful to avoid name clashes, and it works better than the old way with plain braces (which should not have anything right before them lest they're interpreted as block arguments).

[SethTisue]

@LPTK I think the following wording in the doc:

colons at end of lines are accepted at all points where an opening brace enclosing a function argument is legal

misled me; I read “function argument” as referring specifically to lambdas & by-names.

I have amended this PR to omit the word “function” there

[LPTK]

@SethTisue Ah yes, it's an English language ambiguity. I think the meaning originally intended by "enclosing a function argument" was "enclosing the argument to a function", not "enclosing a function passed as an argument". It could be misleading indeed!

[SethTisue]

Discussion has settled down and this is ready for merge, I believe.