Some documentation updates for Lua 5.5 (#1159)

* docs: demonstrate union type inference in else
* docs: reflect Lua 5.5 compiler options and variable attributes
* docs: 5.5-style named varags (introduced in #1122)
* docs: missing word
* docs: named varargs should always be read-only (see #1160)

Author: bjornbm

docs/src/compiler_options.md

@@ -24,7 +24,7 @@ return {
 | `-I --include-dir`   | `include_dir`              | `{string}` | `check` `gen` `run`  | Prepend this directory to the module search path.
 |                      | `source_dir`               | `string`   | `check` `gen` `run`  | Set the project source directory and add it to the module search path.
 | `--gen-compat`       | `gen_compat`               | `string`   | `gen` `run`          | Generate compatibility code for targeting different Lua VM versions. See [below](#generated-code) for details.
-| `--gen-target`       | `gen_target`               | `string`   | `gen` `run`          | Minimum targeted Lua version for generated code. Options are `5.1`, `5.3` and `5.4`. See [below](#generated-code) for details.
+| `--gen-target`       | `gen_target`               | `string`   | `gen` `run`          | Minimum targeted Lua version for generated code. Options are `5.1`, `5.3`, `5.4` and `5.5`. See [below](#generated-code) for details.
 | `--keep-hashbang`    |                            |            | `gen`                | Preserve hashbang line (`#!`) at the top of file if present.
 | `-p --pretend`       |                            |            | `gen`                | Don't compile/write to any files, but type check and log what files would be written to.
 | `--wdisable`         | `disable_warnings`         | `{string}` | `check` `run`        | Disable the given warnings.
@@ -39,7 +39,7 @@ such as `src` without repeating that directory in `include_dir`; any explicit
 
 ### Generated code
 
-Teal is a Lua dialect that most closely resembles Lua 5.3-5.4, but it is able
+Teal is a Lua dialect that most closely resembles Lua 5.3–5.5, but it is able
 to target Lua 5.1 (including LuaJIT) and Lua 5.2 as well. The compiler attempts
 to produce code that, given an input `.tl` file, generates the same behavior
 on various Lua versions.
@@ -60,7 +60,7 @@ library for bitwise operators.
 
 Using `5.3`, Teal will generate code using the native `//` and bitwise operators.
 
-The option `5.4` is equivalent to `5.3`, but it also allows using the `<close>`
+The options `5.4` and `5.5` are equivalent to `5.3`, but also allow using the `<close>`
 variable annotation. Since that is incompatible with other Lua versions, using
 this option requires using `--gen-compat=off`.
 
@@ -76,7 +76,7 @@ target implicitly.
 
 If set explicitly via the `--gen-target` flag of the `tl` CLI (or the equivalent
 options in the programmatic API), the generated code will target the Lua
-version requested: 5.1, 5.3 or 5.4.
+version requested: 5.1, 5.3, 5.4 or 5.5.
 
 If the code generation target is not set explicitly via `--gen-target`, Teal
 will target the Lua version most compatible with the version of the Lua VM

docs/src/functions.md

@@ -38,7 +38,7 @@ argument type itself.
 
 You can declare functions that generate iterators which can be used in
 `for` statements: the function needs to produce another function that iterates.
-This is an example [taken the book "Programming in Lua"](https://www.lua.org/pil/7.1.html):
+This is an example [taken from the book "Programming in Lua"](https://www.lua.org/pil/7.1.html):
 
 ```lua
 local function allwords(): (function(): string)
@@ -150,6 +150,15 @@ end
 test(1, 2, 3)
 ```
 
+Named vararg tables, as introduced in [Lua 5.5](https://www.lua.org/manual/5.5/manual.html#3.4.11),
+are supported by Teal:
+
+```lua
+local function test(...args: boolean): integer, boolean
+   return args.n, args[1]
+end
+```
+
 In case your function returns a variable amount of values, you may also declare
 variadic return types by using the `type...` syntax:
 

docs/src/tuples.md

@@ -28,7 +28,7 @@ local x = p1[my_number] -- => x is a string | number union
 if x is string then
    print("Name is " .. x .. "!")
 else
-   print("Age is " .. x)
+   print("Age is " .. x * 12 .. " months.")
 end
 ```
 

docs/src/variable_attributes.md

@@ -7,8 +7,8 @@ from Lua 5.4. They are:
 
 The `<const>` annotation works in Teal like it does in Lua 5.4 (it works at
 compile time, even if you're running a different version of Lua). Do note
-however that this is annotation for variables, and not values: the contents of a
-value set to a const variable are not constant.
+however that, just like in Lua, this is annotation for variables, and not values:
+the contents of a value set to a const variable are not constant.
 
 ```lua
 local xs <const> = {1,2,3}
@@ -18,10 +18,10 @@ xs = {} -- Error! can't replace the array in variable xs
 
 ### To-be-closed variables
 
-The `<close>` annotation from Lua 5.4 is only supported in Teal if your code
-generation target is Lua 5.4 (see the [compiler options](compiler_options.md)
+The `<close>` annotation introduced in Lua 5.4 is only supported in Teal if your code
+generation target is Lua 5.4 or greater (see the [compiler options](compiler_options.md)
 documentation for details on code generation targets). These work just
-[like they do in Lua 5.4](https://www.lua.org/manual/5.4/manual.html#3.3.8).
+[like they do in Lua 5.4+](https://www.lua.org/manual/5.4/manual.html#3.3.8).
 
 ```lua
 local contents = {}