search

google / starlark-go

Starlark in Go: the Starlark configuration language, implemented in Go
BSD 3-Clause "New" or "Revised" License
2.26k stars 204 forks source link

Update spec.md to correct some mistakes #428

Closed ahrtr closed 1 year ago

ahrtr commented 1 year ago

Changed items:

  1. The section Module execution has the same level as Statements, both has the prefix "##", but it's just a sub item under Statements. It seems not correct. So increased Module execution to +1 level.
  2. #name-resolution is a wrong link, so replaced it with #built-in-constants-and-functions.
  3. The lambda example has wrong output, corrected.
  4. typo, element --> tuple

There might be another error in https://github.com/google/starlark-go/blob/master/doc/spec.md#lists , I am not quite sure about it and don't know how to update it. See below,

For most types, x += y is equivalent to x = x + y, except that it evaluates x only once, that is, it allocates a new list to hold the concatenation of x and y. However, if x refers to a list, the statement does not allocate a new list but instead mutates the original list in place, similar to x.extend(y).

My immediate feeling is that the "it allocates a new list" isn't correct. The following "However, if x refers to a list" indicates that previous sentence is talking about most other types instead of list.

adonovan commented 1 year ago

Changed items:

  1. The section Module execution has the same level as Statements, both has the prefix "##", but it's just a sub item under Statements. It seems not correct. So increased Module execution to +1 level.
  2. #name-resolution is a wrong link, so replaced it with #built-in-constants-and-functions.
  3. The lambda example has wrong output, corrected.
  4. typo, element --> tuple

There might be another error in https://github.com/google/starlark-go/blob/master/doc/spec.md#lists , I am not quite sure about it and don't know how to update it. See below,

For most types, x += y is equivalent to x = x + y, except that it evaluates x only once, that is, it allocates a new list to hold the concatenation of x and y. However, if x refers to a list, the statement does not allocate a new list but instead mutates the original list in place, similar to x.extend(y).

My immediate feeling is that the "it allocates a new list" isn't correct. The following "However, if x refers to a list" indicates that previous sentence is talking about most other types instead of list.

It's correct in that the current section is about lists, but I agree it could be clearer. How about:

For most types, `x += y` is equivalent to `x = x + y`, except that it
evaluates `x` only once. However, if `x` refers to a list, the statement
`x += y` does not allocate a new list as `x = x + y` would,
but instead mutates the original list in place, similar to `x.extend(y)`.
ahrtr commented 1 year ago

It's correct in that the current section is about lists, but I agree it could be clearer. How about:

For most types, `x += y` is equivalent to `x = x + y`, except that it
evaluates `x` only once. However, if `x` refers to a list, the statement
`x += y` does not allocate a new list as `x = x + y` would,
but instead mutates the original list in place, similar to `x.extend(y)`.

Makes sense & updated & thx