diff options
Diffstat (limited to 'src/main/java/com/google/devtools/build/lib')
5 files changed, 179 insertions, 20 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/FileTypeApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/FileTypeApi.java index 83faf7fd61..f959cbf19e 100644 --- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/FileTypeApi.java +++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/FileTypeApi.java @@ -15,10 +15,14 @@ package com.google.devtools.build.lib.skylarkbuildapi; import com.google.common.collect.ImmutableList; +import com.google.devtools.build.lib.skylarkinterface.Param; +import com.google.devtools.build.lib.skylarkinterface.ParamType; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; import com.google.devtools.build.lib.syntax.EvalException; +import com.google.devtools.build.lib.syntax.SkylarkList; +import com.google.devtools.build.lib.syntax.SkylarkNestedSet; /** * Interface for an object representing the type of file. @@ -36,8 +40,21 @@ public interface FileTypeApi<FileApiT extends FileApi> { name = "filter", doc = "Returns a list created from the elements of the parameter containing all the " - + "<a href=\"File.html\"><code>File</code></a>s that match the FileType. The parameter " - + "must be a <a href=\"depset.html\"><code>depset</code></a> or a " - + "<a href=\"list.html\"><code>list</code></a>.") + + "<a href=\"File.html\"><code>File</code></a>s that match the FileType.", + parameters = { + @Param( + name = "files", + positional = true, + named = false, + allowedTypes = { + @ParamType(type = SkylarkNestedSet.class), + @ParamType(type = SkylarkList.class) + }, + doc = "The files to match. This parameter " + + "must be a <a href=\"depset.html\"><code>depset</code></a> or a " + + "<a href=\"list.html\"><code>list</code></a>." + ) + } + ) public ImmutableList<FileApiT> filter(Object filesUnchecked) throws EvalException; } diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/RunfilesApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/RunfilesApi.java index d1d4d3c7ff..e8da9a5486 100644 --- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/RunfilesApi.java +++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/RunfilesApi.java @@ -15,6 +15,7 @@ package com.google.devtools.build.lib.skylarkbuildapi; import com.google.devtools.build.lib.collect.nestedset.NestedSet; +import com.google.devtools.build.lib.skylarkinterface.Param; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; @@ -51,7 +52,16 @@ public interface RunfilesApi { name = "merge", doc = "Returns a new runfiles object that includes all the contents of this one and the " - + "argument." + + "argument.", + parameters = { + @Param( + name = "other", + positional = true, + named = false, + type = RunfilesApi.class, + doc = "The runfiles object to merge into this." + ), + } ) public RunfilesApi merge(RunfilesApi other); } 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 12c2c523c9..cdbc310a11 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 @@ -305,8 +305,18 @@ public interface SkylarkRuleContextApi extends SkylarkValue { @SkylarkCallable( name = "tokenize", - doc = "Splits a shell command to a list of tokens.", - documented = false + doc = "Splits a shell command into a list of tokens.", + // TODO(cparsons): Look into flipping this to true. + documented = false, + parameters = { + @Param( + name = "option", + positional = true, + named = false, + type = String.class, + doc = "The string to split." + ), + } ) public SkylarkList<String> tokenize(String optionString) throws FuncallException, EvalException; @@ -316,7 +326,31 @@ public interface SkylarkRuleContextApi extends SkylarkValue { "Expands all references to labels embedded within a string for all files using a mapping " + "from definition labels (i.e. the label in the output type attribute) to files. " + "Deprecated.", - documented = false + // TODO(cparsons): Look into flipping this to true. + documented = false, + parameters = { + @Param( + name = "expression", + positional = true, + named = false, + type = String.class, + doc = "The string expression to expand." + ), + @Param( + name = "files", + positional = true, + named = false, + type = SkylarkList.class, + doc = "The list of files." + ), + @Param( + name = "label_resolver", + positional = true, + named = false, + type = Label.class, + doc = "The label resolver." + ), + } ) public String expand( @Nullable String expression, SkylarkList<Object> artifacts, Label labelResolver) @@ -338,7 +372,25 @@ public interface SkylarkRuleContextApi extends SkylarkValue { ) public FileApi newFileFromFilename(String filename) throws EvalException; - @SkylarkCallable(name = "new_file", documented = false) + @SkylarkCallable(name = "new_file", + documented = false, + parameters = { + @Param( + name = "root", + positional = true, + named = false, + type = FileRootApi.class, + doc = "The file root." + ), + @Param( + name = "filename", + positional = true, + named = false, + type = String.class, + doc = "The file name." + ), + } + ) public FileApi newFileFromRoot(FileRootApi root, String filename) throws EvalException; @SkylarkCallable( @@ -361,7 +413,33 @@ public interface SkylarkRuleContextApi extends SkylarkValue { ) public FileApi newFileFromBaseFile(FileApi baseArtifact, String newBaseName) throws EvalException; - @SkylarkCallable(name = "new_file", documented = false) + @SkylarkCallable( + name = "new_file", + documented = false, + parameters = { + @Param( + name = "root", + positional = true, + named = false, + type = FileRootApi.class, + doc = "The file root." + ), + @Param( + name = "base_file", + positional = true, + named = false, + type = FileApi.class, + doc = "The base file." + ), + @Param( + name = "suffix", + positional = true, + named = false, + type = String.class, + doc = "The filename suffix." + ), + } + ) public FileApi newFileFromRootAndBase(FileRootApi root, FileApi baseArtifact, String suffix) throws EvalException; @@ -383,7 +461,23 @@ public interface SkylarkRuleContextApi extends SkylarkValue { @SkylarkCallable( name = "check_placeholders", - documented = false + documented = false, + parameters = { + @Param( + name = "template", + positional = true, + named = false, + type = String.class, + doc = "The template." + ), + @Param( + name = "allowed_placeholders", + positional = true, + named = false, + type = SkylarkList.class, + doc = "The allowed placeholders." + ), + } ) public boolean checkPlaceholders(String template, SkylarkList<Object> allowedPlaceholders) throws EvalException; @@ -395,13 +489,7 @@ public interface SkylarkRuleContextApi extends SkylarkValue { + "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" + + "<code>$$VAR_NAME</code> expands to <code>$VAR_NAME</code>." + "Examples:" + "<pre class=language-python>\n" + "ctx.expand_make_variables(\"cmd\", \"$(MY_VAR)\", {\"MY_VAR\": \"Hi\"}) " @@ -409,7 +497,32 @@ public interface SkylarkRuleContextApi extends SkylarkValue { + "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.") + + "that this function is experimental.", + parameters = { + @Param( + name = "attribute_name", + positional = true, + named = false, + type = String.class, + doc = "The attribute name. Used for error reporting." + ), + @Param( + name = "command", + positional = true, + named = false, + type = String.class, + doc = "The expression to expand. It can contain references to " + + "\"Make variables\"." + ), + @Param( + name = "additional_substitutions", + positional = true, + named = false, + type = SkylarkDict.class, + doc = "Additional substitutions to make beyond the default make variables." + ), + } + ) public String expandMakeVariables( String attributeName, String command, final Map<String, String> additionalSubstitutions) throws EvalException; diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaProtoCommonApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaProtoCommonApi.java index 8cab6bd8e3..e8aaec8016 100644 --- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaProtoCommonApi.java +++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/java/JavaProtoCommonApi.java @@ -82,7 +82,16 @@ public interface JavaProtoCommonApi<FileT extends FileApi, name = "has_proto_sources", doc = "Returns whether the given proto_library target contains proto sources. If there are no" + " sources it means that the proto_library is an alias library, which exports its" - + " dependencies." + + " dependencies.", + parameters = { + @Param( + name = "target", + positional = true, + named = false, + type = TransitiveInfoCollectionApi.class, + doc = "The proto_library target." + ), + } ) public boolean hasProtoSources(TransitiveInfoCollectionT target); diff --git a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/repository/RepositoryPathApi.java b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/repository/RepositoryPathApi.java index c510f2f420..414153f1d5 100644 --- a/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/repository/RepositoryPathApi.java +++ b/src/main/java/com/google/devtools/build/lib/skylarkbuildapi/repository/RepositoryPathApi.java @@ -15,6 +15,7 @@ package com.google.devtools.build.lib.skylarkbuildapi.repository; import com.google.common.collect.ImmutableList; +import com.google.devtools.build.lib.skylarkinterface.Param; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory; @@ -55,7 +56,16 @@ public interface RepositoryPathApi<RepositoryPathApiT extends RepositoryPathApi< @SkylarkCallable( name = "get_child", - doc = "Append the given path to this path and return the resulted path." + doc = "Append the given path to this path and return the resulted path.", + parameters = { + @Param( + name = "child_path", + positional = true, + named = false, + type = String.class, + doc = "The path to append to this path." + ), + } ) public RepositoryPathApi<?> getChild(String childPath); |