diff options
6 files changed, 26 insertions, 14 deletions
diff --git a/site/docs/skylark/concepts.md b/site/docs/skylark/concepts.md index 887a6bd2eb..cfb36d2f0e 100644 --- a/site/docs/skylark/concepts.md +++ b/site/docs/skylark/concepts.md @@ -89,6 +89,11 @@ Some differences with Python should be noted: * Dictionary assignment has slightly different semantics: `d["x"] = y` is syntactic sugar for `d = d + {"x": y}` or `d += {"x": y}`. +* Dictionaries have deterministic order when iterating (sorted by key). + +* Sets use a custom order when iterating (see + [documentation](library.html#modules._top_level.set)). + * Recursion is not allowed. The following Python features are not supported: diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md index 92c8239eb2..ef2d18cd1e 100644 --- a/site/docs/skylark/rules.md +++ b/site/docs/skylark/rules.md @@ -12,7 +12,7 @@ it in a global variable. [See example](cookbook.md#empty). Attributes ---------- -An attribute is a rule argument, such as `srcs` or `deps`. You have to list +An attribute is a rule argument, such as `srcs` or `deps`. You must list the attributes and their type when you define a rule. ```python @@ -29,7 +29,7 @@ If an attribute starts with `_`, it is private and users cannot set it. It is useful in particular for label attributes (your rule will have an implicit dependency on this label). -The following attributes are implicitely added to every rule: `name`, +The following attributes are implicitly added to every rule: `name`, `visibility`, `deprecation`, `tags`, `testonly`, `features`. To access an attribute, use `ctx.attr.<attribute_name>`. The name and the 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 8de762c0be..9aa630717b 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 @@ -689,7 +689,7 @@ public class MethodLibrary { @SkylarkSignature(name = "bool", returnType = Boolean.class, doc = "Converts an object to boolean. " + "It returns False if the object is None, False, an empty string, the number 0, or an " - + "empty collection. Otherwise, it returns True. Similarly to Python <code>bool</code> " + + "empty collection. Otherwise, it returns True. As in Python, <code>bool</code> " + "is also a type.", mandatoryPositionals = {@Param(name = "x", doc = "The variable to convert.")}) private static BuiltinFunction bool = new BuiltinFunction("bool") { @@ -766,9 +766,9 @@ public class MethodLibrary { }; @SkylarkSignature(name = "enumerate", returnType = SkylarkList.class, - doc = "Return a list of pairs (two-element lists), with the index (int) and the item from" + doc = "Return a list of pairs (two-element tuples), with the index (int) and the item from" + " the input list.\n<pre class=\"language-python\">" - + "enumerate([24, 21, 84]) == [[0, 24], [1, 21], [2, 84]]</pre>\n", + + "enumerate([24, 21, 84]) == [(0, 24), (1, 21), (2, 84)]</pre>\n", mandatoryPositionals = {@Param(name = "list", type = SkylarkList.class, doc = "input list")}, useLocation = true) private static BuiltinFunction enumerate = new BuiltinFunction("enumerate") { @@ -880,13 +880,14 @@ public class MethodLibrary { @SkylarkSignature(name = "getattr", doc = "Returns the struct's field of the given name if exists, otherwise <code>default</code>" - + " if specified, otherwise rasies an error. For example, <code>getattr(x, \"foobar\")" - + "</code> is equivalent to <code>x.foobar</code>." - + "Example:<br>" + + " 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." + + "<br>" + "<pre class=\"language-python\">getattr(ctx.attr, \"myattr\")\n" + "getattr(ctx.attr, \"myattr\", \"mydefault\")</pre>", mandatoryPositionals = { - @Param(name = "object", doc = "The struct which's field is accessed."), + @Param(name = "object", doc = "The struct whose field is accessed."), @Param(name = "name", doc = "The name of the struct field.")}, optionalPositionals = { @Param(name = "default", defaultValue = "None", @@ -1041,8 +1042,10 @@ public class MethodLibrary { + "Strings are iterable and support the <code>in</code> operator. Examples:<br>" + "<pre class=\"language-python\">\"a\" in \"abc\" # evaluates as True\n" + "x = []\n" - + "for s in \"abc\":\n" - + " x += [s] # x == [\"a\", \"b\", \"c\"]</pre>") + + "for s in \"abc\":\n" + + " x += [s] # x == [\"a\", \"b\", \"c\"]</pre>\n" + + "Implicit concatenation of strings is not allowed; use the <code>+</code> " + + "operator instead.") public static final class StringModule {} /** diff --git a/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java b/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java index 1965b9d91c..53cacb1227 100644 --- a/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java +++ b/src/main/java/com/google/devtools/build/lib/packages/SkylarkNativeModule.java @@ -71,7 +71,7 @@ public class SkylarkNativeModule { + "The label can be referenced in <code>visibility</code> attributes.", mandatoryNamedOnly = { @Param(name = "name", type = String.class, - doc = "A unique name for this rule.")}, + doc = "The unique name for this rule.")}, optionalNamedOnly = { @Param(name = "packages", type = SkylarkList.class, generic1 = String.class, defaultValue = "[]", 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 f436b1d06b..797c2bfaa2 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 @@ -196,7 +196,11 @@ public class SkylarkRuleClassFunctions { "dictionary to declare all the attributes of the rule. It maps from an attribute name " + "to an attribute object (see <a href=\"#modules.attr\">attr</a> module). " + "Attributes starting with <code>_</code> are private, and can be used to add " - + "an implicit dependency on a label."), + + "an implicit dependency on a label. The attribute <code>name</code> is implicitly " + + "added and must not be specified. Attributes <code>visibility</code>, " + + "<code>deprecation</code>, <code>tags</code>, <code>testonly</code>, and " + + "<code>features</code> are implicitly added and might be overriden."), + // TODO(bazel-team): need to give the types of these builtin attributes @Param(name = "outputs", type = Map.class, callbackEnabled = true, noneable = true, defaultValue = "None", doc = "outputs of this rule. " + "It is a dictionary mapping from string to a template name. " 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 91a0e81a65..e671ad1eec 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 @@ -471,7 +471,7 @@ public final class SkylarkRuleContext { @SkylarkCallable(doc = "Returns a string after expanding all references to \"Make variables\". The variables " - + "have to have the following format: <code>$(VAR_NAME)</code>. Also, <code>$$VAR_NAME" + + "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" |