Fix a few generated docs.

In particular,

* fix sentences with no space after the period, like [here]([]
* switch backticks to `<code>`, like [here]([]
* link `ctx.var` [here]([]
* Add periods to the end of paragraphs, like [here]([]
* Format a list [here]([]

Closes #5337.

PiperOrigin-RevId: 199631585

4 files changed, 571 insertions, 608 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java
index 6d6ba657a8..8bb807041d 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/CommandLineArgsApi.java
@@ -502,19 +502,20 @@ public interface CommandLineArgsApi extends SkylarkValue {
   public void useParamsFile(String paramFileArg, Boolean useAlways) throws EvalException;
 
   @SkylarkCallable(
-    name = "set_param_file_format",
-    doc = "Sets the format of the param file when written to disk",
-    parameters = {
-      @Param(
-          name = "format",
-          type = String.class,
-          named = true,
-          doc =
-              "The format of the param file. Must be one of:<br>"
-                  + "\"shell\": All arguments are shell quoted and separated by whitespace<br>"
-                  + "\"multiline\": All arguments are unquoted and separated by newline characters"
-                  + "The format defaults to \"shell\" if not called.")
-    }
-  )
+      name = "set_param_file_format",
+      doc = "Sets the format of the param file when written to disk",
+      parameters = {
+        @Param(
+            name = "format",
+            type = String.class,
+            named = true,
+            doc =
+                "The format of the param file. Must be one of:<ul><li>"
+                    + "\"shell\": All arguments are shell quoted and separated by "
+                    + "whitespace</li><li>"
+                    + "\"multiline\": All arguments are unquoted and separated by newline "
+                    + "characters</li></ul>"
+                    + "The format defaults to \"shell\" if not called.")
+      })
   public void setParamFileFormat(String format) throws EvalException;
 }
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 25a3218bc6..1d03df9edf 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
@@ -38,43 +38,42 @@ import com.google.devtools.build.lib.syntax.SkylarkNestedSet;
 public interface SkylarkActionFactoryApi extends SkylarkValue {
 
   @SkylarkCallable(
-    name = "declare_file",
-    doc =
-        "Declares that the rule or aspect creates a file with the given filename. "
-            + "If <code>sibling</code> is not specified, the file name is relative to the package"
-            + "directory, otherwise the file is in the same directory as <code>sibling</code>."
-            + "Files cannot be created outside of the current package."
-            + "<p>Remember that in addition to declaring a file, you must separately create an "
-            + "action that emits the file. Creating that action will require passing the returned "
-            + "<code>File</code> object to the action's construction function."
-            + "<p>Note that <a href='../rules.$DOC_EXT#files'>predeclared output files</a> do not "
-            + "need to be (and cannot be) declared using this function. You can obtain their "
-            + "<code>File</code> objects from <a href=\"ctx.html#outputs\"><code>ctx.outputs</code>"
-            + "</a> instead. "
-            + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
-            + "computed_dependencies/hash.bzl\">See example of use</a>",
-    parameters = {
-      @Param(
-        name = "filename",
-        type = String.class,
-        doc =
-            "If no 'sibling' provided, path of the new file, relative "
-                + "to the current package. Otherwise a base name for a file "
-                + "('sibling' determines a directory)."
-      ),
-      @Param(
-        name = "sibling",
-        doc =
-            "A file that lives in the same directory as the newly created file. "
-                + "The file must be in the current package.",
-        type = FileApi.class,
-        noneable = true,
-        positional = false,
-        named = true,
-        defaultValue = "None"
-      )
-    }
-  )
+      name = "declare_file",
+      doc =
+          "Declares that the rule or aspect creates a file with the given filename. "
+              + "If <code>sibling</code> is not specified, the file name is relative to the "
+              + "package "
+              + "directory, otherwise the file is in the same directory as <code>sibling</code>. "
+              + "Files cannot be created outside of the current package."
+              + "<p>Remember that in addition to declaring a file, you must separately create an "
+              + "action that emits the file. Creating that action will require passing the "
+              + "returned <code>File</code> object to the action's construction function."
+              + "<p>Note that <a href='../rules.$DOC_EXT#files'>predeclared output files</a> do "
+              + "not "
+              + "need to be (and cannot be) declared using this function. You can obtain their "
+              + "<code>File</code> objects from "
+              + "<a href=\"ctx.html#outputs\"><code>ctx.outputs</code></a> instead. "
+              + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
+              + "computed_dependencies/hash.bzl\">See example of use</a>.",
+      parameters = {
+        @Param(
+            name = "filename",
+            type = String.class,
+            doc =
+                "If no 'sibling' provided, path of the new file, relative "
+                    + "to the current package. Otherwise a base name for a file "
+                    + "('sibling' determines a directory)."),
+        @Param(
+            name = "sibling",
+            doc =
+                "A file that lives in the same directory as the newly created file. "
+                    + "The file must be in the current package.",
+            type = FileApi.class,
+            noneable = true,
+            positional = false,
+            named = true,
+            defaultValue = "None")
+      })
   public FileApi declareFile(String filename, Object sibling) throws EvalException;
 
   @SkylarkCallable(
@@ -161,137 +160,126 @@ public interface SkylarkActionFactoryApi extends SkylarkValue {
   public void write(FileApi output, Object content, Boolean isExecutable) throws EvalException;
 
   @SkylarkCallable(
-    name = "run",
-    doc =
-        "Creates an action that runs an executable. "
-            + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
-            + "actions_run/execute.bzl\">See example of use</a>",
-    parameters = {
-      @Param(
-        name = "outputs",
-        type = SkylarkList.class,
-        generic1 = FileApi.class,
-        named = true,
-        positional = false,
-        doc = "List of the output files of the action."
-      ),
-      @Param(
-        name = "inputs",
-        allowedTypes = {
-          @ParamType(type = SkylarkList.class),
-          @ParamType(type = SkylarkNestedSet.class),
-        },
-        generic1 = FileApi.class,
-        defaultValue = "[]",
-        named = true,
-        positional = false,
-        doc = "List or depset of the input files of the action."
-      ),
-      @Param(
-        name = "executable",
-        type = Object.class,
-        allowedTypes = {
-          @ParamType(type = FileApi.class),
-          @ParamType(type = String.class),
-        },
-        named = true,
-        positional = false,
-        doc = "The executable file to be called by the action."
-      ),
-      @Param(
-        name = "tools",
-        allowedTypes = {
-          @ParamType(type = SkylarkList.class),
-          @ParamType(type = SkylarkNestedSet.class),
-        },
-        generic1 = FileApi.class,
-        defaultValue = "unbound",
-        named = true,
-        positional = false,
-        doc =
-            "List or depset of any tools needed by the action. Tools are inputs with additional "
-                + "runfiles that are automatically made available to the action."
-      ),
-      @Param(
-        name = "arguments",
-        type = Object.class,
-        allowedTypes = {
-          @ParamType(type = SkylarkList.class),
-        },
-        defaultValue = "[]",
-        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."
-      ),
-      @Param(
-        name = "mnemonic",
-        type = String.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc = "A one-word description of the action, for example, CppCompile or GoLink."
-      ),
-      @Param(
-        name = "progress_message",
-        type = String.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc =
-            "Progress message to show to the user during the build, "
-                + "for example, \"Compiling foo.cc to create foo.o\"."
-      ),
-      @Param(
-        name = "use_default_shell_env",
-        type = Boolean.class,
-        defaultValue = "False",
-        named = true,
-        positional = false,
-        doc = "Whether the action should use the built in shell environment or not."
-      ),
-      @Param(
-        name = "env",
-        type = SkylarkDict.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc = "Sets the dictionary of environment variables."
-      ),
-      @Param(
-        name = "execution_requirements",
-        type = SkylarkDict.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc =
-            "Information for scheduling the action. See "
-                + "<a href=\"$BE_ROOT/common-definitions.html#common.tags\">tags</a> "
-                + "for useful keys."
-      ),
-      @Param(
-        // TODO(bazel-team): The name here isn't accurate anymore.
-        // This is technically experimental, so folks shouldn't be too attached,
-        // but consider renaming to be more accurate/opaque.
-        name = "input_manifests",
-        type = SkylarkList.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc =
-            "(Experimental) sets the input runfiles metadata; "
-                + "they are typically generated by resolve_command."
-      )
-    },
-    useLocation = true
-  )
+      name = "run",
+      doc =
+          "Creates an action that runs an executable. "
+              + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
+              + "actions_run/execute.bzl\">See example of use</a>.",
+      parameters = {
+        @Param(
+            name = "outputs",
+            type = SkylarkList.class,
+            generic1 = FileApi.class,
+            named = true,
+            positional = false,
+            doc = "List of the output files of the action."),
+        @Param(
+            name = "inputs",
+            allowedTypes = {
+              @ParamType(type = SkylarkList.class),
+              @ParamType(type = SkylarkNestedSet.class),
+            },
+            generic1 = FileApi.class,
+            defaultValue = "[]",
+            named = true,
+            positional = false,
+            doc = "List or depset of the input files of the action."),
+        @Param(
+            name = "executable",
+            type = Object.class,
+            allowedTypes = {
+              @ParamType(type = FileApi.class),
+              @ParamType(type = String.class),
+            },
+            named = true,
+            positional = false,
+            doc = "The executable file to be called by the action."),
+        @Param(
+            name = "tools",
+            allowedTypes = {
+              @ParamType(type = SkylarkList.class),
+              @ParamType(type = SkylarkNestedSet.class),
+            },
+            generic1 = FileApi.class,
+            defaultValue = "unbound",
+            named = true,
+            positional = false,
+            doc =
+                "List or depset of any tools needed by the action. Tools are inputs with "
+                    + "additional "
+                    + "runfiles that are automatically made available to the action."),
+        @Param(
+            name = "arguments",
+            type = Object.class,
+            allowedTypes = {
+              @ParamType(type = SkylarkList.class),
+            },
+            defaultValue = "[]",
+            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."),
+        @Param(
+            name = "mnemonic",
+            type = String.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc = "A one-word description of the action, for example, CppCompile or GoLink."),
+        @Param(
+            name = "progress_message",
+            type = String.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "Progress message to show to the user during the build, "
+                    + "for example, \"Compiling foo.cc to create foo.o\"."),
+        @Param(
+            name = "use_default_shell_env",
+            type = Boolean.class,
+            defaultValue = "False",
+            named = true,
+            positional = false,
+            doc = "Whether the action should use the built in shell environment or not."),
+        @Param(
+            name = "env",
+            type = SkylarkDict.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc = "Sets the dictionary of environment variables."),
+        @Param(
+            name = "execution_requirements",
+            type = SkylarkDict.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "Information for scheduling the action. See "
+                    + "<a href=\"$BE_ROOT/common-definitions.html#common.tags\">tags</a> "
+                    + "for useful keys."),
+        @Param(
+            // TODO(bazel-team): The name here isn't accurate anymore.
+            // This is technically experimental, so folks shouldn't be too attached,
+            // but consider renaming to be more accurate/opaque.
+            name = "input_manifests",
+            type = SkylarkList.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "(Experimental) sets the input runfiles metadata; "
+                    + "they are typically generated by resolve_command.")
+      },
+      useLocation = true)
   public void run(
       SkylarkList outputs,
       Object inputs,
@@ -308,147 +296,140 @@ public interface SkylarkActionFactoryApi extends SkylarkValue {
       throws EvalException;
 
   @SkylarkCallable(
-    name = "run_shell",
-    doc =
-        "Creates an action that runs a shell command. "
-            + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
-            + "shell_command/size.bzl\">See example of use</a>",
-    parameters = {
-      @Param(
-        name = "outputs",
-        type = SkylarkList.class,
-        generic1 = FileApi.class,
-        named = true,
-        positional = false,
-        doc = "List of the output files of the action."
-      ),
-      @Param(
-        name = "inputs",
-        allowedTypes = {
-          @ParamType(type = SkylarkList.class),
-          @ParamType(type = SkylarkNestedSet.class),
-        },
-        generic1 = FileApi.class,
-        defaultValue = "[]",
-        named = true,
-        positional = false,
-        doc = "List or depset of the input files of the action."
-      ),
-      @Param(
-        name = "tools",
-        allowedTypes = {
-          @ParamType(type = SkylarkList.class),
-          @ParamType(type = SkylarkNestedSet.class),
-        },
-        generic1 = FileApi.class,
-        defaultValue = "unbound",
-        named = true,
-        positional = false,
-        doc =
-            "List or depset of any tools needed by the action. Tools are inputs with additional "
-                + "runfiles that are automatically made available to the action."
-      ),
-      @Param(
-        name = "arguments",
-        allowedTypes = {
-          @ParamType(type = SkylarkList.class),
-        },
-        defaultValue = "[]",
-        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."
-                + "The command can access these arguments as <code>$1</code>, <code>$2</code>, etc."
-      ),
-      @Param(
-        name = "mnemonic",
-        type = String.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc = "A one-word description of the action, for example, CppCompile or GoLink."
-      ),
-      @Param(
-        name = "command",
-        type = Object.class,
-        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><br><br>"
-                + "The command 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."
-      ),
-      @Param(
-        name = "progress_message",
-        type = String.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc =
-            "Progress message to show to the user during the build, "
-                + "for example, \"Compiling foo.cc to create foo.o\"."
-      ),
-      @Param(
-        name = "use_default_shell_env",
-        type = Boolean.class,
-        defaultValue = "False",
-        named = true,
-        positional = false,
-        doc = "Whether the action should use the built in shell environment or not."
-      ),
-      @Param(
-        name = "env",
-        type = SkylarkDict.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc = "Sets the dictionary of environment variables."
-      ),
-      @Param(
-        name = "execution_requirements",
-        type = SkylarkDict.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc =
-            "Information for scheduling the action. See "
-                + "<a href=\"$BE_ROOT/common-definitions.html#common.tags\">tags</a> "
-                + "for useful keys."
-      ),
-      @Param(
-        // TODO(bazel-team): The name here isn't accurate anymore.
-        // This is technically experimental, so folks shouldn't be too attached,
-        // but consider renaming to be more accurate/opaque.
-        name = "input_manifests",
-        type = SkylarkList.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc =
-            "(Experimental) sets the input runfiles metadata; "
-                + "they are typically generated by resolve_command."
-      )
-    },
-    useLocation = true
-  )
+      name = "run_shell",
+      doc =
+          "Creates an action that runs a shell command. "
+              + "<a href=\"https://github.com/bazelbuild/examples/tree/master/rules/"
+              + "shell_command/size.bzl\">See example of use</a>.",
+      parameters = {
+        @Param(
+            name = "outputs",
+            type = SkylarkList.class,
+            generic1 = FileApi.class,
+            named = true,
+            positional = false,
+            doc = "List of the output files of the action."),
+        @Param(
+            name = "inputs",
+            allowedTypes = {
+              @ParamType(type = SkylarkList.class),
+              @ParamType(type = SkylarkNestedSet.class),
+            },
+            generic1 = FileApi.class,
+            defaultValue = "[]",
+            named = true,
+            positional = false,
+            doc = "List or depset of the input files of the action."),
+        @Param(
+            name = "tools",
+            allowedTypes = {
+              @ParamType(type = SkylarkList.class),
+              @ParamType(type = SkylarkNestedSet.class),
+            },
+            generic1 = FileApi.class,
+            defaultValue = "unbound",
+            named = true,
+            positional = false,
+            doc =
+                "List or depset of any tools needed by the action. Tools are inputs with "
+                    + "additional "
+                    + "runfiles that are automatically made available to the action."),
+        @Param(
+            name = "arguments",
+            allowedTypes = {
+              @ParamType(type = SkylarkList.class),
+            },
+            defaultValue = "[]",
+            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."
+                    + "The command can access these arguments as <code>$1</code>, <code>$2</code>, "
+                    + "etc."),
+        @Param(
+            name = "mnemonic",
+            type = String.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc = "A one-word description of the action, for example, CppCompile or GoLink."),
+        @Param(
+            name = "command",
+            type = Object.class,
+            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><br><br>"
+                    + "The command 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."),
+        @Param(
+            name = "progress_message",
+            type = String.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "Progress message to show to the user during the build, "
+                    + "for example, \"Compiling foo.cc to create foo.o\"."),
+        @Param(
+            name = "use_default_shell_env",
+            type = Boolean.class,
+            defaultValue = "False",
+            named = true,
+            positional = false,
+            doc = "Whether the action should use the built in shell environment or not."),
+        @Param(
+            name = "env",
+            type = SkylarkDict.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc = "Sets the dictionary of environment variables."),
+        @Param(
+            name = "execution_requirements",
+            type = SkylarkDict.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "Information for scheduling the action. See "
+                    + "<a href=\"$BE_ROOT/common-definitions.html#common.tags\">tags</a> "
+                    + "for useful keys."),
+        @Param(
+            // TODO(bazel-team): The name here isn't accurate anymore.
+            // This is technically experimental, so folks shouldn't be too attached,
+            // but consider renaming to be more accurate/opaque.
+            name = "input_manifests",
+            type = SkylarkList.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "(Experimental) sets the input runfiles metadata; "
+                    + "they are typically generated by resolve_command.")
+      },
+      useLocation = true)
   public void runShell(
       SkylarkList outputs,
       Object inputs,
@@ -465,48 +446,44 @@ public interface SkylarkActionFactoryApi extends SkylarkValue {
       throws EvalException;
 
   @SkylarkCallable(
-    name = "expand_template",
-    doc =
-        "Creates a template expansion action. When the action is executed, it will "
-            + "generate a file based on a template. Parts of the template will be replaced "
-            + "using the <code>substitutions</code> dictionary. Whenever a key of the "
-            + "dictionary appears in the template, it is replaced with the associated value. "
-            + "There is no special syntax for the keys. You may, for example, use curly braces "
-            + "to avoid conflicts (for example, <code>{KEY}</code>). "
-            + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/expand_template/hello.bzl\">"
-            + "See example of use</a>",
-    parameters = {
-      @Param(
-        name = "template",
-        type = FileApi.class,
-        named = true,
-        positional = false,
-        doc = "The template file, which is a UTF-8 encoded text file."
-      ),
-      @Param(
-        name = "output",
-        type = FileApi.class,
-        named = true,
-        positional = false,
-        doc = "The output file, which is a UTF-8 encoded text file."
-      ),
-      @Param(
-        name = "substitutions",
-        type = SkylarkDict.class,
-        named = true,
-        positional = false,
-        doc = "Substitutions to make when expanding the template."
-      ),
-      @Param(
-        name = "is_executable",
-        type = Boolean.class,
-        defaultValue = "False",
-        named = true,
-        positional = false,
-        doc = "Whether the output file should be executable."
-      )
-    }
-  )
+      name = "expand_template",
+      doc =
+          "Creates a template expansion action. When the action is executed, it will "
+              + "generate a file based on a template. Parts of the template will be replaced "
+              + "using the <code>substitutions</code> dictionary. Whenever a key of the "
+              + "dictionary appears in the template, it is replaced with the associated value. "
+              + "There is no special syntax for the keys. You may, for example, use curly braces "
+              + "to avoid conflicts (for example, <code>{KEY}</code>). "
+              + "<a href=\"https://github.com/bazelbuild/examples/blob/master/rules/"
+              + "expand_template/hello.bzl\">"
+              + "See example of use</a>.",
+      parameters = {
+        @Param(
+            name = "template",
+            type = FileApi.class,
+            named = true,
+            positional = false,
+            doc = "The template file, which is a UTF-8 encoded text file."),
+        @Param(
+            name = "output",
+            type = FileApi.class,
+            named = true,
+            positional = false,
+            doc = "The output file, which is a UTF-8 encoded text file."),
+        @Param(
+            name = "substitutions",
+            type = SkylarkDict.class,
+            named = true,
+            positional = false,
+            doc = "Substitutions to make when expanding the template."),
+        @Param(
+            name = "is_executable",
+            type = Boolean.class,
+            defaultValue = "False",
+            named = true,
+            positional = false,
+            doc = "Whether the output file should be executable.")
+      })
   public void expandTemplate(
       FileApi template,
       FileApi output,
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java
index 2350429680..7c1be4caf3 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkRuleContextApi.java
@@ -371,23 +371,26 @@ public interface SkylarkRuleContextApi extends SkylarkValue {
       throws EvalException;
 
   @SkylarkCallable(
-    doc = "<b>Deprecated.</b> Use <code>ctx.var</code> to access the variables instead.<br>"
-        + "Returns a string after expanding all references to \"Make variables\". The variables "
-        + "must have the following format: <code>$(VAR_NAME)</code>. Also, <code>$$VAR_NAME"
-        + "</code> expands to <code>$VAR_NAME</code>. Parameters:"
-        + "<ul><li>The name of the attribute (<code>string</code>). It's only used for error "
-        + "reporting.</li>\n"
-        + "<li>The expression to expand (<code>string</code>). It can contain references to "
-        + "\"Make variables\".</li>\n"
-        + "<li>A mapping of additional substitutions (<code>dict</code> of <code>string</code> : "
-        + "<code>string</code>).</li></ul>\n"
-        + "Examples:"
-        + "<pre class=language-python>\n"
-        + "ctx.expand_make_variables(\"cmd\", \"$(MY_VAR)\", {\"MY_VAR\": \"Hi\"})  # == \"Hi\"\n"
-        + "ctx.expand_make_variables(\"cmd\", \"$$PWD\", {})  # == \"$PWD\"\n"
-        + "</pre>"
-        + "Additional variables may come from other places, such as configurations. Note that "
-        + "this function is experimental.")
+      doc =
+          "<b>Deprecated.</b> Use <a href=\"ctx.html#var\">ctx.var</a> to access the variables "
+              + "instead.<br>Returns a string after expanding all references to \"Make "
+              + "variables\". The "
+              + "variables must have the following format: <code>$(VAR_NAME)</code>. Also, "
+              + "<code>$$VAR_NAME</code> expands to <code>$VAR_NAME</code>. Parameters:"
+              + "<ul><li>The name of the attribute (<code>string</code>). It's only used for error "
+              + "reporting.</li>\n"
+              + "<li>The expression to expand (<code>string</code>). It can contain references to "
+              + "\"Make variables\".</li>\n"
+              + "<li>A mapping of additional substitutions (<code>dict</code> of "
+              + "<code>string</code> : <code>string</code>).</li></ul>\n"
+              + "Examples:"
+              + "<pre class=language-python>\n"
+              + "ctx.expand_make_variables(\"cmd\", \"$(MY_VAR)\", {\"MY_VAR\": \"Hi\"})  "
+              + "# == \"Hi\"\n"
+              + "ctx.expand_make_variables(\"cmd\", \"$$PWD\", {})  # == \"$PWD\"\n"
+              + "</pre>"
+              + "Additional variables may come from other places, such as configurations. Note "
+              + "that this function is experimental.")
   public String expandMakeVariables(
       String attributeName, String command, final Map<String, String> additionalSubstitutions)
       throws EvalException;
@@ -421,160 +424,148 @@ public interface SkylarkRuleContextApi extends SkylarkValue {
   public String getBuildFileRelativePath() throws EvalException;
 
   @SkylarkCallable(
-    name = "action",
-    doc =
-        "DEPRECATED. Use <a href=\"actions.html#run\">ctx.actions.run()</a> or"
-            + " <a href=\"actions.html#run_shell\">ctx.actions.run_shell()</a>. <br>"
-            + "Creates an action that runs an executable or a shell command."
-            + " You must specify either <code>command</code> or <code>executable</code>.\n"
-            + "Actions and genrules are very similar, but have different use cases. Actions are "
-            + "used inside rules, and genrules are used inside macros. Genrules also have make "
-            + "variable expansion.",
-    parameters = {
-      @Param(
-        name = "outputs",
-        type = SkylarkList.class,
-        generic1 = FileApi.class,
-        named = true,
-        positional = false,
-        doc = "List of the output files of the action."
-      ),
-      @Param(
-        name = "inputs",
-        allowedTypes = {
-          @ParamType(type = SkylarkList.class),
-          @ParamType(type = SkylarkNestedSet.class),
-        },
-        generic1 = FileApi.class,
-        defaultValue = "[]",
-        named = true,
-        positional = false,
-        doc = "List of the input files of the action."
-      ),
-      @Param(
-        name = "executable",
-        type = Object.class,
-        allowedTypes = {
-          @ParamType(type = FileApi.class),
-          @ParamType(type = String.class),
-          @ParamType(type = Runtime.NoneType.class),
-        },
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc = "The executable file to be called by the action."
-      ),
-      @Param(
-        name = "tools",
-        allowedTypes = {
-          @ParamType(type = SkylarkList.class),
-          @ParamType(type = SkylarkNestedSet.class),
-        },
-        generic1 = FileApi.class,
-        defaultValue = "unbound",
-        named = true,
-        positional = false,
-        doc =
-            "List of the any tools needed by the action. Tools are inputs with additional "
-                + "runfiles that are automatically made available to the action."
-      ),
-      @Param(
-        name = "arguments",
-        allowedTypes = {
-          @ParamType(type = SkylarkList.class),
-        },
-        defaultValue = "[]",
-        named = true,
-        positional = false,
-        doc =
-            "Command line arguments of the action."
-                + "Must be a list of strings or actions.args() objects."
-      ),
-      @Param(
-        name = "mnemonic",
-        type = String.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc = "A one-word description of the action, e.g. CppCompile or GoLink."
-      ),
-      @Param(
-        name = "command",
-        type = Object.class,
-        allowedTypes = {
-          @ParamType(type = String.class),
-          @ParamType(type = SkylarkList.class, generic1 = String.class),
-          @ParamType(type = Runtime.NoneType.class),
-        },
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc =
-            "Shell command to execute. It is usually preferable to "
-                + "use <code>executable</code> instead. "
-                + "Arguments are available with <code>$1</code>, <code>$2</code>, etc."
-      ),
-      @Param(
-        name = "progress_message",
-        type = String.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc =
-            "Progress message to show to the user during the build, "
-                + "e.g. \"Compiling foo.cc to create foo.o\"."
-      ),
-      @Param(
-        name = "use_default_shell_env",
-        type = Boolean.class,
-        defaultValue = "False",
-        named = true,
-        positional = false,
-        doc = "Whether the action should use the built in shell environment or not."
-      ),
-      @Param(
-        name = "env",
-        type = SkylarkDict.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc = "Sets the dictionary of environment variables."
-      ),
-      @Param(
-        name = "execution_requirements",
-        type = SkylarkDict.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc =
-            "Information for scheduling the action. See "
-                + "<a href=\"$BE_ROOT/common-definitions.html#common.tags\">tags</a> "
-                + "for useful keys."
-      ),
-      @Param(
-        // TODO(bazel-team): The name here isn't accurate anymore. This is technically experimental,
-        // so folks shouldn't be too attached, but consider renaming to be more accurate/opaque.
-        name = "input_manifests",
-        type = SkylarkList.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        positional = false,
-        doc =
-            "(Experimental) sets the input runfiles metadata; "
-                + "they are typically generated by resolve_command."
-      )
-    },
-    allowReturnNones = true,
-    useLocation = true,
-    useEnvironment = true
-  )
+      name = "action",
+      doc =
+          "DEPRECATED. Use <a href=\"actions.html#run\">ctx.actions.run()</a> or"
+              + " <a href=\"actions.html#run_shell\">ctx.actions.run_shell()</a>. <br>"
+              + "Creates an action that runs an executable or a shell command."
+              + " You must specify either <code>command</code> or <code>executable</code>.\n"
+              + "Actions and genrules are very similar, but have different use cases. Actions are "
+              + "used inside rules, and genrules are used inside macros. Genrules also have make "
+              + "variable expansion.",
+      parameters = {
+        @Param(
+            name = "outputs",
+            type = SkylarkList.class,
+            generic1 = FileApi.class,
+            named = true,
+            positional = false,
+            doc = "List of the output files of the action."),
+        @Param(
+            name = "inputs",
+            allowedTypes = {
+              @ParamType(type = SkylarkList.class),
+              @ParamType(type = SkylarkNestedSet.class),
+            },
+            generic1 = FileApi.class,
+            defaultValue = "[]",
+            named = true,
+            positional = false,
+            doc = "List of the input files of the action."),
+        @Param(
+            name = "executable",
+            type = Object.class,
+            allowedTypes = {
+              @ParamType(type = FileApi.class),
+              @ParamType(type = String.class),
+              @ParamType(type = Runtime.NoneType.class),
+            },
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc = "The executable file to be called by the action."),
+        @Param(
+            name = "tools",
+            allowedTypes = {
+              @ParamType(type = SkylarkList.class),
+              @ParamType(type = SkylarkNestedSet.class),
+            },
+            generic1 = FileApi.class,
+            defaultValue = "unbound",
+            named = true,
+            positional = false,
+            doc =
+                "List of the any tools needed by the action. Tools are inputs with additional "
+                    + "runfiles that are automatically made available to the action."),
+        @Param(
+            name = "arguments",
+            allowedTypes = {
+              @ParamType(type = SkylarkList.class),
+            },
+            defaultValue = "[]",
+            named = true,
+            positional = false,
+            doc =
+                "Command line arguments of the action. Must be a list of strings or actions.args() "
+                    + "objects."),
+        @Param(
+            name = "mnemonic",
+            type = String.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc = "A one-word description of the action, e.g. CppCompile or GoLink."),
+        @Param(
+            name = "command",
+            type = Object.class,
+            allowedTypes = {
+              @ParamType(type = String.class),
+              @ParamType(type = SkylarkList.class, generic1 = String.class),
+              @ParamType(type = Runtime.NoneType.class),
+            },
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "Shell command to execute. It is usually preferable to "
+                    + "use <code>executable</code> instead. "
+                    + "Arguments are available with <code>$1</code>, <code>$2</code>, etc."),
+        @Param(
+            name = "progress_message",
+            type = String.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "Progress message to show to the user during the build, "
+                    + "e.g. \"Compiling foo.cc to create foo.o\"."),
+        @Param(
+            name = "use_default_shell_env",
+            type = Boolean.class,
+            defaultValue = "False",
+            named = true,
+            positional = false,
+            doc = "Whether the action should use the built in shell environment or not."),
+        @Param(
+            name = "env",
+            type = SkylarkDict.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc = "Sets the dictionary of environment variables."),
+        @Param(
+            name = "execution_requirements",
+            type = SkylarkDict.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "Information for scheduling the action. See "
+                    + "<a href=\"$BE_ROOT/common-definitions.html#common.tags\">tags</a> "
+                    + "for useful keys."),
+        @Param(
+            // TODO(bazel-team): The name here isn't accurate anymore. This is technically
+            // experimental,
+            // so folks shouldn't be too attached, but consider renaming to be more accurate/opaque.
+            name = "input_manifests",
+            type = SkylarkList.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            positional = false,
+            doc =
+                "(Experimental) sets the input runfiles metadata; "
+                    + "they are typically generated by resolve_command.")
+      },
+      allowReturnNones = true,
+      useLocation = true,
+      useEnvironment = true)
   public Runtime.NoneType action(
       SkylarkList outputs,
       Object inputs,
@@ -737,66 +728,60 @@ public interface SkylarkRuleContextApi extends SkylarkValue {
       throws EvalException;
 
   @SkylarkCallable(
-    name = "runfiles",
-    doc = "Creates a runfiles object.",
-    parameters = {
-      @Param(
-        name = "files",
-        type = SkylarkList.class,
-        generic1 = FileApi.class,
-        named = true,
-        defaultValue = "[]",
-        doc = "The list of files to be added to the runfiles."
-      ),
-      // TODO(bazel-team): If we have a memory efficient support for lazy list containing
-      // NestedSets we can remove this and just use files = [file] + list(set)
-      // Also, allow empty set for init
-      @Param(
-        name = "transitive_files",
-        type = SkylarkNestedSet.class,
-        generic1 = FileApi.class,
-        noneable = true,
-        defaultValue = "None",
-        named = true,
-        doc =
-            "The (transitive) set of files to be added to the runfiles. The depset should "
-                + "use the `default` order (which, as the name implies, is the default)."
-      ),
-      @Param(
-        name = "collect_data",
-        type = Boolean.class,
-        defaultValue = "False",
-        named = true,
-        doc =
-            "Whether to collect the data "
-                + "runfiles from the dependencies in srcs, data and deps attributes."
-      ),
-      @Param(
-        name = "collect_default",
-        type = Boolean.class,
-        defaultValue = "False",
-        named = true,
-        doc =
-            "Whether to collect the default "
-                + "runfiles from the dependencies in srcs, data and deps attributes."
-      ),
-      @Param(
-        name = "symlinks",
-        type = SkylarkDict.class,
-        defaultValue = "{}",
-        named = true,
-        doc = "The map of symlinks to be added to the runfiles, prefixed by workspace name."
-      ),
-      @Param(
-        name = "root_symlinks",
-        type = SkylarkDict.class,
-        defaultValue = "{}",
-        named = true,
-        doc = "The map of symlinks to be added to the runfiles."
-      )
-    },
-    useLocation = true
-  )
+      name = "runfiles",
+      doc = "Creates a runfiles object.",
+      parameters = {
+        @Param(
+            name = "files",
+            type = SkylarkList.class,
+            generic1 = FileApi.class,
+            named = true,
+            defaultValue = "[]",
+            doc = "The list of files to be added to the runfiles."),
+        // TODO(bazel-team): If we have a memory efficient support for lazy list containing
+        // NestedSets we can remove this and just use files = [file] + list(set)
+        // Also, allow empty set for init
+        @Param(
+            name = "transitive_files",
+            type = SkylarkNestedSet.class,
+            generic1 = FileApi.class,
+            noneable = true,
+            defaultValue = "None",
+            named = true,
+            doc =
+                "The (transitive) set of files to be added to the runfiles. The depset should "
+                    + "use the <code>default</code> order (which, as the name implies, is the "
+                    + "default)."),
+        @Param(
+            name = "collect_data",
+            type = Boolean.class,
+            defaultValue = "False",
+            named = true,
+            doc =
+                "Whether to collect the data "
+                    + "runfiles from the dependencies in srcs, data and deps attributes."),
+        @Param(
+            name = "collect_default",
+            type = Boolean.class,
+            defaultValue = "False",
+            named = true,
+            doc =
+                "Whether to collect the default "
+                    + "runfiles from the dependencies in srcs, data and deps attributes."),
+        @Param(
+            name = "symlinks",
+            type = SkylarkDict.class,
+            defaultValue = "{}",
+            named = true,
+            doc = "The map of symlinks to be added to the runfiles, prefixed by workspace name."),
+        @Param(
+            name = "root_symlinks",
+            type = SkylarkDict.class,
+            defaultValue = "{}",
+            named = true,
+            doc = "The map of symlinks to be added to the runfiles.")
+      },
+      useLocation = true)
   public RunfilesApi runfiles(
       SkylarkList files,
       Object transitiveFiles,
diff --git a/src/main/java/com/google/devtools/build/lib/syntax/Runtime.java b/src/main/java/com/google/devtools/build/lib/syntax/Runtime.java
index 9774ec5bb9..48129f4955 100644
--- a/src/main/java/com/google/devtools/build/lib/syntax/Runtime.java
+++ b/src/main/java/com/google/devtools/build/lib/syntax/Runtime.java
@@ -124,18 +124,18 @@ public final class Runtime {
   public static final String PKG_NAME = "PACKAGE_NAME";
 
   @SkylarkSignature(
-    name = "REPOSITORY_NAME",
-    returnType = String.class,
-    doc =
-        "<b>Deprecated. Use <a href=\"native.html#repository_name\">repository_name()</a> "
-            + "instead.</b> The name of the repository the rule or build extension is called from. "
-            + "For example, in packages that are called into existence by the WORKSPACE stanza "
-            + "<code>local_repository(name='local', path=...)</code> it will be set to "
-            + "<code>@local</code>. In packages in the main repository, it will be set to "
-            + "<code>@</code>. It can only be accessed in functions (transitively) called from "
-            + "BUILD files, i.e. it follows the same restrictions as "
-            + "<a href=\"#PACKAGE_NAME\">PACKAGE_NAME</a>"
-  )
+      name = "REPOSITORY_NAME",
+      returnType = String.class,
+      doc =
+          "<b>Deprecated. Use <a href=\"native.html#repository_name\">repository_name()</a> "
+              + "instead.</b> The name of the repository the rule or build extension is called "
+              + "from. "
+              + "For example, in packages that are called into existence by the WORKSPACE stanza "
+              + "<code>local_repository(name='local', path=...)</code> it will be set to "
+              + "<code>@local</code>. In packages in the main repository, it will be set to "
+              + "<code>@</code>. It can only be accessed in functions (transitively) called from "
+              + "BUILD files, i.e. it follows the same restrictions as "
+              + "<a href=\"#PACKAGE_NAME\">PACKAGE_NAME</a>.")
   public static final String REPOSITORY_NAME = "REPOSITORY_NAME";
 
   /** Adds bindings for False/True/None constants to the given map builder. */