Better documentation of main classes

5 files changed, 12 insertions, 3 deletions

diff --git a/src/dotty/tools/dotc/Bench.scala b/src/dotty/tools/dotc/Bench.scala
index 2fc38d78c..56b6dabbe 100644
--- a/src/dotty/tools/dotc/Bench.scala
+++ b/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
diff --git a/src/dotty/tools/dotc/Compiler.scala b/src/dotty/tools/dotc/Compiler.scala
index 62507d11a..fe48ac30e 100644
--- a/src/dotty/tools/dotc/Compiler.scala
+++ b/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:
diff --git a/src/dotty/tools/dotc/Main.scala b/src/dotty/tools/dotc/Main.scala
index 6c473d8bb..a6844fbbc 100644
--- a/src/dotty/tools/dotc/Main.scala
+++ b/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
 }
diff --git a/src/dotty/tools/dotc/Resident.scala b/src/dotty/tools/dotc/Resident.scala
index e1b62e4d0..56f6684d0 100644
--- a/src/dotty/tools/dotc/Resident.scala
+++ b/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>
diff --git a/src/dotty/tools/dotc/Run.scala b/src/dotty/tools/dotc/Run.scala
index ee808323a..7a0e555e4 100644
--- a/src/dotty/tools/dotc/Run.scala
+++ b/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)