Backport "Sync with the stable documentation branch" to LTS

docs/_docs/reference/dropped-features/nonlocal-returns.md

@@ -9,21 +9,17 @@ Returning from nested anonymous functions has been deprecated, and will produce
 
 Nonlocal returns are implemented by throwing and catching `scala.runtime.NonLocalReturnException`-s. This is rarely what is intended by the programmer. It can be problematic because of the hidden performance cost of throwing and catching exceptions. Furthermore, it is a leaky implementation: a catch-all exception handler can intercept a `NonLocalReturnException`.
 
-A drop-in library replacement is provided in [`scala.util.control.NonLocalReturns`](https://scala-lang.org/api/3.x/scala/util/control/NonLocalReturns$.html). Example:
+A better alternative to nonlocal returns and also the `scala.util.control.Breaks` API is provided by [`scala.util.boundary` and `boundary.break`](http://dotty.epfl.ch/api/scala/util/boundary$.html).
 
-```scala
-import scala.util.control.NonLocalReturns.*
-
-extension [T](xs: List[T])
-  def has(elem: T): Boolean = returning {
-    for x <- xs do
-      if x == elem then throwReturn(true)
-    false
-  }
+Example:
 
-@main def test(): Unit =
-  val xs = List(1, 2, 3, 4, 5)
-  assert(xs.has(2) == xs.contains(2))
+```scala
+import scala.util.boundary, boundary.break
+def firstIndex[T](xs: List[T], elem: T): Int =
+  boundary:
+    for (x, i) <- xs.zipWithIndex do
+      if x == elem then break(i)
+    -1
 ```
 
 Note: compiler produces deprecation error on nonlocal returns only with `-source:future` option.

docs/sidebar.yml

@@ -92,7 +92,6 @@ subsection:
           - page: reference/changed-features/operators.md
           - page: reference/changed-features/wildcards.md
           - page: reference/changed-features/imports.md
-          - page: reference/changed-features/type-checking.md
           - page: reference/changed-features/type-inference.md
           - page: reference/changed-features/implicit-resolution.md
           - page: reference/changed-features/implicit-conversions.md

project/resources/referenceReplacements/sidebar.yml

@@ -88,7 +88,6 @@ subsection:
       - page: reference/changed-features/operators.md
       - page: reference/changed-features/wildcards.md
       - page: reference/changed-features/imports.md
-      - page: reference/changed-features/type-checking.md
       - page: reference/changed-features/type-inference.md
       - page: reference/changed-features/implicit-resolution.md
       - page: reference/changed-features/implicit-conversions.md

project/scripts/expected-links/reference-expected-links.txt

@@ -18,7 +18,6 @@
 ./changed-features/pattern-matching.html
 ./changed-features/structural-types-spec.html
 ./changed-features/structural-types.html
-./changed-features/type-checking.html
 ./changed-features/type-inference.html
 ./changed-features/vararg-splices.html
 ./changed-features/wildcards.html