Documentation is unclear about new brace-less syntax

[winitzki]

The documentation for the new syntax - arguably, a very important change in Scala 3 - is confusing.

The file is https://github.com/lampepfl/dotty/blob/master/docs/docs/reference/other-new-features/indentation.md and the relevant section is titled "Optional braces around template bodies". https://dotty.epfl.ch/docs/reference/other-new-features/indentation.html#optional-braces-around-template-bodies

First, it explains that the change introduces a colon at end of line. Then it gives examples, some of which do not involve any colon at all:

With these new rules, the following constructs are all valid:

...

type T = A:
  def f: Int

given [T](using Ord[T]): Ord[List[T]] with
  def compare(x: List[T], y: List[T]) = ???

extension (xs: List[Int])
  def second: Int = xs.tail.head

...

In the example with type T = A: it is not clear what is being done; is this type T = A with Object { def f: Int } or something else?

But the next two examples are given ... with and extension, which do not involve a colon at the end of line. The first one is the given ... with, and it is confusing since the with keyword is never explained. Actually, this use of the with keyword seems to be never mentioned in the documentation.

The example with extension does not have a colon at the end of line. Is this an error?

Please make the documentation complete in these crucial aspects. I would have pushed a PR directly for this documentation file, except that I don't actually know what would be the right explanation for those examples.

[b-studios]

Thanks for reporting, I added it to the umbrella issue #10633 so when somebody touches this part of the documentation we can also consider your remarks here.