build process: improve javadoc about target source roots (IDEA-190358)

jps/jps-builders/src/org/jetbrains/jps/builders/AdditionalRootsProviderService.java

@@ -23,11 +23,19 @@ import java.util.Collections;
 import java.util.List;
 
 /**
+ * Allows adding additional roots to other build targets.
+ *
+ * Implementations of this class are registered as Java services, by
+ * creating a file META-INF/services/org.jetbrains.jps.builders.AdditionalRootsProviderService containing the qualified name of your implementation
+ * class.
  * @author nik
  */
 public abstract class AdditionalRootsProviderService<R extends BuildRootDescriptor> {
   private final Collection<? extends BuildTargetType<? extends BuildTarget<R>>> myTargetTypes;
 
+  /**
+   * @param targetTypes types of target to which additional roots should be added
+   */
   protected AdditionalRootsProviderService(Collection<? extends BuildTargetType<? extends BuildTarget<R>>> targetTypes) {
     myTargetTypes = targetTypes;
   }
@@ -36,6 +44,10 @@ public abstract class AdditionalRootsProviderService<R extends BuildRootDescript
     return myTargetTypes;
   }
 
+  /**
+   * Override this method to return additional roots which should be added to {@link BuildTarget#computeRootDescriptors the roots} returned
+   * by the {@code target} itself.
+   */
   @NotNull
   public List<R> getAdditionalRoots(@NotNull BuildTarget<R> target, BuildDataPaths dataPaths) {
     return Collections.emptyList();

jps/jps-builders/src/org/jetbrains/jps/builders/BuildTarget.java

@@ -80,13 +80,10 @@ public abstract class BuildTarget<R extends BuildRootDescriptor> {
   }
 
   /**
-   * Returns the list of source roots for this target.
-   *
-   * @param model            the JPS project model.
-   * @param index            the index of exclude roots.
-   * @param ignoredFileIndex the index of ignore patterns.
-   * @param dataPaths        the index of paths that can be used to serialize data related to build targets.
-   * @return
+   * Returns the list of root directories which contain input files for this target. The build process will track files under these root
+   * and pass modified and deleted files to the builders via {@link DirtyFilesHolder}.
+   * @see AdditionalRootsProviderService
+   * @see org.jetbrains.jps.builders.java.ExcludedJavaSourceRootProvider
    */
   @NotNull
   public abstract List<R> computeRootDescriptors(JpsModel model,

jps/jps-builders/src/org/jetbrains/jps/builders/DirtyFilesHolder.java

@@ -21,6 +21,11 @@ import java.io.IOException;
 import java.util.Collection;
 
 /**
+ * Provides list of files under {@link BuildTarget#computeRootDescriptors source roots} of a target which were modified or deleted since the
+ * previous build.
+ *
+ * @see org.jetbrains.jps.incremental.TargetBuilder#build
+ * @see org.jetbrains.jps.incremental.ModuleLevelBuilder#build
  * @author nik
  */
 public interface DirtyFilesHolder<R extends BuildRootDescriptor, T extends BuildTarget<R>> {

jps/jps-builders/src/org/jetbrains/jps/builders/java/ExcludedJavaSourceRootProvider.java

@@ -20,6 +20,10 @@ import org.jetbrains.jps.model.module.JpsModule;
 import org.jetbrains.jps.model.module.JpsModuleSourceRoot;
 
 /**
+ * Allows excluding source or resource roots of Java modules from compilation.
+ *
+ * Implementations of this class are registered as Java services, by creating a file
+ * META-INF/services/org.jetbrains.jps.builders.java.ExcludedJavaSourceRootProvider containing the qualified name of your implementation class.
  *
  * @author nik
  */