Add doc page

Author: odersky

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

@@ -1170,7 +1170,7 @@ class Namer { typer: Typer =>
                 ctx.error(UnableToExtendSealedClass(pclazz), cls.sourcePos)
               else if ctx.settings.strict.value then
                 checkFeature(nme.adhocExtensions,
-                  i"Unless $pclazz with flags ${pclazz.flagsString} is declared 'open', its extension in a separate file",
+                  i"Unless $pclazz is declared 'open', its extension in a separate file",
                   cls.topLevelClass,
                   parent.sourcePos)
             pt

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

@@ -1756,7 +1756,6 @@ class Typer extends Namer
       // check value class constraints
       checkDerivedValueClass(cls, body1)
 
-
       // Temporarily set the typed class def as root tree so that we have at least some
       // information in the IDE in case we never reach `SetRootTree`.
       if (ctx.mode.is(Mode.Interactive) && ctx.settings.YretainTrees.value)

docs/docs/reference/other-new-features/open-classes.md

@@ -0,0 +1,78 @@
+---
+layout: doc-page
+title: "Open Classes"
+---
+
+An `open` modifier on a class signals that the class is planned for extensions. Example:
+```scala
+// File Writer.scala
+package p
+
+open class Writer[T] with
+
+  /** Sends to stdout, can be overridden */
+  def send(x: T) = println(x)
+
+  /** Send all arguments using `send` */
+  def sendAll(xs: T*) = xs.foreach(send)
+
+// File EncryptedWriter.scala
+package p
+
+class EncryptedWriter[T: Encryptable] extends Writer[T] with
+  override def send(x: T) = super.send(encrypt(x))
+```
+An open class typically comes with some documentation that describes
+the internal calling patterns between methods of the class as well as hooks that can be overridden. We call this the _extension contract_ of the class. It is different from the _external contract_ between a class and its users.
+
+Classes that are not open can still be extended, but only if one of two alternative conditions hold:
+
+ - The extending class is in the same source file as the extended class. In this case, the extension is usually an internal implementation matter.
+
+ - The language feature `adhocExtensions` is enabled for the extending class. This is typically enabled by an import statement
+   ```scala
+   import scala.language.adhocExtensions
+   ```
+   in the source file of the extension, but can alternatively be provided
+   by a command line option `-language:adhocExtensions`.
+   If the feature is not enabled, the compiler will issue a "feature" warning. For instance, if the `open` modifier on class `Writer` is dropped, compiling `EncryptedWriter` would produce a warning:
+   ```
+   -- Feature Warning: EncryptedWriter.scala:6:14 ----
+     |class EncryptedWriter[T: Encryptable] extends Writer[T]
+     |                                              ^
+     |Unless class Writer is declared 'open', its extension in a separate file should be enabled
+     |by adding the import clause 'import scala.language.adhocExtensions'
+     |or by setting the compiler option -language:adhocExtensions.
+   ```
+
+### Motivation
+
+When writing a class, there are three possible expectations of extensibility:
+
+- The class is intended to allow extensions. This means one should expect
+a carefully worked out and documented extension contract for the class.
+
+- Extensions of the class are forbidden, for instance to make correctness or security guarantees.
+
+- There is no firm decision either way. The class is not _a priori_ intended for extensions, but if others find it useful to extend on an _ad-hoc_ basis, let them go ahead. However, they are on their own in this case. There is no documented extension contract, and future versions of the class might break the extensions (by rearranging internal call patterns, for instance).
+
+The three cases are clearly distinguished by using `open` for (1), `final` for (2) and no modifier for (3).
+
+It is good practice to avoid _ad-hoc_ extensions in a code base, since they tend to lead to fragile systems that are hard to evolve. But there
+are still some situations where these extensions are useful: for instance,
+to mock classes in tests, or to apply temporary patches that add features or fix bugs in library classes. That's why _ad-hoc_ extensions are permitted, but only if there is an explicit opt-in via a language feature import.
+
+### Details
+
+ - `open` is a soft modifier. It is treated as a normal identifier
+   unless it is in modifier position.
+ - An `open` class cannot be `final` or `sealed`.
+ - Traits or `abstract` classes are always `open`, so `open` is redundant for them.
+
+### Relatinship with `sealed`
+
+A class that is neither `abstract` nor `open` is similar to a `sealed` class`: it can still be extended, but only in the same compilation unit. The difference is what happens if an extension of the class is attempted in a different compilation unit. For a `sealed` class, this is an error, whereas for a simple non-open class, this is still permitted provided the `adhocExtensions` feature is enabled, and gives a warning otherwise.
+
+### Migration
+
+`open` is a new modifier in Scala 3. To allow cross compilation between Scala 2.13 and Scala 3.0 without warnings, the feature warning for ad-hoc extensions is produced only under `-strict`. It will be produced by default from Scala 3.1 on.

docs/sidebar.yml

@@ -93,6 +93,8 @@ sidebar:
               url: docs/reference/other-new-features/export.html
             - title: Opaque Type Aliases
               url: docs/reference/other-new-features/opaques.html
+            - title: Open Classes
+              url: docs/reference/other-new-features/open-classes.html
             - title: Parameter Untupling
               url: docs/reference/other-new-features/parameter-untupling.html
             - title: Kind Polymorphism