Launcher documentation

launch/interface/src/main/java/xsbti/AppProvider.java

@@ -2,10 +2,16 @@ package xsbti;
 
 public interface AppProvider
 {
+	/** Returns the ScalaProvider that this AppProvider will use. */
 	public ScalaProvider scalaProvider();
+	/** The ID of the application that will be created by 'newMain' or 'mainClass'.*/
 	public ApplicationID id();
 
+	/** Loads the class for the entry point for the application given by 'id'.  This method will return the same class
+	* every invocation.  That is, the ClassLoader is not recreated each call.*/
 	public Class<? extends AppMain> mainClass();
+	/** Creates a new instance of the entry point of the application given by 'id'.
+	* It is guaranteed that newMain().getClass() == mainClass()*/
 	public AppMain newMain();
 
 	public ComponentProvider components();

launch/interface/src/main/java/xsbti/Exit.java

@@ -1,4 +1,7 @@
 package xsbti;
+
+/** A launched application returns an instance of this class in order to communicate to the launcher
+* that the application is completely finished and the launcher should exit with the given exit code.*/
 public interface Exit extends MainResult
 {
 	public int code();

launch/interface/src/main/java/xsbti/Launcher.java

@@ -1,6 +1,5 @@
 package xsbti;
 
-
 public interface Launcher
 {
 	public static final int InterfaceVersion = 1;

launch/interface/src/main/java/xsbti/MainResult.java

@@ -1,4 +1,8 @@
 package xsbti;
 
-public interface MainResult {}
-
+/** A launched application should return an instance of this from its 'run' method
+* to communicate to the launcher what should be done now that the application
+* has competed.  This interface should be treated as 'sealed', with Exit and Reboot the only
+* direct subtypes.
+*/
+public interface MainResult {}

launch/interface/src/main/java/xsbti/Reboot.java

@@ -2,6 +2,9 @@ package xsbti;
 
 import java.io.File;
 
+/** A launched application returns an instance of this class in order to communicate to the launcher
+* that the application should be restarted.  Different versions of the application and Scala can be used.
+* The application can be given different arguments and a new working directory as well.*/
 public interface Reboot extends MainResult
 {
 	public String[] arguments();

launch/interface/src/main/java/xsbti/ScalaProvider.java

@@ -16,6 +16,7 @@ public interface ScalaProvider
 	public File libraryJar();
 	public File compilerJar();
 	/** Creates an application provider that will use 'loader()' as the parent ClassLoader for
-	* the application given by 'id'.*/
+	* the application given by 'id'.  This method will retrieve the application if it has not already
+	* been retrieved.*/
 	public AppProvider app(ApplicationID id);
 }