Improve documentation for resolve_command

--
MOS_MIGRATED_REVID=105875176

1 files changed, 8 insertions, 12 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
index 56f4c2090e..4a42997c0e 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
@@ -130,7 +130,7 @@ public class SkylarkRuleImplementationFunctions {
         @Param(name = "input_manifests", type = Map.class, noneable = true,
             defaultValue = "None",
             doc = "sets the map of input manifests files; "
-            + "they are typically generated by the command_helper")},
+            + "they are typically generated by resolve_command")},
       useLocation = true)
   private static final BuiltinFunction createSpawnAction = new BuiltinFunction("action") {
     public Runtime.NoneType invoke(
@@ -519,12 +519,16 @@ public class SkylarkRuleImplementationFunctions {
     return (Map<Label, Iterable<Artifact>>) labelDict;
   }
 
+  /** suffix of script to be used in case the command is too long to fit on a single line */
+  private static final String SCRIPT_SUFFIX = ".script.sh";
+
   @SkylarkSignature(
     name = "resolve_command",
     doc = "Experimental."
-    + "Returns a tuple of the list of resolved inputs, "
+    + "Returns a tuple (inputs, command, input_manifests) of the list of resolved inputs, "
     + "the argv list for the resolved command, and "
-    + "the dict mapping locations to runfiles required to run the command",
+    + "the dict mapping locations to runfiles required to run the command, "
+    + "all of them suitable for passing as the same-named arguments of the ctx.action method.",
     objectType = SkylarkRuleContext.class,
     returnType = Tuple.class,
     mandatoryPositionals = {
@@ -544,12 +548,6 @@ public class SkylarkRuleImplementationFunctions {
         doc = "name of the associated attribute for which to issue an error, or None"
       ),
       @Param(
-        name = "suffix",
-        type = String.class, // string
-        defaultValue = "'.script.sh'",
-        doc = "suffix of script if command line too long"
-      ),
-      @Param(
         name = "expand_locations",
         type = Boolean.class,
         defaultValue = "False",
@@ -586,7 +584,6 @@ public class SkylarkRuleImplementationFunctions {
             SkylarkRuleContext ctx,
             String command,
             Object attributeO,
-            String suffix,
             Boolean expandLocations,
             Object makeVariablesO,
             SkylarkList tools,
@@ -606,7 +603,6 @@ public class SkylarkRuleImplementationFunctions {
             command = helper.resolveCommandAndExpandLabels(
                 command, attribute, false, false);
           }
-          // TODO(bazel_team): Implement heuristic label expansion
           if (!EvalUtils.isNullOrNone(makeVariablesO)) {
             Map<String, String> makeVariables = Type.STRING_DICT.convert(
                 makeVariablesO, "make_variables", ruleLabel);
@@ -614,7 +610,7 @@ public class SkylarkRuleImplementationFunctions {
           }
           List<Artifact> inputs = new ArrayList<>();
           inputs.addAll(helper.getResolvedTools());
-          List<String> argv = helper.buildCommandLine(command, inputs, suffix);
+          List<String> argv = helper.buildCommandLine(command, inputs, SCRIPT_SUFFIX);
           return Tuple.of(
               new MutableList(inputs, env),
               new MutableList(argv, env),