diff options
7 files changed, 97 insertions, 34 deletions
diff --git a/scripts/serve-docs.sh b/scripts/serve-docs.sh index 811fed7cbf..d064b3cdf1 100755 --- a/scripts/serve-docs.sh +++ b/scripts/serve-docs.sh @@ -52,6 +52,7 @@ function build_and_serve { 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 edf80dad68..107a9bf053 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 @@ public final class SkylarkDocumentationProcessor { 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 de864cc5c2..849c276fa4 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 final class SkylarkParamDoc extends SkylarkDoc { */ 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 @@ public final class SkylarkParamDoc extends SkylarkDoc { 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 83f65403e6..b3a42dad61 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 @@ ${module.documentation} #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 de3dfd62c9..2d10af4e0e 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; 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 @@ public class SkylarkRuleImplementationFunctions { /** * 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 @@ public class SkylarkRuleImplementationFunctions { ), @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 @@ public class SkylarkRuleImplementationFunctions { ), @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 @@ public class SkylarkRuleImplementationFunctions { 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 @@ public class SkylarkRuleImplementationFunctions { 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 @@ public class SkylarkRuleImplementationFunctions { 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 @@ public class SkylarkRuleImplementationFunctions { 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 4bbf10ad5d..0c1c0540e1 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 @@ public @interface Param { 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 0000000000..0e4cfb9462 --- /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; +} |