Better compiler entry points

- Document the entry points
- It is now possible to set a custom reporter without using a custom
  context
- Use `null` for optional arguments to make it easier to run the
  compiler using reflection or from Java.
- DPDirectCompiler does not use a custom context anymore

1 files changed, 48 insertions, 10 deletions

diff --git a/src/dotty/tools/dotc/Driver.scala b/src/dotty/tools/dotc/Driver.scala
index 57fa4a052..7f22fc774 100644
--- a/src/dotty/tools/dotc/Driver.scala
+++ b/src/dotty/tools/dotc/Driver.scala
@@ -40,19 +40,57 @@ abstract class Driver extends DotClass {
     (fileNames, ctx)
   }
 
-  def process(args: Array[String], rootCtx: Context): Reporter = {
-    val (fileNames, ctx) = setup(args, rootCtx)
-    doCompile(newCompiler(), fileNames)(ctx)
-  }
 
-  def process(args: Array[String], callback: CompilerCallback): Reporter = {
-    process(args, initCtx.setCompilerCallback(callback))
+  /** Principal entry point to the compiler.
+   *  Creates a new compiler instance and run it with arguments `args`.
+   *
+   *  The optional arguments of this method all have `null` as their default
+   *  value, this makes it easier to call this method by reflection or from Java.
+   *
+   *  @param args       Arguments to pass to the compiler.
+   *  @param reporter   Used to log errors, warnings, and info messages.
+   *                    The default reporter is used if this is `null`.
+   *  @param callback   Used to execute custom code during the compilation
+   *                    process. No callbacks will be executed if this is `null`.
+   *  @return           The `Reporter` used. Use `Reporter#hasErrors` to check
+   *                    if compilation succeeded.
+   */
+  final def process(args: Array[String], reporter: Reporter = null,
+    callback: CompilerCallback = null): Reporter = {
+    val ctx = initCtx.fresh
+    if (reporter != null)
+      ctx.setReporter(reporter)
+    if (callback != null)
+      ctx.setCompilerCallback(callback)
+    process(args, ctx)
   }
 
-  // We overload `process` instead of using a default argument so that we
-  // can easily call this method using reflection from `RawCompiler` in sbt.
-  def process(args: Array[String]): Reporter = {
-    process(args, initCtx)
+  /** Entry point to the compiler with no optional arguments.
+   *
+   *  This overload is provided for compatibility reasons: the
+   *  `RawCompiler` of sbt expects this method to exist and calls
+   *  it using reflection. Keeping it means that we can change
+   *  the other overloads without worrying about breaking compatibility
+   *  with sbt.
+   */
+  final def process(args: Array[String]): Reporter =
+    process(args, null, null)
+
+  /** Entry point to the compiler using a custom `Context`.
+   *
+   *  In most cases, you do not need a custom `Context` and should
+   *  instead use one of the other overloads of `process`. However,
+   *  the other overloads cannot be overriden, instead you
+   *  should override this one which they call internally.
+   *
+   *  @param args       Arguments to pass to the compiler.
+   *  @param rootCtx    The root Context to use.
+   *  @return           The `Reporter` used. Use `Reporter#hasErrors` to check
+   *                    if compilation succeeded.
+   */
+  def process(args: Array[String], rootCtx: Context): Reporter = {
+    val (fileNames, ctx) = setup(args, rootCtx)
+    doCompile(newCompiler(), fileNames)(ctx)
   }
 
   def main(args: Array[String]): Unit = {