diff options
author | Sam Rawlins <srawlins@google.com> | 2018-06-07 07:25:49 -0700 |
---|---|---|
committer | Copybara-Service <copybara-piper@google.com> | 2018-06-07 07:27:12 -0700 |
commit | 71d0f6ca22419d928078ba3eb6fecfc80043e018 (patch) | |
tree | eed94e0c28df89425b2e5c14586dddd92599ded4 /src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java | |
parent | c62d2271105ddeba2e738514f8ada38358493bc7 (diff) |
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
Diffstat (limited to 'src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java')
-rw-r--r-- | src/main/java/com/google/devtools/build/lib/skylarkbuildapi/SkylarkActionFactoryApi.java | 679 |
1 files changed, 328 insertions, 351 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 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, |