Display all allowed types for SkylarkSignature Params that allow multiple
types.
Fixes #921
Certain parameters, such as the `executable` and `command` parameters of
ctx.action, allow multiple types. However, the allowed types are not enumerated
in the SkylarkSignature annotation, causing the generated Skylark Library
document to not display any type information for those params.
This change adds a new field, `allowedTypes`, to `SkylarkSignature` that is a
list of `ParamType` objects. If the param can accept multiple types, then
`type` is set to `Object.class`, and `allowedTypes` is set to the list of types
that can be accepted.
--
MOS_MIGRATED_REVID=126617047
diff --git a/scripts/serve-docs.sh b/scripts/serve-docs.sh
index 811fed7..d064b3c 100755
--- a/scripts/serve-docs.sh
+++ b/scripts/serve-docs.sh
@@ -52,6 +52,7 @@
pkill -9 jekyll || true
if [ -z "$TARGET" ]; then
+ echo "Serving bazel.io site at port $PORT"
jekyll serve --detach --quiet --port $PORT --source $WORKING_DIR
else
TMP_TARGET=$(mktemp -d)
diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
index edf80da..107a9bf 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
@@ -83,7 +83,7 @@
private static void writeNavPage(String outputDir, List<SkylarkModuleDoc> navModules)
throws IOException {
- File navFile = new File(outputDir + "/" + "skylark-nav.html");
+ File navFile = new File(outputDir + "/skylark-nav.html");
Page page = TemplateEngine.newPage(DocgenConsts.SKYLARK_NAV_TEMPLATE);
page.add("modules", navModules);
page.write(navFile);
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java
index de864cc..849c276 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java
@@ -14,6 +14,7 @@
package com.google.devtools.build.docgen.skylark;
import com.google.devtools.build.lib.skylarkinterface.Param;
+import com.google.devtools.build.lib.skylarkinterface.ParamType;
/**
* A class containing the documentation for a Skylark method parameter.
@@ -38,7 +39,19 @@
*/
public String getType() {
if (param.type().equals(Object.class)) {
- return "";
+ StringBuilder sb = new StringBuilder();
+ for (int i = 0; i < param.allowedTypes().length; i++) {
+ ParamType paramType = param.allowedTypes()[i];
+ if (paramType.generic1().equals(Object.class)) {
+ sb.append(getTypeAnchor(paramType.type()));
+ } else {
+ sb.append(getTypeAnchor(paramType.type(), paramType.generic1()));
+ }
+ if (i < param.allowedTypes().length - 1) {
+ sb.append("; or ");
+ }
+ }
+ return sb.toString();
}
if (param.generic1().equals(Object.class)) {
return getTypeAnchor(param.type());
@@ -51,11 +64,11 @@
return method;
}
- public String getName() {
+ @Override public String getName() {
return param.name();
}
- public String getDocumentation() {
+ @Override public String getDocumentation() {
return param.doc();
}
}
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/skylark-library.vm b/src/main/java/com/google/devtools/build/docgen/templates/skylark-library.vm
index 83f6540..b3a42da 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/skylark-library.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/skylark-library.vm
@@ -23,7 +23,7 @@
#if ($method.documented())
<h2 id="${method.name}">${method.name}</h2>
#if (!$method.signature.isEmpty())
- <p><pre>${method.signature}</pre></p>
+ <p><pre class="rule-signature">${method.signature}</pre></p>
#end
${method.documentation}
diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
index de3dfd6..2d10af4 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleImplementationFunctions.java
@@ -42,6 +42,7 @@
import com.google.devtools.build.lib.packages.Attribute.ConfigurationTransition;
import com.google.devtools.build.lib.packages.AttributeMap;
import com.google.devtools.build.lib.skylarkinterface.Param;
+import com.google.devtools.build.lib.skylarkinterface.ParamType;
import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature;
import com.google.devtools.build.lib.syntax.BuiltinFunction;
import com.google.devtools.build.lib.syntax.Environment;
@@ -79,23 +80,22 @@
/**
* A Skylark built-in function to create and register a SpawnAction using a
* dictionary of parameters:
- * createSpawnAction(
- * inputs = [input1, input2, ...],
- * outputs = [output1, output2, ...],
- * executable = executable,
- * arguments = [argument1, argument2, ...],
- * mnemonic = 'Mnemonic',
- * command = 'command',
- * )
+ * action(
+ * inputs = [input1, input2, ...],
+ * outputs = [output1, output2, ...],
+ * executable = executable,
+ * arguments = [argument1, argument2, ...],
+ * mnemonic = 'Mnemonic',
+ * command = 'command',
+ * )
*/
@SkylarkSignature(
name = "action",
- doc =
- "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.",
+ doc = "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.",
objectType = SkylarkRuleContext.class,
returnType = Runtime.NoneType.class,
parameters = {
@@ -119,7 +119,12 @@
),
@Param(
name = "executable",
- type = Object.class, // File or PathFragment or None
+ type = Object.class,
+ allowedTypes = {
+ @ParamType(type = Artifact.class),
+ @ParamType(type = PathFragment.class),
+ @ParamType(type = Runtime.NoneType.class),
+ },
defaultValue = "None",
named = true,
positional = false,
@@ -145,14 +150,18 @@
),
@Param(
name = "command",
- type = Object.class, // string or ListOf(string) or NoneType
+ type = Object.class,
+ allowedTypes = {
+ @ParamType(type = String.class),
+ @ParamType(type = SkylarkList.class, generic1 = String.class),
+ @ParamType(type = Runtime.NoneType.class),
+ },
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."
+ 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",
@@ -161,9 +170,8 @@
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\""
+ 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",
@@ -189,8 +197,7 @@
defaultValue = "None",
named = true,
positional = false,
- doc =
- "information for scheduling the action. See "
+ doc = "information for scheduling the action. See "
+ "<a href=\"/docs/be/common-definitions.html#common.tags\">tags</a> for useful keys."
),
@Param(
@@ -200,9 +207,8 @@
defaultValue = "None",
named = true,
positional = false,
- doc =
- "sets the map of input manifests files; "
- + "they are typically generated by resolve_command"
+ doc = "sets the map of input manifests files; "
+ + "they are typically generated by resolve_command"
)
},
useLocation = true
@@ -653,7 +659,7 @@
defaultValue = "False",
named = true,
positional = false,
- doc = "shall we expand $(location) variables? "
+ doc = "shall we expand $(location) variables? "
+ "See <a href=\"#expand_location\">ctx.expand_location()</a> for more details."
),
@Param(
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkinterface/Param.java b/src/main/java/com/google/devtools/build/lib/skylarkinterface/Param.java
index 4bbf10a..0c1c054 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkinterface/Param.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkinterface/Param.java
@@ -45,6 +45,12 @@
Class<?> type() default Object.class;
/**
+ * List of allowed types for the parameter if multiple types are allowed, and {@link #type()} is
+ * set to Object.class.
+ */
+ ParamType[] allowedTypes() default {};
+
+ /**
* When {@link #type()} is a generic type (e.g.,
* {@link com.google.devtools.build.lib.syntax.SkylarkList}), specify the type parameter (e.g.
* {@link String}.class} along with {@link com.google.devtools.build.lib.syntax.SkylarkList} for
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkinterface/ParamType.java b/src/main/java/com/google/devtools/build/lib/skylarkinterface/ParamType.java
new file mode 100644
index 0000000..0e4cfb9
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/skylarkinterface/ParamType.java
@@ -0,0 +1,37 @@
+// Copyright 2016 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package com.google.devtools.build.lib.skylarkinterface;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+/**
+ * An annotation for parameter types for Skylark built-in functions.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ParamType {
+ /**
+ * The Java class of the type, e.g. {@link String}.class or
+ * {@link com.google.devtools.build.lib.syntax.SkylarkList}.class.
+ */
+ Class<?> type() default Object.class;
+
+ /**
+ * When {@link #type()} is a generic type (e.g.,
+ * {@link com.google.devtools.build.lib.syntax.SkylarkList}), specify the type parameter (e.g.
+ * {@link String}.class} along with {@link com.google.devtools.build.lib.syntax.SkylarkList} for
+ * {@link #type()} to specify a list of strings).
+ */
+ Class<?> generic1() default Object.class;
+}
