update documentation

Author: wirthi

docs/user/NashornMigrationGuide.md

@@ -35,6 +35,10 @@ This is the case for Nashorn-specific extensions that GraalVM JavaScript does no
 Note that you have to enable [experimental options](Options.md#stable-and-experimental-options) to use this flag.
 Further note that setting this flag defeats the [secure by default](#secure-by-default) approach of GraalVM JavaScript in some cases, e.g., when operating on a legacy `ScriptEngine`.
 
+When you use the Nashorn compatibility mode, by default, ECMAScript 5 is set as compatibility level.
+You can specify a different ECMAScript version using the `js.ecmascript-version` flag; note that this might conflict with full Nashorn compatibilty.
+A code example how to set the flag is given near the end of this section.
+
 The `js.nashorn-compat` option can be set:
 1. by using a command line option:
 ```shell
@@ -55,7 +59,7 @@ try (Context context = Context.newBuilder().allowExperimentalOptions(true).optio
 java -Dpolyglot.js.nashorn-compat=true MyApplication
 ```
 
-Functionality only available under this flag includes:
+Functionality only available under the `nashorn-compat` flag includes:
 * `Java.isJavaFunction`, `Java.isJavaMethod`, `Java.isScriptObject`, `Java.isScriptFunction`
 * `new Interface|AbstractClass(fn|obj)`
 * `JavaImporter`
@@ -64,6 +68,13 @@ Functionality only available under this flag includes:
 * `load("nashorn:parser.js")`, `load("nashorn:mozilla_compat.js")`
 * `exit`, `quit`
 
+The `js.ecmascript-version` option can be set in similar fashion.
+As this is a supported option, there is no need to provide the `experimental-options` flag just for setting the `ecmascript-version`:
+1. by using a command line option:
+```shell
+js --js.ecmascript-version=2020
+```
+
 ## Nashorn Syntax Extensions
 
 [Nashorn syntax extensions](https://wiki.openjdk.java.net/display/Nashorn/Nashorn+extensions) can be enabled using the `js.syntax-extensions` experimental option.

docs/user/Options.md

@@ -39,7 +39,7 @@ The following options are currently available:
    * `--js.annex-b`: enable ECMAScript Annex B web compatibility features. Boolean value, default is `true`.
    * `--js.array-sort-inherited`: define whether `Array.protoype.sort` should sort inherited keys (implementation-defined behavior). Boolean value, default is `true`.
    * `--js.atomics`: enable *ES2017 Atomics*. Boolean value, default is `true`.
-   * `--js.ecmascript-version`: emulate a specific ECMAScript version. Integer value (`5`-`9`), default is the latest version.
+   * `--js.ecmascript-version`: emulate a specific ECMAScript version. Integer value (`5`-`13`, or `2015`-`2022`), default is the latest stable version.
    * `--js.foreign-object-prototype`: provide JavaScript's default prototype to foreign objects that mimic JavaScript's own types (foreign Arrays, Objects and Functions). Boolean value, default is `false`.
    * `--js.intl-402`: enable ECMAScript Internationalization API. Boolean value, default is `false`.
    * `--js.regexp-static-result`: provide static `RegExp` properties containing the results of the last successful match, e.g., `RegExp.$1` (legacy). Boolean value, default is `true`.
@@ -72,8 +72,7 @@ See [ScriptEngine Implementation](ScriptEngine.md) on how to use experimental op
 
 This option provides compatibility to a specific version of the ECMAScript specification.
 It expects an integer value, where both the counting version numbers (`5` to `11`) and the publication years (starting from `2015`) are supported.
-The default in the development version of GraalVM is the current draft of the specification, currently the [`ECMAScript 2021 draft specification`](https://tc39.es/ecma262/).
-Thus, starting with GraalVM 21.0.0, the default will move to the draft ECMAScript 2021 specification.
+The default in the development version of GraalVM is the [`ECMAScript 2021 specification`](https://tc39.es/ecma262/).
 GraalVM JavaScript implements some features of the future draft specification and of open proposals, if you explicitly select that version and/or enable specific experimental flags.
 For production settings, it is recommended to set the `ecmascript-version` to an existing, finalized version of the specification.
 
@@ -84,10 +83,12 @@ Available versions are:
 * `8` or `2017` for ECMAScript 2017
 * `9` or `2018` for ECMAScript 2018
 * `10` or `2019` for ECMAScript 2019
-* `11` or `2020` for ECMAScript 2020 (latest finalized version of the specification)
-* `12` or `2021` for ECMAScript 2021 (**default**, currently in draft stage)
+* `11` or `2020` for ECMAScript 2020
+* `12` or `2021` for ECMAScript 2021 (**default**, latest finalized version of the specification)
 * `13` or `2022` for ECMAScript 2022 (future changes and proposals)
 
+As of GraalVM 21.2, the flag can also be set to `latest` or `staging`, to use the latest stable version (which is the default), or the staging version including experimental functionality under development.
+
 ## intl-402
 
 This option enables ECMAScript's [Internationalization API](https://tc39.github.io/ecma402/).

docs/user/ScriptEngine.md

@@ -22,6 +22,8 @@ These options are:
 * `polyglot.js.allowHostClassLookup <boolean or Predicate<String>>`
 * `polyglot.js.allowHostClassLoading <boolean>`
 * `polyglot.js.allowAllAccess <boolean>`
+* `polyglot.js.nashorn-compat <boolean>`
+* `polyglot.js.ecmascript-version <String>`
 
 These options control the sandboxing rules applied to evaluated JavaScript code and are set to `false` by default, unless the application was started in the Nashorn compatibility mode (`--js.nashorn-compat=true`).