Change @experimental spec

Author: nicolasstucki

compiler/src/dotty/tools/dotc/config/Feature.scala

@@ -106,15 +106,13 @@ object Feature:
   def checkExperimentalDef(sym: Symbol, srcPos: SrcPos)(using Context) =
     if !isExperimentalEnabled then
       val symMsg =
-        if sym eq defn.ExperimentalAnnot then
-          i"use of @experimental is experimental"
-        else if sym.hasAnnotation(defn.ExperimentalAnnot) then
+        if sym.hasAnnotation(defn.ExperimentalAnnot) then
           i"$sym is marked @experimental"
         else if sym.owner.hasAnnotation(defn.ExperimentalAnnot) then
           i"${sym.owner} is marked @experimental"
         else
           i"$sym inherits @experimental"
-      report.error(s"$symMsg and therefore may only be used with a nightly or snapshot version of the compiler", srcPos)
+      report.error(s"$symMsg and therefore may only be used in an experimental scope.", srcPos)
 
   /** Check that experimental compiler options are only set for snapshot or nightly compiler versions. */
   def checkExperimentalSettings(using Context): Unit =

compiler/src/dotty/tools/dotc/transform/SymUtils.scala

@@ -263,11 +263,13 @@ object SymUtils:
 
     /** Is symbol declared or inherits @experimental? */
     def isExperimental(using Context): Boolean =
-      // TODO should be add `@experimental` to `class experimental` in PostTyper?
-      self.eq(defn.ExperimentalAnnot)
-      || self.hasAnnotation(defn.ExperimentalAnnot)
+      self.hasAnnotation(defn.ExperimentalAnnot)
       || (self.maybeOwner.isClass && self.owner.hasAnnotation(defn.ExperimentalAnnot))
 
+    def isInExperimentalScope(using Context): Boolean =
+      self.hasAnnotation(defn.ExperimentalAnnot)
+      || (!self.is(Package) && self.owner.isInExperimentalScope)
+
     /** The declared self type of this class, as seen from `site`, stripping
     *  all refinements for opaque types.
     */

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

