Update dict docs
--
PiperOrigin-RevId: 145859025
MOS_MIGRATED_REVID=145859025
diff --git a/site/versions/master/docs/skylark/concepts.md b/site/versions/master/docs/skylark/concepts.md
index 20ebb72..ca5d69d 100644
--- a/site/versions/master/docs/skylark/concepts.md
+++ b/site/versions/master/docs/skylark/concepts.md
@@ -204,44 +204,45 @@
The following items are upcoming changes.
-* Comprehensions currently "leak" the values of their loop variables into the
- surrounding scope (Python 2 semantics). This will be changed so that
- comprehension variables are local (Python 3 semantics).
+* Comprehensions currently "leak" the values of their loop variables into the
+ surrounding scope (Python 2 semantics). This will be changed so that
+ comprehension variables are local (Python 3 semantics).
-* Previously dictionaries were guaranteed to use sorted order for their keys.
- Going forward, there is no guarantee on order besides that it is
- deterministic. As an implementation matter, some kinds of dictionaries may
- continue to use sorted order while others may use insertion order.
+* Previously dictionaries were guaranteed to use sorted order for their keys.
+ Going forward, there is no guarantee on order besides that it is
+ deterministic. As an implementation matter, some kinds of dictionaries may
+ continue to use sorted order while others may use insertion order.
-* The `+=` operator and similar operators are currently syntactic sugar;
- `x += y` is the same as `x = x + y`. This will change to follow Python
- semantics, so that for mutable collection datatypes, `x += y` will be a
- mutation to the value of `x` rather than a rebinding of the variable `x`
- itself to a new value. E.g. for lists, `x += y` will be the same as
- `x.extend(y)`.
+* The `+=` operator and similar operators are currently syntactic sugar; `x +=
+ y` is the same as `x = x + y`. This will change to follow Python semantics,
+ so that for mutable collection datatypes, `x += y` will be a mutation to the
+ value of `x` rather than a rebinding of the variable `x` itself to a new
+ value. E.g. for lists, `x += y` will be the same as `x.extend(y)`.
-* The `+` operator is defined for dictionaries, returning an immutable
- concatenated dictionary created from the entries of the original
- dictionaries. This will be going away. The same result can be achieved using
- `dict(a.items() + b.items())`. Likewise, there is a `+` operator for sets that
- will be going away; users should use `|` instead.
+* The "set" datatype is being renamed to "depset" in order to avoid confusion
+ with Python's sets, which behave very differently.
-* The order comparison operators (<, <=, >=, >) are currently defined across
- different types of values, e.g., you can write `5 < 'foo'`. This will be an
- error, just like in Python 3. Note that this means you will be unable to
- sort lists that contain mixed types of values.
+* The `+` operator is defined for dictionaries, returning an immutable
+ concatenated dictionary created from the entries of the original
+ dictionaries. This will be going away. The same result can be achieved using
+ `dict(a.items() + b.items())`.
-* The structure of the set that you get back from using the `+` or `|` operator
- is changing. Previously `a + b`, where `a` is a set, would include as its
- direct items all of `a`'s direct items. Under the upcoming way, the result
- will only include `a` as a single transitive entity. This will alter the
- visible iteration order of the returned set. Most notably,
- `set([1, 2]) + set([3, 4] + set([5, 6])` will return elements in the order
- `1 2 3 4 5 6` instead of `3 4 5 6 1 2`. This change is associated with a fix
- that improves set union to be O(1) time.
+* The `|` operator is defined for depsets as a synonym for `+`. This will be
+ going away; use `+` instead.
-* The set datatype will be renamed in order to avoid confusion with Python's
- set datatype, which behaves very differently.
+* The order comparison operators (<, <=, >=, >) are currently defined across
+ different types of values, e.g., you can write `5 < 'foo'`. This will be an
+ error, just like in Python 3. Note that this means you will be unable to
+ sort lists that contain mixed types of values.
+
+* The structure of the set that you get back from using the `+` or `|`
+ operator is changing. Previously `a + b`, where `a` is a set, would include
+ as its direct items all of `a`'s direct items. Under the upcoming way, the
+ result will only include `a` as a single transitive entity. This will alter
+ the visible iteration order of the returned set. Most notably, `set([1,
+ 2]) + set([3, 4] + set([5, 6])` will return elements in the order `1 2 3 4 5
+ 6` instead of `3 4 5 6 1 2`. This change is associated with a fix that
+ improves set union to be O(1) time.
These changes concern the `load()` syntax in particular.
diff --git a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java
index 0dddafb..b2143df 100644
--- a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java
+++ b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java
@@ -1720,9 +1720,12 @@
returnType = SkylarkDict.class,
doc =
"Creates a <a href=\"dict.html\">dictionary</a> from an optional positional "
- + "argument and an optional set of keyword arguments. Values from the keyword "
- + "argument will overwrite values from the positional argument if a key appears "
- + "multiple times.",
+ + "argument and an optional set of keyword arguments. In the case where the same key "
+ + "is given multiple times, the last value will be used. Entries supplied via keyword "
+ + "arguments are considered to come after entries supplied via the positional "
+ + "argument. Note that the iteration order for dictionaries is deterministic but "
+ + "unspecified, and not necessarily related to the order in which keys are given to "
+ + "this function.",
parameters = {
@Param(
name = "args",
@@ -1730,7 +1733,7 @@
defaultValue = "[]",
doc =
"Either a dictionary or a list of entries. Entries must be tuples or lists with "
- + "exactly two elements: key, value"
+ + "exactly two elements: key, value."
),
},
extraKeywords = @Param(name = "kwargs", doc = "Dictionary of additional entries."),
diff --git a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java
index ad0a97d..d622a7c 100644
--- a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java
+++ b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkDict.java
@@ -27,22 +27,22 @@
*/
@SkylarkModule(name = "dict",
category = SkylarkModuleCategory.BUILTIN,
- doc = "A language built-in type to support dicts. "
- + "Example of dict literal:<br>"
+ doc = "A language built-in type representating a dictionary (associative mapping). "
+ + "Dictionaries may be constructed with a special literal syntax:<br>"
+ "<pre class=\"language-python\">d = {\"a\": 2, \"b\": 5}</pre>"
- + "Use brackets to access elements:<br>"
+ + "Use square brackets to access elements:<br>"
+ "<pre class=\"language-python\">e = d[\"a\"] # e == 2</pre>"
- + "Dicts support the <code>+</code> operator to concatenate two dicts. In case of multiple "
- + "keys the second one overrides the first one. Examples:<br>"
- + "<pre class=\"language-python\">"
- + "d = {\"a\" : 1} + {\"b\" : 2} # d == {\"a\" : 1, \"b\" : 2}\n"
- + "d += {\"c\" : 3} # d == {\"a\" : 1, \"b\" : 2, \"c\" : 3}\n"
- + "d = d + {\"c\" : 5} # d == {\"a\" : 1, \"b\" : 2, \"c\" : 5}</pre>"
- + "Iterating on a dict is equivalent to iterating on its keys (order is not specified).<br>"
- + "Dicts support the <code>in</code> operator, testing membership in the keyset of the dict. "
- + "Example:<br>"
- + "<pre class=\"language-python\">\"a\" in {\"a\" : 2, \"b\" : 5} # evaluates as True"
- + "</pre>")
+ + "Like lists, they can also be constructed using a comprehension syntax:<br>"
+ + "<pre class=\"language-python\">d = {i: 2*i for i in range(20)}\n"
+ + "e = d[8] # e == 16</pre>"
+ + "See also the <a href=\"globals.html#dict\">dict()</a> constructor function. "
+ + "<p>Iterating over a dict is equivalent to iterating over its keys. The <code>in</code> "
+ + "operator tests for membership in the keyset of the dict.<br>"
+ + "<pre class=\"language-python\">\"a\" in {\"a\" : 2, \"b\" : 5} # evaluates as True</pre>"
+ + "The iteration order for a dict is deterministic but not specified. When constructing a dict "
+ + "using any of the above methods, if there are two identical keys with conflicting values "
+ + "then the last value takes precedence."
+)
public final class SkylarkDict<K, V>
extends MutableMap<K, V> implements Map<K, V>, SkylarkIndexable {
