Merge pull request #2583 from dotty-staging/add-reference-2

Add section on dropping DelayedInit

Author: odersky

docs/docs/reference/dropped/class-shadowing.md

@@ -0,0 +1,29 @@
+---
+layout: doc-page
+title: Dropped: Class Shadowing
+---
+
+Scala so far allowed patterns like this:
+
+    class Base {
+      class Ops { ... }
+    }
+
+    class Sub extends Base {
+      class Ops { ... }
+    }
+
+Dotty rejects this with the error message:
+
+    6 |      class Ops {  }
+      |            ^
+      |class Ops cannot have the same name as class Ops in class Base -- class definitions cannot be overridden
+
+The issue is that the two `Ops` classes _look_ like one overrides the
+other, but classes in Scala cannot be overridden. To keep things clean
+(and its internal operations conistent) the Dotty compiler forces you
+to rename the inner classes so that their names are different.
+
+
+
+

docs/docs/reference/dropped/delayedInit.md

@@ -0,0 +1,26 @@
+---
+layout: doc-page
+title: Dropped: Delayedinit
+---
+
+The special handling of the `DelayedInit` trait is no longer
+supported.
+
+One consequence is that the `App` class, which used `DelayedInit` is
+now partially broken. You can still use `App` for an easy and concise
+way to set up a main program. Example:
+
+    object HelloWorld extends App {
+      println("Hello, world!")
+    }
+
+However, the code is now run in the initializer of the object, which on
+some JVM's means that it will only be interpreted. So, better not use it
+for benchmarking! Also, if you want to access the command line arguments,
+you need to use an explicit `main` method for that.
+
+    object Hello {
+      def main(args: Array[String]) =
+        println(s"Hello, ${args(0)}")
+    }
+

docs/docs/reference/dropped/early-initializers.md

@@ -0,0 +1,11 @@
+---
+layout: doc-page
+title: Dropped: Early Initializers
+---
+
+Early initializers of the form
+
+    class C extends { ... } with SuperClass ...
+
+have been dropped. They were rarely used, and mostly to compensate for the lack of
+[trait parameters](../trait-parameters.md), which are now directly supported in Dotty.

docs/docs/reference/dropped/existential-types.md

@@ -0,0 +1,33 @@
+---
+layout: doc-page
+title: Dropped: Existential Types
+---
+
+Existential types using `forSome` have been dropped. The reasons for dropping them were:
+
+ - Existential types violate a type soundness principle on which DOT
+   and Dotty are constructed. That principle says that every the
+   prefix (`p`, respectvely `S`) of a type selection `p.T` or `S#T`
+   must either come from a value constructed at runtime or refer to a
+   type that is known to have only good bounds.
+
+ - Existential types create many difficult feature interactions
+   with other Scala constructs.
+
+ - Existential types have large overlap with path-dependent types,
+   so the gain of having them is relatively minor.
+
+Existential types that can be expressed using only wildcards (but not
+`forSome`) are still supported, but are treated as refined types.
+For instance, the type
+
+    Map[_ <: AnyRef, Int]
+
+is treated as the type `Map`, where the first type parameter
+is upper-bounded by `AnyRef` and the second type parameter is an alias
+of `Int`.
+
+When reading classfiles compiled with _scalac_, Dotty will do a best
+effort to approximate existential types with its own types. It will
+issue a warning is a precise emulation is not possible.
+

docs/docs/reference/dropped/limit22.md

@@ -0,0 +1,13 @@
+---
+layout: doc-page
+title: Dropped: Limit 22
+---
+
+The limit of 22 for the maximal number of parameters of function types
+has been dropped.  Functions can now have an arbitrary number of
+parameters. Functions beyond Function22 are represented with a new trait
+`scala.FunctionXXL`.
+
+The limit of 22 for the size of tuples is about to be dropped. Tuples
+will in the future be represented by an HList-like structure which can
+be arbitrarily large.

docs/docs/reference/dropped/macros.md

