Document the difference between Spawn#getExecutionInfo and Spawn#getCombinedExecProperties
@@ -29,12 +29,23 @@ import javax.annotation.Nullable;
*/
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 @@ public interface Spawn {
*
* <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();
