Add reference docs

Add sections to reference that explain the new
rules for eta expansion and auto-application.

Author: odersky

compiler/src/dotty/tools/dotc/typer/EtaExpansion.scala

@@ -79,7 +79,7 @@ object EtaExpansion {
    *     val xN = argN
    *     x0.f(x1, ..., xN)
    *
-   *  But leave idempotent expressions alone.
+   *  But leave pure expressions alone.
    *
    */
   def liftApp(defs: mutable.ListBuffer[Tree], tree: Tree)(implicit ctx: Context): Tree = tree match {

docs/docs/reference/changed/eta-expansion.md

@@ -0,0 +1,44 @@
+---
+layout: doc-page
+title: "Automatic Eta Expansion"
+---
+
+Previously, a method reference `m` was converted to a function value
+only if the expected type was a function type. If that was not the
+case, one had to write `m _` to force the conversion (which is called
+eta-expansion).
+
+For methods with one or more parameters, this restriction has now been
+dropped. Example:
+
+    def m(x: Boolean, y: String)(z: Int): List[Int]
+    val f1 = m
+    val f2 = m(true, "abc")
+
+This creates two function values:
+
+    f1: (Boolean, String) => Int => List[Int]
+    f2: Int => List[Int]
+
+The syntax `m _` is no longer needed and will be deprecated in the
+future.
+
+Automatic eta expansion does not apply to "nullary" methods that take an empty parameter list. Given
+
+    def next(): T
+
+, a simple reference to `next` does not auto-convert to a
+function. One has to write explicitely `() => next()` to achieve that
+(it's better to write it this way rather than `next _` because the latter
+will be deprecated).
+
+The reason for excluding nullary methods from automatic eta expansion
+is that Scala implicitly inserts the `()` argument, which would
+conflict with eta expansion. Automatic `()` insertion is
+[limited](auto-apply.md) in Dotty, but the fundamental ambiguity
+remains.
+
+### Reference
+
+For more info, see [PR #2701](https://github.com/lampepfl/dotty/pull/2701).
+

docs/docs/reference/dropped/auto-apply.md

@@ -0,0 +1,87 @@
+---
+layout: doc-page
+title: "Auto-Application"
+---
+
+Previously an empty argument list `()` was implicitly inserted when
+calling a nullary method without arguments. E.g.
+
+    def next(): T = ...
+    next     // is expanded to next()
+
+In Dotty, this idiom is an error.
+
+    next
+    ^
+    missing arguments for method next
+
+In Dotty, the application syntax has to follow exactly the parameter
+syntax. Excluded from this rule are methods that are defined in Java
+or that override methods defined in Java. The reason for being more
+lenient with such methods is that otherwise everyone would have to
+write
+
+    xs.toString().length()
+
+instead of
+
+    xs.toString.length
+
+The latter is idiomatic Scala because it conforms to the _uniform
+access principle_. This principle states that one should be able to
+change an object member from a field to a non-side-effecting method
+and back without affecting clients that access the
+member. Consequently, Scala encourages to define such "property"
+methods without a `()` parameter list whereas side-effecting methods
+should be defined with it. Methods defined in Java cannot make this
+distinction; for them a `()` is always mandatory. So Scala fixes the
+problem on the client side, by allowing the parameterless references.
+But where Scala allows that freedom for all method references, Dotty
+restricts it to references of external methods that are not defined
+themselves in Dotty.
+
+For reasons of backwards compatibility, Dotty for the moment also
+auto-inserts `()` for nullary methods that are defined in Scala 2, or
+that override a method defined in Scala 2. It turns out that, because
+the correspondence between definition and call was not enforced in
+Scala so far, there are quite a few method definitions in Scala 2
+libraries that use `()` in an inconsistent way. For instance, we
+find in `scala.math.Numeric`
+
+    def toInt(): Int
+
+whereas `toInt` is written without parameters everywhere
+else. Enforcing strict parameter correspondence for references to
+such methods would project the inconsistencies to client code, which
+is undesirable. So Dotty opts for more leniency when type-checking
+references to such methods until most core libraries in Scala 2 have
+been cleaned up.
+
+Stricter conformance rules also apply to overriding of nullary
+methods.  It is no longer allowed to override a parameterless method
+by a nullary method or _vice versa_. Instead, both methods must agree
+exactly in their parameter lists.
+
+    class A {
+      def next(): Int
+    }
+    class B extends A {
+      /*!*/ def next: Int // overriding error: incompatible type
+    }
+
+Methods overriding Java or Scala-2 methods are again exempted from this
+requirement.
+
+### Migrating code
+
+Existing Scala code with inconsistent parameters can still be compiled
+in Dotty under `-language:Scala2`. When paired with the `-rewrite`
+option, the code will be automatcally rewritten to conforrm to Dotty's
+stricter checking.
+
+### Reference
+
+For more info, see [Issue #2570](https://github.com/lampepfl/dotty/issue/2570) and [PR #2716](https://github.com/lampepfl/dotty/pull/2716).
+
+
+

docs/sidebar.yml

@@ -69,6 +69,8 @@ sidebar:
               url: docs/reference/changed/vararg-patterns.html
             - title: Pattern matching
               url: docs/reference/changed/pattern-matching.html
+            - title: Eta Expansion
+              url: docs/reference/changed/eta-expansion.html
         - title: Dropped Features
           subsection:
             - title: DelayedInit
@@ -89,6 +91,8 @@ sidebar:
               url: docs/reference/dropped/limit22.html
             - title: XML literals
               url: docs/reference/dropped/xml.html
+            - title: Auto-Application
+              url: docs/reference/dropped/auto-apply.html
     - title: Contributing
       subsection:
         - title: Getting Started

tests/neg/overrides.scala

@@ -40,6 +40,8 @@ class A[T] {
 
   def f(x: T)(y: T = x) = y
 
+  def next: T
+
 }
 
 class B extends A[Int] {
@@ -48,6 +50,8 @@ class B extends A[Int] {
 
   f(2)()
 
+  def next(): Int     // error: incompatible type
+
 }
 
 class X {