diff options
8 files changed, 54 insertions, 51 deletions
diff --git a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java index f6e99dc186..1166cffd8e 100644 --- a/src/main/java/com/google/devtools/build/lib/actions/Artifact.java +++ b/src/main/java/com/google/devtools/build/lib/actions/Artifact.java @@ -209,26 +209,24 @@ public class Artifact implements FileType.HasFilename, ActionInput { return path; } - /** * Returns the directory name of this artifact, similar to dirname(1). - * + * * <p> The directory name is always a relative path to the execution directory. */ - @SkylarkCallable(name = "dirname", structField = true, - doc = "The directory name of this artifact.") + @SkylarkCallable(name = "dirname", structField = true, + doc = "The name of the directory containing this file.") public final String getDirname() { PathFragment parent = getExecPath().getParentDirectory(); - return (parent == null) ? "/" : parent.getSafePathString(); } - + /** * Returns the base file name of this artifact, similar to basename(1). */ @Override @SkylarkCallable(name = "basename", structField = true, - doc = "The base file name of this artifact.") + doc = "The base file name of this file.") public final String getFilename() { return getExecPath().getBaseName(); } @@ -247,7 +245,7 @@ public class Artifact implements FileType.HasFilename, ActionInput { * for source artifacts if created without specifying the owner, or for special derived artifacts, * such as target completion middleman artifacts, build info artifacts, and the like. * - * <p>When deserializing artifacts we end up with a dummy owner. In that case, + * <p>When deserializing artifacts we end up with a dummy owner. In that case, * it must be set using {@link #setArtifactOwner} before this method is called. */ public final ArtifactOwner getArtifactOwner() { diff --git a/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java b/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java index b4d7047394..ac83eca8cc 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java @@ -259,7 +259,7 @@ public final class Runfiles { */ @SkylarkCallable( name = "files", - doc = "Returns the set of runfiles as artifacts", + doc = "Returns the set of runfiles as files", structField = true ) public NestedSet<Artifact> getArtifacts() { diff --git a/src/main/java/com/google/devtools/build/lib/packages/MethodLibrary.java b/src/main/java/com/google/devtools/build/lib/packages/MethodLibrary.java index 50751b7db4..c99f4dd256 100644 --- a/src/main/java/com/google/devtools/build/lib/packages/MethodLibrary.java +++ b/src/main/java/com/google/devtools/build/lib/packages/MethodLibrary.java @@ -859,7 +859,8 @@ public class MethodLibrary { }; @SkylarkSignature(name = "str", returnType = String.class, doc = - "Converts any object to string. This is useful for debugging.", + "Converts any object to string. This is useful for debugging." + + "<pre class=\"language-python\">str(\"ab\") == \"ab\"</pre>", mandatoryPositionals = {@Param(name = "x", doc = "The object to convert.")}) private static BuiltinFunction str = new BuiltinFunction("str") { public String invoke(Object x) { @@ -868,7 +869,8 @@ public class MethodLibrary { }; @SkylarkSignature(name = "repr", returnType = String.class, doc = - "Converts any object to a string representation. This is useful for debugging.", + "Converts any object to a string representation. This is useful for debugging.<br>" + + "<pre class=\"language-python\">str(\"ab\") == \\\"ab\\\"</pre>", mandatoryPositionals = {@Param(name = "x", doc = "The object to convert.")}) private static BuiltinFunction repr = new BuiltinFunction("repr") { public String invoke(Object x) { @@ -877,10 +879,9 @@ public class MethodLibrary { }; @SkylarkSignature(name = "bool", returnType = Boolean.class, - doc = "Converts an object to boolean. " + doc = "Constructor for the bool type. " + "It returns False if the object is None, False, an empty string, the number 0, or an " - + "empty collection. Otherwise, it returns True. As in Python, <code>bool</code> " - + "is also a type.", + + "empty collection. Otherwise, it returns True.", mandatoryPositionals = {@Param(name = "x", doc = "The variable to convert.")}) private static BuiltinFunction bool = new BuiltinFunction("bool") { public Boolean invoke(Object x) throws EvalException { @@ -917,12 +918,12 @@ public class MethodLibrary { }; @SkylarkSignature(name = "struct", returnType = SkylarkClassObject.class, doc = - "Creates an immutable struct using the keyword arguments as fields. It is used to group " + "Creates an immutable struct using the keyword arguments as attributes. It is used to group " + "multiple values together.Example:<br>" + "<pre class=\"language-python\">s = struct(x = 2, y = 3)\n" - + "return s.x + s.y # returns 5</pre>", + + "return s.x + getattr(s, \"y\") # returns 5</pre>", extraKeywords = { - @Param(name = "kwargs", doc = "the struct fields")}, + @Param(name = "kwargs", doc = "the struct attributes")}, useLocation = true) private static BuiltinFunction struct = new BuiltinFunction("struct") { @SuppressWarnings("unchecked") @@ -1061,12 +1062,12 @@ public class MethodLibrary { * Returns true if the object has a field of the given name, otherwise false. */ @SkylarkSignature(name = "hasattr", returnType = Boolean.class, - doc = "Returns True if the object <code>x</code> has a field of the given <code>name</code>, " - + "otherwise False. Example:<br>" + doc = "Returns True if the object <code>x</code> has an attribute of the given " + + "<code>name</code>, otherwise False. Example:<br>" + "<pre class=\"language-python\">hasattr(ctx.attr, \"myattr\")</pre>", mandatoryPositionals = { - @Param(name = "object", doc = "The object to check."), - @Param(name = "name", type = String.class, doc = "The name of the field.")}, + @Param(name = "x", doc = "The object to check."), + @Param(name = "name", type = String.class, doc = "The name of the attribute.")}, useLocation = true, useEnvironment = true) private static final BuiltinFunction hasattr = new BuiltinFunction("hasattr") { public Boolean invoke(Object obj, String name, @@ -1091,17 +1092,17 @@ public class MethodLibrary { doc = "Returns the struct's field of the given name if exists, otherwise <code>default</code>" + " if specified, otherwise raises an error. For example, <code>getattr(x, \"foobar\")" + "</code> is equivalent to <code>x.foobar</code>, except that it returns " - + "<code>default</code> for a non-existant attribute instead of raising an error." + + "<code>default</code> for a non-existent attribute instead of raising an error." + "<br>" + "<pre class=\"language-python\">getattr(ctx.attr, \"myattr\")\n" + "getattr(ctx.attr, \"myattr\", \"mydefault\")</pre>", mandatoryPositionals = { - @Param(name = "object", doc = "The struct whose field is accessed."), - @Param(name = "name", doc = "The name of the struct field.")}, + @Param(name = "x", doc = "The struct whose attribute is accessed."), + @Param(name = "name", doc = "The name of the struct attribute.")}, optionalPositionals = { @Param(name = "default", defaultValue = "None", doc = "The default value to return in case the struct " - + "doesn't have a field of the given name.")}, + + "doesn't have an attribute of the given name.")}, useLocation = true) private static final BuiltinFunction getattr = new BuiltinFunction("getattr") { public Object invoke(Object obj, String name, Object defaultValue, @@ -1111,7 +1112,7 @@ public class MethodLibrary { if (defaultValue != Environment.NONE) { return defaultValue; } else { - throw new EvalException(loc, Printer.format("Object of type '%s' has no field %r", + throw new EvalException(loc, Printer.format("Object of type '%s' has no attribute %r", EvalUtils.getDataTypeName(obj), name)); } } @@ -1120,9 +1121,9 @@ public class MethodLibrary { }; @SkylarkSignature(name = "dir", returnType = SkylarkList.class, - doc = "Returns a list strings: the names of the fields and " + doc = "Returns a list strings: the names of the attributes and " + "methods of the parameter object.", - mandatoryPositionals = {@Param(name = "object", doc = "The object to check.")}, + mandatoryPositionals = {@Param(name = "x", doc = "The object to check.")}, useLocation = true, useEnvironment = true) private static final BuiltinFunction dir = new BuiltinFunction("dir") { public SkylarkList invoke(Object object, @@ -1145,7 +1146,7 @@ public class MethodLibrary { @SkylarkSignature(name = "type", returnType = String.class, doc = "Returns the type name of its argument.", - mandatoryPositionals = {@Param(name = "object", doc = "The object to check type of.")}) + mandatoryPositionals = {@Param(name = "x", doc = "The object to check type of.")}) private static final BuiltinFunction type = new BuiltinFunction("type") { public String invoke(Object object) { // There is no 'type' type in Skylark, so we return a string with the type name. @@ -1154,14 +1155,16 @@ public class MethodLibrary { }; @SkylarkSignature(name = "fail", - doc = "Raises an error that cannot be intercepted.", + doc = "Raises an error that cannot be intercepted. It can be used anywhere, " + + "both in the loading phase and in the analysis phase.", returnType = Environment.NoneType.class, mandatoryPositionals = { @Param(name = "msg", type = String.class, doc = "Error message to display for the user")}, optionalPositionals = { @Param(name = "attr", type = String.class, noneable = true, defaultValue = "None", - doc = "The name of the attribute that caused the error")}, + doc = "The name of the attribute that caused the error. This is used only for " + + "error reporting.")}, useLocation = true) private static final BuiltinFunction fail = new BuiltinFunction("fail") { public Environment.NoneType invoke(String msg, Object attr, @@ -1249,7 +1252,7 @@ public class MethodLibrary { + "y = \"hello\"[1:-1] # \"ell\"\n" + "z = \"hello\"[:4] # \"hell\"</pre>" + "Strings are iterable and support the <code>in</code> operator. Examples:<br>" - + "<pre class=\"language-python\">\"a\" in \"abc\" # evaluates as True\n" + + "<pre class=\"language-python\">\"bc\" in \"abcd\" # evaluates to True\n" + "x = []\n" + "for s in \"abc\":\n" + " x += [s] # x == [\"a\", \"b\", \"c\"]</pre>\n" diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java index f465af18d7..fc85bb1874 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkAttr.java @@ -55,7 +55,7 @@ import java.util.Map; onlyLoadingPhase = true, doc = "Module for creating new attributes. " - + "They are only for use with the <code>rule</code> function." + + "They are only for use with the <a href=\"#modules._top_level.rule\">rule</a> function." ) public final class SkylarkAttr { @@ -75,11 +75,11 @@ public final class SkylarkAttr { "configuration of the attribute. " + "For example, use DATA_CFG or HOST_CFG."; private static final String DEFAULT_ARG = "default"; - private static final String DEFAULT_DOC = "sets the default value of the attribute."; + private static final String DEFAULT_DOC = "the default value of the attribute."; private static final String EXECUTABLE_ARG = "executable"; private static final String EXECUTABLE_DOC = - "set to True if the labels have to be executable. This means the label must refer to an " + "True if the labels have to be executable. This means the label must refer to an " + "executable file, or to a rule that outputs an executable file. Access the labels " + "with <code>ctx.executable.<attribute_name></code>."; @@ -87,11 +87,10 @@ public final class SkylarkAttr { private static final String FLAGS_DOC = "deprecated, will be removed"; private static final String MANDATORY_ARG = "mandatory"; - private static final String MANDATORY_DOC = - "set to True if users have to explicitely specify the value"; + private static final String MANDATORY_DOC = "True if the value must be explicitly specified"; private static final String NON_EMPTY_ARG = "non_empty"; - private static final String NON_EMPTY_DOC = "set to True if the attribute must not be empty"; + private static final String NON_EMPTY_DOC = "True if the attribute must not be empty"; private static final String PROVIDERS_ARG = "providers"; @@ -99,7 +98,7 @@ public final class SkylarkAttr { private static final String VALUES_ARG = "values"; private static final String VALUES_DOC = - "specify the list of allowed values for the attribute. An error is raised if any other " + "the list of allowed values for the attribute. An error is raised if any other " + "value is given."; private static boolean containsNonNoneKey(Map<String, Object> arguments, String key) { diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java index f39d2922fd..84d1ce9a87 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java @@ -188,15 +188,15 @@ public class SkylarkRuleClassFunctions { returnType = BaseFunction.class, mandatoryPositionals = { @Param(name = "implementation", type = BaseFunction.class, - doc = "the function implementing this rule, has to have exactly one parameter: " - + "<code>ctx</code>. The function is called during analysis phase for each " - + "instance of the rule. It can access the attributes provided by the user. " + doc = "the function implementing this rule, must have exactly one parameter: " + + "<a href=\"#modules.ctx\">ctx</a>. The function is called during the analysis phase " + + "for each instance of the rule. It can access the attributes provided by the user. " + "It must create actions to generate all the declared outputs.") }, optionalPositionals = { @Param(name = "test", type = Boolean.class, defaultValue = "False", doc = "Whether this rule is a test rule. " - + "If True, the rule must end with <code>_test</code> (otherwise it cannot), " + + "If True, the rule must end with <code>_test</code> (otherwise it must not), " + "and there must be an action that generates <code>ctx.outputs.executable</code>."), @Param(name = "attrs", type = Map.class, noneable = true, defaultValue = "None", doc = "dictionary to declare all the attributes of the rule. It maps from an attribute name " @@ -211,13 +211,13 @@ public class SkylarkRuleClassFunctions { defaultValue = "None", doc = "outputs of this rule. " + "It is a dictionary mapping from string to a template name. " + "For example: <code>{\"ext\": \"${name}.ext\"}</code>. <br>" - + "The dictionary key becomes a field in <code>ctx.outputs</code>. " + + "The dictionary key becomes an attribute in <code>ctx.outputs</code>. " // TODO(bazel-team): Make doc more clear, wrt late-bound attributes. + "It may also be a function (which receives <code>ctx.attr</code> as argument) " + "returning such a dictionary."), @Param(name = "executable", type = Boolean.class, defaultValue = "False", - doc = "whether this rule always outputs an executable of the same name or not. If " - + "True, there must be an action that generates <code>ctx.outputs.executable</code>."), + doc = "whether this rule is marked as executable or not. If True, " + + "there must be an action that generates <code>ctx.outputs.executable</code>."), @Param(name = "output_to_genfiles", type = Boolean.class, defaultValue = "False", doc = "If true, the files will be generated in the genfiles directory instead of the " + "bin directory. This is used for compatibility with existing rules.")}, @@ -350,6 +350,7 @@ public class SkylarkRuleClassFunctions { @SkylarkSignature(name = "Label", doc = "Creates a Label referring to a BUILD target. Use " + "this function only when you want to give a default value for the label attributes. " + + "The argument must refer to an absolute label. " + "Example: <br><pre class=language-python>Label(\"//tools:default\")</pre>", returnType = Label.class, mandatoryPositionals = {@Param(name = "label_string", type = String.class, diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java index 2823f9632a..45d64f07d6 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java +++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java @@ -274,7 +274,7 @@ public final class SkylarkRuleContext { @SkylarkCallable(name = "executable", structField = true, doc = "A <code>struct</code> containing executable files defined in label type " + "attributes marked as <code>executable=True</code>. The struct fields correspond " - + "to the attribute names. The struct value is always a <code>file</code>s or " + + "to the attribute names. Each struct value is always a <code>file</code>s or " + "<code>None</code>. If an optional attribute is not specified in the rule " + "then the corresponding struct value is <code>None</code>. If a label type is not " + "marked as <code>executable=True</code>, no corresponding struct field is generated.") @@ -345,12 +345,12 @@ public final class SkylarkRuleContext { + " The struct is generated the following way:<br>" + "<ul><li>If the rule is marked as <code>executable=True</code> the struct has an " + "\"executable\" field with the rules default executable <code>file</code> value." - + "<li>For every entry in the rule's <code>outputs</code> dict a field is generated with " + + "<li>For every entry in the rule's <code>outputs</code> dict an attr is generated with " + "the same name and the corresponding <code>file</code> value." - + "<li>For every output type attribute a struct field is generated with the " + + "<li>For every output type attribute a struct attribute is generated with the " + "same name and the corresponding <code>file</code> value or <code>None</code>, " + "if no value is specified in the rule." - + "<li>For every output list type attribute a struct field is generated with the " + + "<li>For every output list type attribute a struct attribute is generated with the " + "same name and corresponding <code>list</code> of <code>file</code>s value " + "(an empty list if no value is specified in the rule).</ul>") public SkylarkClassObject outputs() { diff --git a/src/main/java/com/google/devtools/build/lib/syntax/Environment.java b/src/main/java/com/google/devtools/build/lib/syntax/Environment.java index cea5ea56bd..3de17c8e5a 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/Environment.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/Environment.java @@ -47,6 +47,8 @@ public class Environment { @SkylarkSignature(name = "PACKAGE_NAME", returnType = String.class, doc = "The name of the package the rule or build extension is called from. " + + "For example, in the BUILD file <code>some/package/BUILD</code>, its value " + + "will be <code>some/package</code>. " + "This variable is special, because its value comes from outside of the extension " + "module (it comes from the BUILD file), so it can only be accessed in functions " + "(transitively) called from BUILD files. For example:<br>" diff --git a/src/test/java/com/google/devtools/build/lib/syntax/SkylarkEvaluationTest.java b/src/test/java/com/google/devtools/build/lib/syntax/SkylarkEvaluationTest.java index 88f4503462..f43232a2ca 100644 --- a/src/test/java/com/google/devtools/build/lib/syntax/SkylarkEvaluationTest.java +++ b/src/test/java/com/google/devtools/build/lib/syntax/SkylarkEvaluationTest.java @@ -856,7 +856,7 @@ public class SkylarkEvaluationTest extends EvaluationTest { @Test public void testGetattrNoAttr() throws Exception { - new SkylarkTest().testIfExactError("Object of type 'struct' has no field \"b\"", + new SkylarkTest().testIfExactError("Object of type 'struct' has no attribute \"b\"", "s = struct(a='val')", "getattr(s, 'b')"); } |