Improve javadoc for the environment functions in the BuildConfiguration

In particular, emphasize that that both, the static and dynamic part of
the configuration has to be collected to get the environment to be used
by actions.

--
Change-Id: I035def947d06dbd8f58460b5bf293b35a8ae038c
Reviewed-on: https://cr.bazel.build/9373
PiperOrigin-RevId: 150319122
MOS_MIGRATED_REVID=150319122

1 files changed, 25 insertions, 0 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java b/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java
index d6c34645a6..ca6158ff6f 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java
@@ -2144,10 +2144,35 @@ public final class BuildConfiguration {
         "A dictionary representing the static local shell environment. It maps variables "
             + "to their values (strings)."
   )
+  /**
+   * Return the "fixed" part of the actions' environment variables.
+   *
+   * <p>An action's full set of environment variables consist of a "fixed" part and of a "variable"
+   * part. The "fixed" variables are independent of the Bazel client's own environment, and are
+   * returned by this function. The "variable" ones are inherited from the Bazel client's own
+   * environment, and are returned by {@link getVariableShellEnvironment}.
+   *
+   * <p>Since values of the "fixed" variables are already known at analysis phase, it is returned
+   * here as a map.
+   */
   public ImmutableMap<String, String> getLocalShellEnvironment() {
     return localShellEnvironment;
   }
 
+  /**
+   * Return the "variable" part of the actions' environment variables.
+   *
+   * <p>An action's full set of environment variables consist of a "fixed" part and of a "variable"
+   * part. The "fixed" variables are independent of the Bazel client's own environment, and are
+   * returned by {@link #getLocalShellEnvironment}. The "variable" ones are inherited from the Bazel
+   * client's own environment, and are returned by this function.
+   *
+   * <p>The values of the "variable" variables are tracked in Skyframe via the {@link
+   * com.google.devtools.build.lib.skyframe.SkyFunctions.CLIENT_ENVIRONMENT_VARIABLE} skyfunction.
+   * This method only returns the names of those variables to be inherited, if set in the client's
+   * environment. (Variables where the name is not returned in this set should not be taken from the
+   * client environment.)
+   */
   public ImmutableSet<String> getVariableShellEnvironment() {
     return envVariables;
   }