@@ -0,0 +1,13 @@
+---
+layout: doc-page
+title: Dropped: Macros
+---
+
+The previous, experimental macro system has been dropped. Instead,
+there is a cleaner, more restricted system based on two complementary
+concepts: `inline` and `meta`.
+
+`inline` has been [implemented](../inline.md) in Dotty.
+
+`meta` is worked on in the separate [Scalameta](http://scalameta.org) project
+

docs/docs/reference/dropped/procedure-syntax.md

@@ -0,0 +1,19 @@
+---
+layout: doc-page
+title: Dropped: Procedure Syntax
+---
+
+Procedure syntax
+
+    def f() { ... }
+
+has been dropped. You need to write one of the following instead:
+
+    def f() = { ... }
+    def f(): Unit = { ... }
+
+Dotty will accept the old syntax under the `-language:Scala2` option.
+If the `-migration` option is set, it can even rewrite old syntax to new.
+The [ScalaFix](https://scalacenter.github.io/scalafix/) tool also
+can rewrite procedure syntax to make it Dotty-compatible.
+

docs/docs/reference/dropped/type-projection.md

@@ -0,0 +1,15 @@
+---
+layout: doc-page
+title: Dropped: General Type Projection
+---
+
+Scala so far allowed general type projection `T#A` where `T` is an arbitrary type
+and `A` names a type member of `T`.
+
+Dotty allows this only if `T` is a class type. The change was made because
+unrestricted type projection is [unsound](https://github.com/lampepfl/dotty/issues/1050).
+
+The restriction rule out the [type-level encoding of compbinator
+ calculus](https://michid.wordpress.com/2010/01/29/scala-type-level-encoding-of-the-ski-calculus/). It also rules out the previous encodings of type
+lambdas using structural types with projection as application.  Type
+ lambdas are now [directly supported](../type-lambdas.md) in Dotty.

docs/docs/reference/dropped/xml.md

@@ -0,0 +1,9 @@
+---
+layout: doc-page
+title: Dropped: XML Literals
+---
+
+XML Literals are still supported, but will be dropped in the near future, to
+be replaced with XML string interpolation
+
+    xml""" ... """

docs/sidebar.yml

@@ -3,32 +3,58 @@ sidebar:
       url: blog/index.html
     - title: Reference
       subsection:
-        - title: Implicit Function Types
-          url: docs/reference/implicit-function-types.md
-        - title: Intersection types
-          url: docs/reference/intersection-types.html
-        - title: Union types
-          url: docs/reference/union-types.html
-        - title: Type lambdas
-          url: docs/reference/type-lambdas.html
+        - title: New Types
+          subsection:
+            - title: Implicit Function Types
+              url: docs/reference/implicit-function-types.md
+            - title: Intersection types
+              url: docs/reference/intersection-types.html
+            - title: Union types
+              url: docs/reference/union-types.html
+            - title: Type lambdas
+              url: docs/reference/type-lambdas.html
+        - title: Enums
+          subsection:
+            - title: Enumerations
+              url: docs/reference/enums.html
+            - title: Algebraic Data Types
+              url: docs/reference/adts.html
+            - title: Translation
+              url: docs/reference/desugarEnums.html
         - title: Trait Parameters
           url: docs/reference/trait-parameters.html
-        - title: Enumerations
-          url: docs/reference/enums.html
-        - title: Algebraic Data Types
-          url: docs/reference/adts.html
-        - title: Enum Translation
-          url: docs/reference/desugarEnums.html
-        - title: Multiversal Equality
+         -title: Multiversal Equality
           url: docs/reference/multiversal-equality.html
-        - title: By-Name Implicits
-          url: docs/reference/implicit-by-name-parameters.htmldocs/reference/implicit-by-name-parameters.html
-        - title: Auto Parameter Tupling
-          url: docs/reference/auto-parameter-tupling.html
-        - title: Named Type Arguments
-          url: docs/reference/named-typeargs.html
         - title: Inline
           url: docs/reference/inline.html
+        - title: Smaller Changes
+          subsection:
+            - title: By-Name Implicits
+              url: docs/reference/implicit-by-name-parameters.html
+            - title: Auto Parameter Tupling
+              url: docs/reference/auto-parameter-tupling.html
+            - title: Named Type Arguments
+              url: docs/reference/named-typeargs.html
+        - title: Dropped Features
+          subsection:
+            - title: DelayedInit
+              url: docs/reference/dropped/delayed-init.md
+            - title: Macros
+              url: docs/reference/dropped/macros.md
+            - title: Existential Types
+              url: docs/reference/dropped/existential-types.md
+            - title: Type Projection
+              url: docs/reference/dropped/type-projection.md
+            - Procedure Syntax
+              url: docs/reference/dropped/procedure-syntax.md
+            - title: Early Initializers
+              url: docs/reference/dropped/early-initializers.md
+            - title: Class Shadowing
+              url: docs/reference/dropped/class-shadowing.md
+            - title: Limit 22
+              url: docs/reference/dropped/limit22.md
+            - title: XML literals
+              url: docs/reference/dropped/xml.md
     - title: Usage
       subsection:
         - title: sbt-projects