external build: javadocs added

jps/jps-builders/src/org/jetbrains/jps/incremental/CompiledClass.java

@@ -22,6 +22,7 @@ import com.intellij.util.Function;
 import com.intellij.util.containers.ContainerUtil;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.jps.builders.BuildTarget;
 
 import java.io.File;
 import java.io.IOException;
@@ -29,6 +30,9 @@ import java.util.Collection;
 import java.util.Collections;
 
 /**
+ * In-memory representation of JVM *.class file produced by a compiler.
+ *
+ * @see ModuleLevelBuilder.OutputConsumer#registerCompiledClass(BuildTarget, CompiledClass)
  * @author Eugene Zhuravlev
  *         Date: 11/18/12
  */
@@ -46,6 +50,12 @@ public class CompiledClass extends UserDataHolderBase{
 
   private boolean myIsDirty = false;
 
+  /**
+   * @param outputFile  path where generated *.class file needs to be stored
+   * @param sourceFiles paths to classes which were used to produce the JVM class (for Java language it always contains single *.java file)
+   * @param className   fully qualified dot-separated name of the class
+   * @param content     content which need to be written to {@code outputFile}
+   */
   public CompiledClass(@NotNull File outputFile, @NotNull Collection<File> sourceFiles, @Nullable String className, @NotNull BinaryContent content) {
     myOutputFile = outputFile;
     mySourceFiles = sourceFiles;
@@ -58,7 +68,7 @@ public class CompiledClass extends UserDataHolderBase{
     this(outputFile, Collections.singleton(sourceFile), className, content);
   }
 
-  public  void save() throws IOException {
+  public void save() throws IOException {
     myContent.saveToFile(myOutputFile);
     myIsDirty = false;
   }

jps/jps-builders/src/org/jetbrains/jps/incremental/ModuleLevelBuilder.java

@@ -50,15 +50,29 @@ public abstract class ModuleLevelBuilder extends Builder {
   }
 
   public interface OutputConsumer {
-
+    /**
+     * Call this method for every file (except *.class files for which {@link #registerCompiledClass} should be
+     * used instead) produced by the builder.
+     * @param target unit of compilation to which the source files belong. It must be one the targets composing {@link ModuleChunk} instance
+     *               passed to {@link ModuleLevelBuilder#build} method
+     * @param outputFile path to the produced file
+     * @param sourcePaths path to source files which were used to produce {@code outputFile}
+     */
     void registerOutputFile(@NotNull BuildTarget<?> target, File outputFile, Collection<String> sourcePaths) throws IOException;
 
+    /**
+     * Call this method for every JVM class produced by the builder. You don't need to save *.class file for the produced class to the disk manually.
+     * The passed {@link CompiledClass} instance will be processed by class-file instrumenters and then written to the disk.
+     */
     void registerCompiledClass(@Nullable BuildTarget<?> target, CompiledClass compiled) throws IOException;
 
     Collection<CompiledClass> getTargetCompiledClasses(@NotNull BuildTarget<?> target);
     @NotNull
     Map<String, CompiledClass> getCompiledClasses();
 
+    /**
+     * @param className fully qualified dot-separated name of a class
+     */
     @Nullable
     BinaryContent lookupClassBytes(String className);
   }
@@ -68,7 +82,8 @@ public abstract class ModuleLevelBuilder extends Builder {
    *
    * @param context          compilation context (can be used to report compiler errors/warnings and to check whether the build
    *                         has been cancelled and needs to be stopped).
-   * @param chunk            target to build.
+   * @param chunk            set of targets each of which depends (maybe transitively) on others so they cannot be built separately.
+   *                         For project without circular dependencies it contains only one {@link ModuleBuildTarget} instance.
    * @param dirtyFilesHolder can be used to enumerate the source files from the inputs of this target that have been modified
    *                         or deleted since the previous compilation run.
    * @param outputConsumer   receives the output files and classes produced by the build. (All output files produced by the build