Deprecate NonLocalReturns API

Change the recommendation in the warning about non-local returns accordingly.

Still to do: A PR against scala/scala that deprecates scala.util.control.Breaks.

Author: odersky

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

@@ -97,7 +97,7 @@ class NonLocalReturns extends MiniPhase {
   override def transformReturn(tree: Return)(using Context): Tree =
     if isNonLocalReturn(tree) then
       report.gradualErrorOrMigrationWarning(
-          em"Non local returns are no longer supported; use scala.util.control.NonLocalReturns instead",
+          em"Non local returns are no longer supported; use `boundary` and `break` in `scala.util` instead",
           tree.srcPos,
           warnFrom = `3.2`,
           errorFrom = future)

library/src/scala/util/control/NonLocalReturns.scala

@@ -7,8 +7,18 @@ package scala.util.control
  *     import scala.util.control.NonLocalReturns.*
  *
  *     returning { ... throwReturn(x) ... }
+ *
+ *  This API has been deprecated. Its functionality is better served by
+ *
+ *   - `scala.util.boundary` in place of `returning`
+ *   - `scala.util.break` in place of `throwReturn`
+ *
+ *  The new abstractions work with plain `RuntimeExceptions` and are more
+ *  performant, since returns within the scope of the same method can be
+ *  rewritten by the compiler to jumps.
  */
 object NonLocalReturns {
+  @deprecated("Use scala.util.boundary.Break instead", "3.3")
   class ReturnThrowable[T] extends ControlThrowable {
     private var myResult: T = _
     def throwReturn(result: T): Nothing = {
@@ -19,10 +29,12 @@ object NonLocalReturns {
   }
 
   /** Performs a nonlocal return by throwing an exception. */
+  @deprecated("Use scala.util.break and scala.util.boundary instead", "3.3")
   def throwReturn[T](result: T)(using returner: ReturnThrowable[? >: T]): Nothing =
     returner.throwReturn(result)
 
   /** Enable nonlocal returns in `op`. */
+  @deprecated("Use scala.util.boundary and scala.util.break instead", "3.3")
   def returning[T](op: ReturnThrowable[T] ?=> T): T = {
     val returner = new ReturnThrowable[T]
     try op(using returner)