Better documentation of main classes

Author: odersky

src/dotty/tools/dotc/Bench.scala

@@ -8,6 +8,10 @@ package dotc
 import core.Contexts.Context
 import reporting.Reporter
 
+/** A main class for running compiler benchmarks. Can instantiate a given
+ *  number of compilers and run each (sequentially) a given number of times
+ *  on the same sources.
+ */
 object Bench extends Driver {
 
   @sharable private var numRuns = 1

src/dotty/tools/dotc/Compiler.scala

@@ -18,6 +18,9 @@ import core.Denotations.SingleDenotation
 import dotty.tools.backend.jvm.{LabelDefs, GenBCode}
 import dotty.tools.backend.sjs.GenSJSIR
 
+/** The central class of the dotc compiler. The job of a compiler is to create
+ *  runs, which process given `phases` in a given `rootContext`.
+ */
 class Compiler {
 
   /** Meta-ordering constraint:

src/dotty/tools/dotc/Main.scala

@@ -3,8 +3,7 @@ package dotc
 
 import core.Contexts.Context
 
-/* To do:
- */
+/** Main class of the `dotc` batch compiler. */
 object Main extends Driver {
   override def newCompiler(implicit ctx: Context): Compiler = new Compiler
 }

src/dotty/tools/dotc/Resident.scala

@@ -6,7 +6,9 @@ import reporting.Reporter
 import java.io.EOFException
 import scala.annotation.tailrec
 
-/** A compiler which stays resident between runs.
+/** A compiler which stays resident between runs. This is more of a PoC than
+ *  something that's expected to be used often
+ *
  *  Usage:
  *
  *  > scala dotty.tools.dotc.Resident <options> <initial files>

src/dotty/tools/dotc/Run.scala

@@ -13,6 +13,7 @@ import java.io.{BufferedWriter, OutputStreamWriter}
 import scala.reflect.io.VirtualFile
 import scala.util.control.NonFatal
 
+/** A compiler run. Exports various methods to compile source files */
 class Run(comp: Compiler)(implicit ctx: Context) {
 
   assert(comp.phases.last.last.id <= Periods.MaxPossiblePhaseId)