Improve error message when using experimental definitions (#19782)

When an experimental definition is used, the error message shows how to
enable the experimental mode. Previously we only did this for
experimental language features, but not for experimental definitions.

Author: nicolasstucki

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

@@ -135,26 +135,25 @@ object Feature:
     if !isExperimentalEnabled then
       report.error(
         em"""Experimental $which may only be used under experimental mode:
-            |  1. In a definition marked as @experimental
-            |  2. Compiling with the -experimental compiler flag
-            |  3. With a nightly or snapshot version of the compiler$note
+            |  1. in a definition marked as @experimental, or
+            |  2. compiling with the -experimental compiler flag, or
+            |  3. with a nightly or snapshot version of the compiler.$note
           """, srcPos)
 
   private def ccException(sym: Symbol)(using Context): Boolean =
     ccEnabled && defn.ccExperimental.contains(sym)
 
   def checkExperimentalDef(sym: Symbol, srcPos: SrcPos)(using Context) =
-    if !isExperimentalEnabled then
-      val experimentalSym =
-        if sym.hasAnnotation(defn.ExperimentalAnnot) then sym
-        else if sym.owner.hasAnnotation(defn.ExperimentalAnnot) then sym.owner
-        else NoSymbol
-      if !ccException(experimentalSym) then
-        val symMsg =
-          if experimentalSym.exists
-          then i"$experimentalSym is marked @experimental"
-          else i"$sym inherits @experimental"
-        report.error(em"$symMsg and therefore may only be used in an experimental scope.", srcPos)
+    val experimentalSym =
+      if sym.hasAnnotation(defn.ExperimentalAnnot) then sym
+      else if sym.owner.hasAnnotation(defn.ExperimentalAnnot) then sym.owner
+      else NoSymbol
+    if !ccException(experimentalSym) then
+      val note =
+        if experimentalSym.exists
+        then i"$experimentalSym is marked @experimental"
+        else i"$sym inherits @experimental"
+      checkExperimentalFeature("definition", srcPos, s"\n\n$note")
 
   /** Check that experimental compiler options are only set for snapshot or nightly compiler versions. */
   def checkExperimentalSettings(using Context): Unit =

tests/neg/use-experimental-def.check

@@ -0,0 +1,10 @@
+-- Error: tests/neg/use-experimental-def.scala:7:15 --------------------------------------------------------------------
+7 |def bar: Int = foo // error
+  |               ^^^
+  |               Experimental definition may only be used under experimental mode:
+  |                 1. in a definition marked as @experimental, or
+  |                 2. compiling with the -experimental compiler flag, or
+  |                 3. with a nightly or snapshot version of the compiler.
+  |
+  |               method foo is marked @experimental
+  |                         

tests/neg/use-experimental-def.scala

@@ -0,0 +1,7 @@
+//> using options -Yno-experimental
+
+import scala.annotation.experimental
+
+@experimental def foo: Int = 1
+
+def bar: Int = foo // error