commit 165cf5d7d3b4a1271d137829fef27c129f80bdc1
author juliexxia <juliexxia@google.com> Fri Mar 20 12:55:12 2020 -0700
committer Copybara-Service <copybara-worker@google.com> Fri Mar 20 12:56:11 2020 -0700
tree 9243c60767cd7e21472356fd8ce902cfecb3ff53
parent c52a51169f13cc3decafa162c78f49e1a080d93c

Document the difference between Spawn#getExecutionInfo and Spawn#getCombinedExecProperties

PiperOrigin-RevId: 302082823

src/main/java/com/google/devtools/build/lib/actions/Spawn.java

diff --git a/src/main/java/com/google/devtools/build/lib/actions/Spawn.java b/src/main/java/com/google/devtools/build/lib/actions/Spawn.java
index 9d95e7d..479a5a8 100644
--- a/src/main/java/com/google/devtools/build/lib/actions/Spawn.java
+++ b/src/main/java/com/google/devtools/build/lib/actions/Spawn.java
@@ -29,12 +29,23 @@
  */
 public interface Spawn {
   /**
-   * Out-of-band data for this spawn. This can be used to signal hints (hardware requirements,
-   * local vs. remote) to the execution subsystem.
+   * Out-of-band data for this spawn. This can be used to signal hints (hardware requirements, local
+   * vs. remote) to the execution subsystem. This data can come from multiple places e.g. tags, hard
+   * coded into rule logic, etc.
    *
-   * <p>String tags from {@link
-   * com.google.devtools.build.lib.analysis.test.TestTargetProperties#getExecutionInfo()} can be added
-   * as keys with arbitrary values to this map too.
+   * <p>The data in this field can be in one of two forms and it is up to the caller of this method
+   * to extract the data it cares about. Forms:
+   *
+   * <ul>
+   *   <li>true key-value pairs
+   *   <li>string tags from {@link *
+   *       com.google.devtools.build.lib.analysis.test.TestTargetProperties#getExecutionInfo()}
+   *       which can be added to the map as keys with arbitrary values (canonically the empty
+   *       string)
+   * </ul>
+   *
+   * <p>Callers of this method may also be interested in the {@link #getCombinedExecProperties()}.
+   * See its javadoc for a comparison.
    */
   ImmutableMap<String, String> getExecutionInfo();
 
@@ -117,6 +128,10 @@
    *
    * <p>Note that this includes data from the execution platform's exec_properties as well as
    * target-level exec_properties.
+   *
+   * <p>Callers might also be interested in {@link #getExecutionInfo()} above. {@link
+   * #getExecutionInfo()} can be set by multiple sources while this data is set via the {@code
+   * exec_properties} attribute on targets and platforms.
    */
   ImmutableMap<String, String> getCombinedExecProperties();