Backport "Drop Mode.PrintShowExceptions && add Mode docs" to LTS (#19149)

Backports #18298 to the LTS branch.

PR submitted by the release tooling.
[skip ci]

Author: Kordyjan

compiler/src/dotty/tools/dotc/core/Decorators.scala

@@ -279,7 +279,7 @@ object Decorators {
         catch
           case ex: CyclicReference => "... (caught cyclic reference) ..."
           case NonFatal(ex)
-          if !ctx.mode.is(Mode.PrintShowExceptions) && !ctx.settings.YshowPrintErrors.value =>
+          if !ctx.settings.YshowPrintErrors.value =>
             s"... (cannot display due to ${ex.className} ${ex.getMessage}) ..."
       case _ => String.valueOf(x).nn
 

compiler/src/dotty/tools/dotc/core/Mode.scala

@@ -1,6 +1,14 @@
 package dotty.tools.dotc.core
 
-/** A collection of mode bits that are part of a context */
+/** A collection of mode bits that are part of a context.
+ *
+ * What's the difference between a boolean setting and a Mode?
+ * A setting is usually valid for the entire compilation run, whereas a mode is context specific.
+ * Changing a setting in a context creates a new SettingsState in that context, which is a relatively big object.
+ * By comparison, a mode is just an Int.
+ * But, Mode bits are a scarce resource, so for low priority situations, just reset the state with a setting.
+ * Also, a setting is externally settable, while a mode isn't.
+ */
 case class Mode(val bits: Int) extends AnyVal {
   import Mode._
   def | (that: Mode): Mode = Mode(bits | that.bits)
@@ -98,9 +106,6 @@ object Mode {
   /** Read original positions when unpickling from TASTY */
   val ReadPositions: Mode = newMode(17, "ReadPositions")
 
-  /** Don't suppress exceptions thrown during show */
-  val PrintShowExceptions: Mode = newMode(18, "PrintShowExceptions")
-
   val PatternOrTypeBits: Mode = Pattern | Type
 
   /** We are elaborating the fully qualified name of a package clause.

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

@@ -153,13 +153,15 @@ class Pickler extends Phase {
       else
         super.runOn(units)
     if ctx.settings.YtestPickler.value then
-      val ctx2 = ctx.fresh.setSetting(ctx.settings.YreadComments, true)
+      val ctx2 = ctx.fresh
+        .setSetting(ctx.settings.YreadComments, true)
+        .setSetting(ctx.settings.YshowPrintErrors, true)
       testUnpickler(
         using ctx2
-            .setPeriod(Period(ctx.runId + 1, ctx.base.typerPhase.id))
-            .setReporter(new ThrowingReporter(ctx.reporter))
-            .addMode(Mode.ReadPositions)
-            .addMode(Mode.PrintShowExceptions))
+          .setPeriod(Period(ctx.runId + 1, ctx.base.typerPhase.id))
+          .setReporter(new ThrowingReporter(ctx.reporter))
+          .addMode(Mode.ReadPositions)
+      )
     result
   }