Trial: Go back to witness syntax

This is an attempt to validate the current given design against my very first proposal
from more than a year ago: witnesses. I have duplicated the docs, replacing syntax
and terminology,

Author: odersky

docs/docs/reference/contextual-witnesses/context-bounds.md

@@ -0,0 +1,30 @@
+---
+layout: doc-page
+title: "Context Bounds"
+---
+
+## Context Bounds
+
+A context bound is a shorthand for expressing the common pattern of an implicit parameter that depends on a type parameter. Using a context bound, the `maximum` function of the last section can be written like this:
+```scala
+def maximum[T: Ord](xs: List[T]): T = xs.reduceLeft(max)
+```
+A bound like `: Ord` on a type parameter `T` of a method or class indicates an implicit parameter `(given Ord[T])`. The implicit parameter(s) generated from context bounds come last in the definition of the containing method or class. E.g.,
+```scala
+def f[T: C1 : C2, U: C3](x: T)(given y: U, z: V): R
+```
+would expand to
+```scala
+def f[T, U](x: T)(given y: U, z: V)(given C1[T], C2[T], C3[U]): R
+```
+Context bounds can be combined with subtype bounds. If both are present, subtype bounds come first, e.g.
+```scala
+def g[T <: B : C](x: T): R = ...
+```
+
+## Syntax
+
+```
+TypeParamBounds   ::=  [SubtypeBounds] {ContextBound}
+ContextBound      ::=  ‘:’ Type
+```

docs/docs/reference/contextual-witnesses/conversions.md

@@ -0,0 +1,75 @@
+---
+layout: doc-page
+title: "Implicit Conversions"
+---
+
+Implicit conversions are defined by witnesses of the `scala.Conversion` class.
+This class is defined in package `scala` as follows:
+```scala
+abstract class Conversion[-T, +U] extends (T => U)
+```
+For example, here is an implicit conversion from `String` to `Token`:
+```scala
+witness of Conversion[String, Token] {
+  def apply(str: String): Token = new KeyWord(str)
+}
+```
+Using an alias this can be expressed more concisely as:
+```scala
+witness of Conversion[String, Token] = new KeyWord(_)
+```
+An implicit conversion is applied automatically by the compiler in three situations:
+
+1. If an expression `e` has type `T`, and `T` does not conform to the expression's expected type `S`.
+2. In a selection `e.m` with `e` of type `T`, but `T` defines no member `m`.
+3. In an application `e.m(args)` with `e` of type `T`, if `T` does define
+   some member(s) named `m`, but none of these members can be applied to the arguments `args`.
+
+In the first case, the compiler looks for a `scala.Conversion` witness that maps
+an argument of type `T` to type `S`. In the second and third
+case, it looks for a `scala.Conversion` witness that maps an argument of type `T`
+to a type that defines a member `m` which can be applied to `args` if present.
+If such a witness `C` is found, the expression `e` is replaced by `C.apply(e)`.
+
+## Examples
+
+1. The `Predef` package contains "auto-boxing" conversions that map
+primitive number types to subclasses of `java.lang.Number`. For instance, the
+conversion from `Int` to `java.lang.Integer` can be defined as follows:
+```scala
+witness int2Integer of Conversion[Int, java.lang.Integer] =
+ java.lang.Integer.valueOf(_)
+```
+
+2. The "magnet" pattern is sometimes used to express many variants of a method. Instead of defining overloaded versions of the method, one can also let the method take one or more arguments of specially defined "magnet" types, into which various argument types can be converted. E.g.
+```scala
+object Completions {
+
+  // The argument "magnet" type
+  enum CompletionArg {
+    case Error(s: String)
+    case Response(f: Future[HttpResponse])
+    case Status(code: Future[StatusCode])
+  }
+  object CompletionArg {
+
+    // conversions defining the possible arguments to pass to `complete`
+    // these always come with CompletionArg
+    // They can be invoked explicitly, e.g.
+    //
+    //   CompletionArg.fromStatusCode(statusCode)
+
+    witness fromString     of Conversion[String, CompletionArg]               = Error(_)
+    witness fromFuture     of Conversion[Future[HttpResponse], CompletionArg] = Response(_)
+    witness fromStatusCode of Conversion[Future[StatusCode], CompletionArg]   = Status(_)
+  }
+  import CompletionArg._
+
+  def complete[T](arg: CompletionArg) = arg match {
+    case Error(s) => ...
+    case Response(f) => ...
+    case Status(code) => ...
+  }
+}
+```
+This setup is more complicated than simple overloading of `complete`, but it can still be useful if normal overloading is not available (as in the case above, since we cannot have two overloaded methods that take `Future[...]` arguments), or if normal overloading would lead to a combinatorial explosion of variants.