diff --git a/interface/src/main/java/xsbti/compile/CompileProgress.java b/interface/src/main/java/xsbti/compile/CompileProgress.java
index 902a50018..17174ff6a 100755
--- a/interface/src/main/java/xsbti/compile/CompileProgress.java
+++ b/interface/src/main/java/xsbti/compile/CompileProgress.java
@@ -1,5 +1,10 @@
 package xsbti.compile;
 
+/**
+ * An API for reporting when files are being compiled.
+ *
+ * Note; This is tied VERY SPECIFICALLY to scala.
+ */
 public interface CompileProgress {
 	void startUnit(String phase, String unitPath);
 
diff --git a/interface/src/main/java/xsbti/compile/GlobalsCache.java b/interface/src/main/java/xsbti/compile/GlobalsCache.java
index a3a412836..d9aa1c017 100644
--- a/interface/src/main/java/xsbti/compile/GlobalsCache.java
+++ b/interface/src/main/java/xsbti/compile/GlobalsCache.java
@@ -3,6 +3,9 @@ package xsbti.compile;
 import xsbti.Logger;
 import xsbti.Reporter;
 
+/**
+ * An interface which lets us know how to retrieve cached compiler instances form the current JVM.
+ */
 public interface GlobalsCache
 {
 	public CachedCompiler apply(String[] args, Output output, boolean forceNew, CachedCompilerProvider provider, Logger log, Reporter reporter);
diff --git a/interface/src/main/java/xsbti/compile/IncrementalCompiler.java b/interface/src/main/java/xsbti/compile/IncrementalCompiler.java
index f2323111d..c98263e7f 100644
--- a/interface/src/main/java/xsbti/compile/IncrementalCompiler.java
+++ b/interface/src/main/java/xsbti/compile/IncrementalCompiler.java
@@ -44,8 +44,18 @@ public interface IncrementalCompiler<Analysis, ScalaCompiler>
 	* @param instance The Scala version to use
 	* @param interfaceJar The compiler interface jar compiled for the Scala version being used
 	* @param options Configures how arguments to the underlying Scala compiler will be built.
+    *
 	*/
+    @Deprecated
 	ScalaCompiler newScalaCompiler(ScalaInstance instance, File interfaceJar, ClasspathOptions options, Logger log);
+    /**
+     * Creates a compiler instance that can be used by the `compile` method.
+     *
+     * @param instance The Scala version to use
+     * @param interfaceJar The compiler interface jar compiled for the Scala version being used
+     * @param options Configures how arguments to the underlying Scala compiler will be built.
+     */
+    ScalaCompiler newScalaCompiler(ScalaInstance instance, File interfaceJar, ClasspathOptions options);
 
 	/** 
 	* Compiles the source interface for a Scala version.  The resulting jar can then be used by the `newScalaCompiler` method