refactor: improve output of -Xshow-phases

compiler/src/dotty/tools/backend/jvm/CollectSuperCalls.scala

@@ -20,7 +20,9 @@ import dotty.tools.dotc.transform.MegaPhase.MiniPhase
 class CollectSuperCalls extends MiniPhase {
   import tpd._
 
-  def phaseName: String = "collectSuperCalls"
+  override def phaseName: String = CollectSuperCalls.name
+
+  override def description: String = CollectSuperCalls.description
 
   override def transformSelect(tree: Select)(using Context): Tree = {
     tree.qualifier match {
@@ -40,3 +42,7 @@ class CollectSuperCalls extends MiniPhase {
     }
   }
 }
+
+object CollectSuperCalls:
+  val name: String = "collectSuperCalls"
+  val description: String = "find classes that are called with super"

compiler/src/dotty/tools/backend/jvm/GenBCode.scala

@@ -34,7 +34,10 @@ import StdNames._
 import dotty.tools.io._
 
 class GenBCode extends Phase {
-  def phaseName: String = GenBCode.name
+
+  override def phaseName: String = GenBCode.name
+
+  override def description: String = GenBCode.description
 
   private val superCallsMap = new MutableSymbolMap[Set[ClassSymbol]]
   def registerSuperCall(sym: Symbol, calls: ClassSymbol): Unit = {
@@ -106,6 +109,7 @@ class GenBCode extends Phase {
 
 object GenBCode {
   val name: String = "genBCode"
+  val description: String = "generate JVM bytecode"
 }
 
 class GenBCodePipeline(val int: DottyBackendInterface, val primitives: DottyPrimitives)(using Context) extends BCodeSyncAndTry {

compiler/src/dotty/tools/backend/sjs/GenSJSIR.scala

@@ -6,11 +6,18 @@ import Phases._
 
 /** Generates Scala.js IR files for the compilation unit. */
 class GenSJSIR extends Phase {
-  def phaseName: String = "genSJSIR"
+
+  override def phaseName: String = GenSJSIR.name
+
+  override def description: String = GenSJSIR.description
 
   override def isRunnable(using Context): Boolean =
     super.isRunnable && ctx.settings.scalajs.value
 
   def run(using Context): Unit =
     new JSCodeGen().run()
 }
+
+object GenSJSIR:
+  val name: String = "genSJSIR"
+  val description: String = "generate .sjsir files for Scala.js"

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

@@ -138,11 +138,32 @@ trait CliCommand:
   protected def yusageMessage(using settings: ConcreteSettings)(using SettingsState) =
     createUsageMsg("Possible private", shouldExplain = true, isPrivate)
 
-  protected def phasesMessage: String =
-    (new Compiler()).phases.map {
-      case List(single) => single.phaseName
-      case more => more.map(_.phaseName).mkString("{", ", ", "}")
-    }.mkString("\n")
+  /** Used for the formatted output of -Xshow-phases */
+  protected def phasesMessage(using ctx: Context): String =
+
+    val phases = new Compiler().phases
+    val nameLimit = 25 
+    val maxCol = ctx.settings.pageWidth.value
+    val maxName = phases.flatten.map(_.phaseName.length).max
+    val width = maxName.min(nameLimit)
+    val maxDesc = maxCol - (width + 6)
+    val fmt = s"%${width}.${width}s  %.${maxDesc}s%n"
+
+    val sb = new StringBuilder
+    sb ++= fmt.format("phase name", "description")
+    sb ++= fmt.format("----------", "-----------")
+
+    phases.foreach {
+      case List(single) =>
+        sb ++= fmt.format(single.phaseName, single.description)
+      case Nil => ()
+      case more =>
+        sb ++= fmt.format(s"{", "")
+        more.foreach { mini => sb ++= fmt.format(mini.phaseName, mini.description) }
+        sb ++= fmt.format(s"}", "")
+    }
+    sb.mkString
+
 
   /** Provide usage feedback on argument summary, assuming that all settings
    *  are already applied in context.

compiler/src/dotty/tools/dotc/parsing/ParserPhase.scala

@@ -15,6 +15,7 @@ import dotty.tools.unsupported
 class Parser extends Phase {
 
   override def phaseName: String = Parser.name
+  override def description: String = Parser.description
 
   // We run TreeChecker only after type checking
   override def isCheckable: Boolean = false
@@ -58,4 +59,5 @@ class Parser extends Phase {
 
 object Parser{
   val name: String = "parser"
+  val description: String = "scan and parse sources"
 }

compiler/src/dotty/tools/dotc/sbt/ExtractAPI.scala

@@ -43,7 +43,10 @@ import scala.util.chaining.*
  *  @see ExtractDependencies
  */
 class ExtractAPI extends Phase {
-  override def phaseName: String = "sbt-api"
+
+  override def phaseName: String = ExtractAPI.name
+
+  override def description: String = ExtractAPI.description
 
   override def isRunnable(using Context): Boolean = {
     def forceRun = ctx.settings.YdumpSbtInc.value || ctx.settings.YforceSbtPhases.value
@@ -87,6 +90,10 @@ class ExtractAPI extends Phase {
   }
 }
 
+object ExtractAPI:
+  val name: String = "sbt-api"
+  val description: String = "sends a representation of the API of classes to sbt"
+
 /** Extracts full (including private members) API representation out of Symbols and Types.
  *
  *  The exact representation used for each type is not important: the only thing

compiler/src/dotty/tools/dotc/sbt/ExtractDependencies.scala

@@ -49,7 +49,9 @@ import scala.collection.{Set, mutable}
 class ExtractDependencies extends Phase {
   import ExtractDependencies._
 
-  override def phaseName: String = "sbt-deps"
+  override def phaseName: String = ExtractDependencies.name
+
+  override def description: String = ExtractDependencies.description
 
   override def isRunnable(using Context): Boolean = {
     def forceRun = ctx.settings.YdumpSbtInc.value || ctx.settings.YforceSbtPhases.value
@@ -180,6 +182,9 @@ class ExtractDependencies extends Phase {
 }
 
 object ExtractDependencies {
+  val name: String = "sbt-deps"
+  val description: String = "sends information on classes' dependencies to sbt"
+
   def classNameAsString(sym: Symbol)(using Context): String =
     sym.fullName.stripModuleClassSuffix.toString
 

compiler/src/dotty/tools/dotc/semanticdb/ExtractSemanticDB.scala

@@ -36,6 +36,8 @@ class ExtractSemanticDB extends Phase:
 
   override val phaseName: String = ExtractSemanticDB.name
 
+  override val description: String = ExtractSemanticDB.description
+
   override def isRunnable(using Context) =
     super.isRunnable && ctx.settings.Xsemanticdb.value
 
@@ -461,6 +463,7 @@ object ExtractSemanticDB:
   import java.nio.file.Paths
 
   val name: String = "extractSemanticDB"
+  val description: String = "extract info into .semanticdb files"
 
   def write(
     source: SourceFile,

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

@@ -21,7 +21,9 @@ import scala.reflect.ClassTag
 class ArrayApply extends MiniPhase {
   import tpd._
 
-  override def phaseName: String = "arrayApply"
+  override def phaseName: String = ArrayApply.name
+
+  override def description: String = ArrayApply.description
 
   override def transformApply(tree: tpd.Apply)(using Context): tpd.Tree =
     if isArrayModuleApply(tree.symbol) then
@@ -71,3 +73,7 @@ class ArrayApply extends MiniPhase {
     }
   }
 }
+
+object ArrayApply:
+  val name: String = "arrayApply"
+  val description: String = "optimize `scala.Array.apply`"

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

@@ -22,7 +22,9 @@ import scala.collection.immutable.::
 class ArrayConstructors extends MiniPhase {
   import ast.tpd._
 
-  override def phaseName: String = "arrayConstructors"
+  override def phaseName: String = ArrayConstructors.name
+
+  override def description: String = ArrayConstructors.description
 
   override def transformApply(tree: tpd.Apply)(using Context): tpd.Tree = {
     def expand(elemType: Type, dims: List[Tree]) =
@@ -49,3 +51,7 @@ class ArrayConstructors extends MiniPhase {
     else tree
   }
 }
+
+object ArrayConstructors:
+  val name: String = "arrayConstructors"
+  val description: String = "intercept creation of (non-generic) arrays and intrinsify"

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

@@ -33,7 +33,9 @@ import ast.TreeTypeMap
 class BetaReduce extends MiniPhase:
   import ast.tpd._
 
-  def phaseName: String = "betaReduce"
+  override def phaseName: String = BetaReduce.name
+
+  override def description: String = BetaReduce.description
 
   override def transformApply(app: Apply)(using Context): Tree = app.fun match
     case Select(fn, nme.apply) if defn.isFunctionType(fn.tpe) =>
@@ -47,6 +49,9 @@ class BetaReduce extends MiniPhase:
 object BetaReduce:
   import ast.tpd._
 
+  val name: String = "betaReduce"
+  val description: String = "reduce closure applications"
+
   /** Beta-reduces a call to `fn` with arguments `argSyms` or returns `tree` */
   def apply(original: Tree, fn: Tree, args: List[Tree])(using Context): Tree =
     fn match

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

@@ -22,8 +22,9 @@ class CapturedVars extends MiniPhase with IdentityDenotTransformer:
   thisPhase =>
   import ast.tpd._
 
-  /** the following two members override abstract members in Transform */
-  val phaseName: String = "capturedVars"
+  override def phaseName: String = CapturedVars.name
+
+  override def description: String = CapturedVars.description
 
   override def runsAfterGroupsOf: Set[String] = Set(LiftTry.name)
     // lifting tries changes what variables are considered to be captured
@@ -167,3 +168,7 @@ class CapturedVars extends MiniPhase with IdentityDenotTransformer:
       case _ =>
         tree
     recur(tree.lhs)
+
+object CapturedVars:
+  val name: String = "capturedVars"
+  val description: String = "represent vars captured by closures as heap objects"

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

@@ -12,6 +12,7 @@ import annotation.threadUnsafe
 
 object CheckLoopingImplicits:
   val name: String = "checkLoopingImplicits"
+  val description: String = "check that implicit defs do not call themselves in an infinite loop"
 
 /** Checks that implicit defs do not call themselves in an infinite loop */
 class CheckLoopingImplicits extends MiniPhase:
@@ -20,6 +21,8 @@ class CheckLoopingImplicits extends MiniPhase:
 
   override def phaseName: String = CheckLoopingImplicits.name
 
+  override def description: String = CheckLoopingImplicits.description
+
   override def transformValDef(mdef: ValDef)(using Context): Tree = 
     transform(mdef)
 

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

@@ -12,6 +12,7 @@ import annotation.threadUnsafe
 
 object CheckNoSuperThis:
   val name: String = "checkNoSuperThis"
+  val description: String = "check that supercalls don't contain references to This"
 
 /** Checks that super and this calls do not pass `this` as (part of) an argument. */
 class CheckNoSuperThis extends MiniPhase:
@@ -20,6 +21,8 @@ class CheckNoSuperThis extends MiniPhase:
 
   override def phaseName: String = CheckNoSuperThis.name
 
+  override def description: String = CheckNoSuperThis.description
+
   override def runsAfterGroupsOf: Set[String] = Set(Constructors.name)
 
   override def transformDefDef(mdef: DefDef)(using Context): DefDef =
@@ -47,4 +50,4 @@ class CheckNoSuperThis extends MiniPhase:
         case _ =>
     mdef
 
-end CheckNoSuperThis
+end CheckNoSuperThis

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

@@ -29,7 +29,9 @@ import Decorators._
 class CheckReentrant extends MiniPhase {
   import ast.tpd._
 
-  override def phaseName: String = "checkReentrant"
+  override def phaseName: String = CheckReentrant.name
+
+  override def description: String = CheckReentrant.description
 
   private var shared: Set[Symbol] = Set()
   private var seen: Set[ClassSymbol] = Set()
@@ -84,3 +86,7 @@ class CheckReentrant extends MiniPhase {
     tree
   }
 }
+
+object CheckReentrant:
+  val name: String = "checkReentrant"
+  val description: String = "check no data races involving global vars"

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

@@ -29,6 +29,8 @@ class CheckStatic extends MiniPhase {
 
   override def phaseName: String = CheckStatic.name
 
+  override def description: String = CheckStatic.description
+
   override def transformTemplate(tree: tpd.Template)(using Context): tpd.Tree = {
     val defns = tree.body.collect{case t: ValOrDefDef => t}
     var hadNonStaticField = false
@@ -63,4 +65,5 @@ class CheckStatic extends MiniPhase {
 
 object CheckStatic {
   val name: String = "checkStatic"
+  val description: String = "check restrictions that apply to @static members"
 }

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

@@ -29,7 +29,10 @@ import dotty.tools.backend.jvm.GenBCode
  *   -Xmain-class
  */
 class CollectEntryPoints extends MiniPhase:
-  def phaseName: String = "Collect entry points"
+
+  override def phaseName: String = CollectEntryPoints.name
+
+  override def description: String = CollectEntryPoints.description
 
   override def isRunnable(using Context): Boolean =
     def forceRun = ctx.settings.XmainClass.isDefault && ctx.settings.outputDir.value.isInstanceOf[JarArchive]
@@ -52,3 +55,7 @@ class CollectEntryPoints extends MiniPhase:
       case _ =>
     }
   }
+
+object CollectEntryPoints:
+  val name: String = "Collect entry points"
+  val description: String = "collect all entry points and save them in the context"

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

@@ -13,6 +13,7 @@ import java.util.IdentityHashMap
 
 object CollectNullableFields {
   val name: String = "collectNullableFields"
+  val description: String = "collect fields that can be nulled out after use in lazy initialization"
 }
 
 /** Collect fields that can be nulled out after use in lazy initialization.
@@ -43,6 +44,8 @@ class CollectNullableFields extends MiniPhase {
 
   override def phaseName: String = CollectNullableFields.name
 
+  override def description: String = CollectNullableFields.description
+
   /** Running after `ElimByName` to see by names as nullable types. */
   override def runsAfter: Set[String] = Set(ElimByName.name)
 

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

@@ -20,6 +20,7 @@ import annotation.threadUnsafe
 
 object CompleteJavaEnums {
   val name: String = "completeJavaEnums"
+  val description: String = "fill in constructors for Java enums"
 
   private val nameParamName: TermName = "_$name".toTermName
   private val ordinalParamName: TermName = "_$ordinal".toTermName
@@ -35,6 +36,8 @@ class CompleteJavaEnums extends MiniPhase with InfoTransformer { thisPhase =>
 
   override def phaseName: String = CompleteJavaEnums.name
 
+  override def description: String = CompleteJavaEnums.description
+
   override def relaxedTypingInGroup: Boolean = true
     // Because it adds additional parameters to some constructors
 

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

@@ -21,6 +21,7 @@ import collection.mutable
 
 object Constructors {
   val name: String = "constructors"
+  val description: String = "collect initialization code in primary constructors"
 }
 
 /** This transform
@@ -33,6 +34,9 @@ class Constructors extends MiniPhase with IdentityDenotTransformer { thisPhase =
   import tpd._
 
   override def phaseName: String = Constructors.name
+
+  override def description: String = Constructors.description
+
   override def runsAfter: Set[String] = Set(HoistSuperArgs.name)
   override def runsAfterGroupsOf: Set[String] = Set(Memoize.name)
     // Memoized needs to be finished because we depend on the ownerchain after Memoize