From de54ae693dc14e5fececd4f12a6dca45bf3626c8 Mon Sep 17 00:00:00 2001
From: nik <Nikolay.Chashnikov@jetbrains.com>
Date: Tue, 17 Apr 2018 11:47:51 +0300
Subject: [PATCH] build process: improve javadoc about target source roots
 (IDEA-190358)

---
 .../jps/builders/AdditionalRootsProviderService.java | 12 ++++++++++++
 .../src/org/jetbrains/jps/builders/BuildTarget.java  | 11 ++++-------
 .../org/jetbrains/jps/builders/DirtyFilesHolder.java |  5 +++++
 .../java/ExcludedJavaSourceRootProvider.java         |  4 ++++
 4 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/jps/jps-builders/src/org/jetbrains/jps/builders/AdditionalRootsProviderService.java b/jps/jps-builders/src/org/jetbrains/jps/builders/AdditionalRootsProviderService.java
index bd0d377a9e39..86878f43dbc7 100644
--- a/jps/jps-builders/src/org/jetbrains/jps/builders/AdditionalRootsProviderService.java
+++ b/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();
diff --git a/jps/jps-builders/src/org/jetbrains/jps/builders/BuildTarget.java b/jps/jps-builders/src/org/jetbrains/jps/builders/BuildTarget.java
index f8b155ab5d63..7a1ba3e660fa 100644
--- a/jps/jps-builders/src/org/jetbrains/jps/builders/BuildTarget.java
+++ b/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,
diff --git a/jps/jps-builders/src/org/jetbrains/jps/builders/DirtyFilesHolder.java b/jps/jps-builders/src/org/jetbrains/jps/builders/DirtyFilesHolder.java
index 3a1eaac159a7..d3c09954b382 100644
--- a/jps/jps-builders/src/org/jetbrains/jps/builders/DirtyFilesHolder.java
+++ b/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>> {
diff --git a/jps/jps-builders/src/org/jetbrains/jps/builders/java/ExcludedJavaSourceRootProvider.java b/jps/jps-builders/src/org/jetbrains/jps/builders/java/ExcludedJavaSourceRootProvider.java
index 18b1a52a9ffb..ecae45a2e8d1 100644
--- a/jps/jps-builders/src/org/jetbrains/jps/builders/java/ExcludedJavaSourceRootProvider.java
+++ b/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
  */