fewer words, easier reading Incorporating feedback from [PR 9310](https://github.com/bazelbuild/bazel/pull/9310). Closes #9326. PiperOrigin-RevId: 267268785
diff --git a/site/docs/skylark/language.md b/site/docs/skylark/language.md index 79c08f0..3650d36 100644 --- a/site/docs/skylark/language.md +++ b/site/docs/skylark/language.md
@@ -31,7 +31,7 @@ fizz_buzz(20) ``` -Starlark's semantics can differ from Python, and behavioral differences are +Starlark's semantics can differ from Python, but behavioral differences are rare, except for cases where Starlark raises an error. The following Python types are supported: @@ -72,7 +72,7 @@ evaluation for `foo.bzl` completes, the environment contains an immutable entry, `var`, with the value `[5]`. -When another, `bar.bzl` loads symbols from `foo.bzl`, loaded values remain +When another `bar.bzl` loads symbols from `foo.bzl`, loaded values remain immutable. For this reason, the following code in `bar.bzl` is illegal: ```python @@ -84,8 +84,9 @@ fct() # runtime error, fct() attempts to modify a frozen list ``` -Just like the above example using `bzl` files, values returned by rules are -immutable too. +Global variables defined in `bzl` files cannot be changed outside of the +`bzl` file that defined them. Just like the above example using `bzl` files, +values returned by rules are immutable. ## Differences between BUILD and .bzl files @@ -128,9 +129,8 @@ * Dictionary literals cannot have duplicated keys. For example, this is an error: `{"a": 4, "b": 7, "a": 1}`. -* The variable used in a comprehension may not be used after the comprehension. - This is stricter than Python 2 and Python 3, which have different behavior - (shadowing vs reassignment). +* The identifier used in a comprehension may not be used after the comprehension. + This is stricter than Python 2 and Python 3. * Strings are represented with double-quotes (e.g. when you call [repr](lib/globals.html#repr)).