Deprecate ScalaThenJava, and improve the docs

Ref #235

internal/compiler-interface/src/main/java/xsbti/compile/CompileOrder.java

@@ -12,54 +12,58 @@
 package xsbti.compile;
 
 /**
- * Define the order in which Scala and Java compilation should happen.
+ * CompileOrder defines the order in which Scala and Java compilation
+ * are called within a single cycle of incremental compilation.
+ * The motivation for CompileOrder is a minor performance improvement
+ * we expect from skipping to parse Java sources.
  *
- * This compilation order matters when the sources to be compiled are both
- * Scala and Java sources, in which case the Zinc compiler needs a strategy
- * to deal with the compilation order. Therefore, this setting has no effect
- * if only Java or Scala sources are being compiled.
+ * In general, because incremental compilatation happens over the course
+ * of time as a series of direct and indirect invalidation and compilation,
+ * the ordering here is more of a implementation detail rather than an
+ * invariant you can rely on to enforce visibility etc.
  */
 public enum CompileOrder {
-	/**
-	 * Allow Scala sources to depend on Java sources and allow Java sources to
-	 * depend on Scala sources.
-     *
-	 * Under this mode, both Java and Scala sources can depend on each other.
-	 * Java sources are also passed to the Scala compiler, which parses them,
-	 * populates the symbol table and lifts them to Scala trees without
-	 * generating class files for the Java trees.
-	 *
-	 * Then, the incremental compiler will add the generated Scala class files
-	 * to the classpath of the Java compiler so that Java sources can depend
-	 * on Scala sources.
-     *
-	 * For more information on the way Mixed and ScalaThenJava mode behave,
-	 * see <a href="https://github.com/sbt/zinc/issues/235">this link</a>.
-	 */
-	Mixed,
+  /**
+   * Scalac is called then Javac is called. This is the recommended default.
+   *
+   * Under this mode, both Java and Scala sources can depend on each other
+   * at all times.
+   * Java sources are also passed to the Scala compiler, which parses them,
+   * populates the symbol table and lifts them to Scala trees without
+   * generating class files for the Java trees.
+   * Then the incremental compiler will add the generated Scala class files
+   * to the classpath of the Java compiler so that Java sources can depend
+   * on Scala sources.
+   */
+  Mixed,
 
-	/**
-	 * Allow Scala sources to depend on the Java sources, but it does not allow
-	 * Java sources to depend on Scala sources.
-     *
-	 * When mixed compilation is not required, it's generally more efficient
-	 * {@link CompileOrder#JavaThenScala} than {@link CompileOrder#ScalaThenJava}
-	 * because the Scala compiler will not parse Java sources, it will just
-	 * unpickle the symbol information from class files.
-	 */
-	JavaThenScala,
+  /**
+   * Javac is called then Scalac is called.
+   *
+   * When mixed compilation is NOT required, it's generally more efficient
+   * to use {@link CompileOrder#JavaThenScala} than {@link CompileOrder#Mixed}
+   * because the Scala compiler will not parse Java sources: it will just
+   * unpickle the symbol information from class files.
+   *
+   * Because Javac is called first, during the first round of compilation
+   * it does not allow Java sources to depend on Scala sources.
+   * Scala sources can depend on the Java sources at all times.
+   */
+  JavaThenScala,
 
-	/**
-     * Allow Java sources to depend on Scala sources, but it does not allow Java
-	 * sources to depend on Scala sources.
-     *
-     * Because of the way the Scala compiler works with regard to Java sources,
-	 * Zinc has to enforce this mode by removing Java sources from the actual
-	 * source arguments that are passed to the Scala compiler, otherwise it'll
-	 * behave exactly as {@link CompileOrder#Mixed}.
-	 *
-	 * For more information on the way Mixed and ScalaThenJava mode behave,
-	 * see <a href="https://github.com/sbt/zinc/issues/235">this link</a>.
-	 */
-	ScalaThenJava
-}
+  /**
+   * Scalac is called without Java sources, then Javac is called.
+   *
+   * When mixed compilation is NOT required, it's generally more efficient
+   * to use {@link CompileOrder#ScalaThenJava} than {@link CompileOrder#Mixed}
+   * because the Scala compiler will not parse Java sources.
+   *
+   * The downside is that because Java sources are not passed to Scalac,
+   * during the first round of compilation it does not allow Scala sources
+   * to depend on Java sources.
+   *
+   * @deprecated Use {@link CompileOrder#Mixed} instead.
+   */
+  @Deprecated
+  ScalaThenJava
+}

internal/zinc-persist/src/main/scala/sbt/internal/inc/binary/converters/ProtobufReaders.scala

@@ -11,6 +11,7 @@
 
 package sbt.internal.inc.binary.converters
 
+import com.github.ghik.silencer.silent
 import java.nio.file.{ Path, Paths }
 import java.util.{ List => JList, Map => JMap }
 import sbt.internal.inc.Relations.ClassDependencies
@@ -223,7 +224,7 @@ final class ProtobufReaders(mapper: ReadMapper, currentVersion: Schema.Version)
     compileOrder match {
       case Schema.CompileOrder.MIXED         => CompileOrder.Mixed
       case Schema.CompileOrder.JAVATHENSCALA => CompileOrder.JavaThenScala
-      case Schema.CompileOrder.SCALATHENJAVA => CompileOrder.ScalaThenJava
+      case Schema.CompileOrder.SCALATHENJAVA => CompileOrder.ScalaThenJava: @silent
       case Schema.CompileOrder.UNRECOGNIZED  => ReadersFeedback.unrecognizedOrder(id).!!
     }
   }

internal/zinc-persist/src/main/scala/sbt/internal/inc/binary/converters/ProtobufWriters.scala

@@ -11,6 +11,7 @@
 
 package sbt.internal.inc.binary.converters
 
+import com.github.ghik.silencer.silent
 import java.io.File
 import java.nio.file.Path
 
@@ -235,6 +236,7 @@ final class ProtobufWriters(mapper: WriteMapper) {
     builder.build
   }
 
+  @silent
   def toCompileOrder(compileOrder: CompileOrder): Schema.CompileOrder = {
     compileOrder match {
       case CompileOrder.Mixed         => Schema.CompileOrder.MIXED