@@ -948,12 +948,7 @@ object RefChecks {
         report.deprecationWarning(s"${sym.showLocated} is deprecated${since}${msg}", pos)
 
   private def checkExperimental(sym: Symbol, pos: SrcPos)(using Context): Unit =
-    if sym.isExperimental
-    && !sym.isConstructor // already reported on the class
-    && !ctx.owner.isExperimental // already reported on the @experimental of the owner
-    && !sym.is(ModuleClass) // already reported on the module
-    && (sym.span.exists || sym != defn.ExperimentalAnnot) // already reported on inferred annotations
-    then
+    if sym.isExperimental && !ctx.owner.isInExperimentalScope then
       Feature.checkExperimentalDef(sym, pos)
 
   private def checkExperimentalSignature(sym: Symbol, pos: SrcPos)(using Context): Unit =
@@ -963,12 +958,14 @@ object RefChecks {
           Feature.checkExperimentalDef(tp.typeSymbol, pos)
         else
           traverseChildren(tp)
-    if !sym.owner.isExperimental && !pos.span.isSynthetic then // avoid double errors
+
+    if !sym.isInExperimentalScope then
       checker.traverse(sym.info)
 
   private def checkExperimentalAnnots(sym: Symbol)(using Context): Unit =
-    for annot <- sym.annotations if annot.symbol.isExperimental && annot.tree.span.exists do
-      Feature.checkExperimentalDef(annot.symbol, annot.tree)
+    if !sym.isExperimental then
+      for annot <- sym.annotations if annot.symbol.isExperimental && annot.tree.span.exists do
+        Feature.checkExperimentalDef(annot.symbol, annot.tree)
 
   /** If @migration is present (indicating that the symbol has changed semantics between versions),
    *  emit a warning.
@@ -1338,7 +1335,6 @@ class RefChecks extends MiniPhase { thisPhase =>
   }
 
   override def transformTypeDef(tree: TypeDef)(using Context): TypeDef = {
-    checkExperimental(tree.symbol, tree.srcPos)
     checkExperimentalAnnots(tree.symbol)
     tree
   }

docs/docs/reference/other-new-features/experimental-defs.md

@@ -0,0 +1,302 @@
+---
+layout: doc-page
+title: "Experimental definitions"
+---
+
+## Experimental definitions
+
+The `@experimental` annotation allows the definition of an API that is not guaranteed backward binary or source compatibility.
+This annotation can be placed on term or type definitions.
+
+### References to experimental definitions
+
+Experimental definitions can only be referenced in an experimental scope. Experimental scopes are defined as follows.
+
+(1) The RHS of an experimental `def`, `val`, `var`, `given` or `type` is an experimental scope.
+
+<details>
+<summary>Examples</summary>
+
+```scala
+import scala.annotation.experimental
+
+@experimental
+def x = ()
+
+def d1 = x // error: value x is marked @experimental and therefore ...
+@experimental def d2 = x
+
+val v1 = x // error: value x is marked @experimental and therefore ...
+@experimental val v2 = x
+
+var vr1 = x // error: value x is marked @experimental and therefore ...
+@experimental var vr2 = x
+
+lazy val lv1 = x // error: value x is marked @experimental and therefore ...
+@experimental lazy val lv2 = x
+```
+
+```scala
+import scala.annotation.experimental
+
+@experimental
+val x = ()
+
+@experimental
+def f() = ()
+
+@experimental
+object X:
+  def fx() = 1
+
+def test1: Unit =
+  f() // error: def f is marked @experimental and therefore ...
+  x // error: value x is marked @experimental and therefore ...
+  X.fx() // error: object X is marked @experimental and therefore ...
+  import X.fx
+  fx() // error: object X is marked @experimental and therefore ...
+
+@experimental
+def test2: Unit =
+  // references to f, x and X are ok because `test2` is experimental
+  f()
+  x
+  X.fx()
+  import X.fx
+  fx()
+```
+
+```scala
+import scala.annotation.experimental
+
+@experimental type E
+
+type A = E // error
+@experimental type B = E
+```
+
+```scala
+import scala.annotation.experimental
+
+@experimental class A
+@experimental type X
+@experimental type Y = Int
+@experimental opaque type Z = Int
+
+def test: Unit =
+  new A // error: class A is marked @experimental and therefore ...
+  val i0: A = ??? // error: class A is marked @experimental and therefore ...
+  val i1: X = ??? // error: type X is marked @experimental and therefore ...
+  val i2: Y = ??? // error: type Y is marked @experimental and therefore ...
+  val i2: Z = ??? // error: type Y is marked @experimental and therefore ...
+  ()
+```
+
+```scala
+@experimental
+trait ExpSAM {
+  def foo(x: Int): Int
+}
+def bar(f: ExpSAM): Unit = {} // error: error form rule 2
+
+def test: Unit =
+  bar(x => x) // error: reference to experimental SAM
+  ()
+```
+
+</details>
+
+(2.) The signatures of an experimental `def`, `val`, `var`, `given` and `type`, or constructors of `class` and `trait` are experimental scopes.
+
+<details>
+<summary>Examples</summary>
+
+```scala
+import scala.annotation.experimental
+
+@experimental def x = 2
+@experimental class A
+@experimental type X
+@experimental type Y = Int
+@experimental opaque type Z = Int
+
+def test1(
+  p1: A, // error: class A is marked @experimental and therefore ...
+  p2: List[A], // error: class A is marked @experimental and therefore ...
+  p3: X, // error: type X is marked @experimental and therefore ...
+  p4: Y, // error: type Y is marked @experimental and therefore ...
+  p5: Z, // error: type Z is marked @experimental and therefore ...
+  p6: Any = x // error: def x is marked @experimental and therefore ...
+): A = ??? // error: class A is marked @experimental and therefore ...
+
+@experimental def test2(
+  p1: A,
+  p2: List[A],
+  p3: X,
+  p4: Y,
+  p5: Z,
+  p6: Any = x
+): A = ???
+
+class Test1(
+  p1: A, // error
+  p2: List[A], // error
+  p3: X, // error
+  p4: Y, // error
+  p5: Z, // error
+  p6: Any = x // error
+) {}
+
+@experimental class Test2(
+  p1: A,
+  p2: List[A],
+  p3: X,
+  p4: Y,
+  p5: Z,
+  p6: Any = x
+) {}
+
+trait Test1(
+  p1: A, // error
+  p2: List[A], // error
+  p3: X, // error
+  p4: Y, // error
+  p5: Z, // error
+  p6: Any = x // error
+) {}
+
+@experimental trait Test2(
+  p1: A,
+  p2: List[A],
+  p3: X,
+  p4: Y,
+  p5: Z,
+  p6: Any = x
+) {}
+```
+
+</details>
+
+(3.) The extension clause of an experimental `class`, `trait`, `object` are experimental scopes.
+
+<details>
+<summary>Examples</summary>
+
+```scala
+import scala.annotation.experimental
+
+@experimental def x = 2
+
+@experimental class A1(x: Any)
+class A2(x: Any)
+
+
+@experimental class B1 extends A1(1)
+class B2 extends A1(1) // error: class A1 is marked @experimental and therefore marked @experimental and therefore ...
+
+@experimental class C1 extends A2(x)
+class C2 extends A2(x) // error def x is marked @experimental and therefore
+```
+
+</details>
+
+(4.) Members of an experimental `class`, `trait` or `object` are in experimental scopes.
+
+<details>
+<summary>Examples</summary>
+
+```scala
+import scala.annotation.experimental
+
+@experimental def x = 2
+
+@experimental class A {
+  def f = x // ok because A is experimental
+}
+
+@experimental class B {
+  def f = x // ok because A is experimental
+}
+
+@experimental object C {
+  def f = x // ok because A is experimental
+}
+
+@experimental class D {
+  def f = {
+    object B {
+      x // ok because A is experimental
+    }
+  }
+}
+```
+
+</details>
+
+(5.) Annotations of an experimental definition are in experimental scopes.
+
+<details>
+<summary>Examples</summary>
+
+```scala
+import scala.annotation.experimental
+
+@experimental class myExperimentalAnnot extends scala.annotation.Annotation
+
+@myExperimentalAnnot // error
+def test: Unit = ()
+
+@experimental
+@myExperimentalAnnot
+def test: Unit = ()
+```
+
+</details>
+
+(6.) Any code compiled using a _Nightly_ or _Snapshot_ version of the compiler is considered to be in an experimental scope.
+Can use the `-Yno-experimental` compiler flag to disable it and run as a proper release.
+
+In any other situation, a reference to an experimental definition will cause a compilation error.
+
+> Question: Should we disallow `@experimental def main(...)`?
+
+### Experimental inheritance
+
+All subclasses of an experimental `class` or `trait` must be marked as `@experimental` even if they are in an experimental scope.
+Anonymous classes and SAMs of experimental classes are considered experimental.
+
+We require explicit annotations to make sure we do not have completion or cycles issues with nested classes. This restriction could be relaxed in the future.
+
+### Experimental overriding
+
+For an overriding member `M` and overridden member `O`, if `O` is non-experimental then `M` must be non-experimental.
+
+This makes sure that we cannot have accidental binary incompatibilities such as the following change.
+```diff
+class A:
+  def f: Any = 1
+class B extends A:
+-  @experimental def f: Int = 2
+```
+### Test frameworks
+
+Tests can be defined as experimental. Tests frameworks can execute tests using reflection even if they are in an experimental class, object or method.
+
+Test that touch experimental APIs can be written as follows
+
+```scala
+import scala.annotation.experimental
+
+@experimental def x = 2
+
+class MyTests {
+  /*@Test*/ def test1 = x // error
+  @experimental /*@Test*/ def test2 = x
+}
+
+@experimental
+class MyExperimentalTests {
+  /*@Test*/ def test1 = x
+  /*@Test*/ def test2 = x
+}
+```

docs/sidebar.yml

@@ -67,6 +67,7 @@ sidebar:
           - page: docs/reference/other-new-features/explicit-nulls.md
           - page: docs/reference/other-new-features/safe-initialization.md
           - page: docs/reference/other-new-features/type-test.md
+          - page: docs/reference/other-new-features/experimental-defs.md
       - title: Other Changed Features
         subsection:
           - page: docs/reference/changed-features/numeric-literals.md