From e2f61b197a1375b04222aa99a6bbcb290a19e36c Mon Sep 17 00:00:00 2001
From: brandjon <brandjon@google.com>
Date: Wed, 15 Aug 2018 13:55:29 -0700
Subject: Clarify docs for ctx.actions.run_shell()'s command/arguments

- Clarified incompatibility between giving args and giving list of strings for command.

- Added more detail about how $i expansion is done.

- Removed incorrect indication that None is allowed for "command".

RELNOTES: None
PiperOrigin-RevId: 208877037
---
 .../skylarkbuildapi/SkylarkActionFactoryApi.java   | 48 ++++++++++++++--------
 1 file changed, 31 insertions(+), 17 deletions(-)

diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java
index 282890de33..51879b72f3 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java
@@ -23,7 +23,6 @@ import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkValue;
 import com.google.devtools.build.lib.syntax.Environment;
 import com.google.devtools.build.lib.syntax.EvalException;
-import com.google.devtools.build.lib.syntax.Runtime;
 import com.google.devtools.build.lib.syntax.SkylarkDict;
 import com.google.devtools.build.lib.syntax.SkylarkList;
 import com.google.devtools.build.lib.syntax.SkylarkNestedSet;
@@ -343,12 +342,17 @@ public interface SkylarkActionFactoryApi extends SkylarkValue {
             named = true,
             positional = false,
             doc =
-                "Command line arguments of the action. "
-                    + "Must be a list of strings or "
-                    + "<a href=\"actions.html#args\"><code>actions.args()</code></a> objects.<br>"
-                    + "Blaze passes the elements in this attribute as arguments to the command."
+                "Command line arguments of the action. Must be a list of strings or "
+                    + "<a href=\"actions.html#args\"><code>actions.args()</code></a> objects."
+                    + ""
+                    + "<p>Bazel passes the elements in this attribute as arguments to the command."
                     + "The command can access these arguments as <code>$1</code>, <code>$2</code>, "
-                    + "etc."),
+                    + "etc. Args objects are flattened before indexing. It is generally not useful "
+                    + "to have an Args object of unknown size in this list, since that means all "
+                    + "strings in or after that Args object will be at unpredictable indices."
+                    + ""
+                    + "<p>In the case where <code>command</code> is a list of strings, this "
+                    + "parameter may not be used."),
         @Param(
             name = "mnemonic",
             type = String.class,
@@ -363,21 +367,31 @@ public interface SkylarkActionFactoryApi extends SkylarkValue {
             allowedTypes = {
               @ParamType(type = String.class),
               @ParamType(type = SkylarkList.class, generic1 = String.class),
-              @ParamType(type = Runtime.NoneType.class),
             },
             named = true,
             positional = false,
             doc =
-                "Shell command to execute.<br><br>"
-                    + "<b>Passing a sequence of strings to this attribute is deprecated and Blaze "
-                    + "may stop accepting such values in the future.</b> If a sequence of strings "
-                    + "is passed, then <code>arguments</code> must not be used.<br><br> "
-                    + "The command string can access the elements of the <code>arguments</code> "
-                    + "object via <code>$1</code>, <code>$2</code>, etc.<br> "
-                    + "When this argument is a string, it must be a valid shell command. For "
-                    + "example: "
-                    + "\"<code>echo foo > $1</code>\". Blaze uses the same shell to execute the "
-                    + "command as it does for genrules."),
+                "Shell command to execute. This may either be a string (preferred) or a sequence "
+                    + "of strings <b>(deprecated)</b>."
+                    + ""
+                    + "<p>If <code>command</code> is a string, then it is executed as if by "
+                    + "<code>sh -c &lt;command&gt; \"\" &lt;arguments&gt;</code> -- that is, the "
+                    + "elements in <code>arguments</code> are made available to the command as "
+                    + "<code>$1</code>, <code>$2</code>, etc. If <code>arguments</code> contains "
+                    + "any <a href=\"actions.html#args\"><code>actions.args()</code></a> objects, "
+                    + "their contents are appended one by one to the command line, so "
+                    + "<code>$</code><i>i</i> can refer to individual strings within an Args "
+                    + "object. Note that it is not useful to pass an Args object of unknown size "
+                    + "as part of <code>arguments</code>, since then the strings would not be at "
+                    + "known indices."
+                    + ""
+                    + "<p><b>(Deprecated)</b> If <code>command</code> is a sequence of strings, "
+                    + "the first item is the executable to run and the remaining items are its "
+                    + "arguments. If this form is used, the <code>arguments</code> parameter must "
+                    + "not be supplied."
+                    + ""
+                    + "<p>Bazel uses the same shell to execute the command as it does for "
+                    + "genrules."),
         @Param(
             name = "progress_message",
             type = String.class,
-- 
cgit v1.2.3