Minor documentation cleanup.

Author: woess

README.md

@@ -14,8 +14,8 @@ The goals of GraalVM JavaScript are:
 
 
 ## Getting Started
-The preferred way to run GraalVM JavaScript is from a [GraalVM](https://www.graalvm.org/downloads/).
-Starting with GraalVM for JDK 21 (23.1), GraalVM JavaScript is available as a [standalone distribution](https://github.com/oracle/graaljs/releases) and a [Maven artifact](https://central.sonatype.com/artifact/org.graalvm.polyglot/js) (but no longer as a GraalVM component).
+The preferred way to run GraalVM JavaScript (a.k.a. GraalJS) is from a [GraalVM](https://www.graalvm.org/downloads/).
+As of GraalVM for JDK 21, (23.1), GraalVM JavaScript and Node.js runtimes are available as [standalone distributions](https://github.com/oracle/graaljs/releases) and [Maven artifacts](https://central.sonatype.com/artifact/org.graalvm.polyglot/js) (but no longer as GraalVM components).
 See the documentation on the [GraalVM website](https://www.graalvm.org/latest/reference-manual/js/) for more information on how to set up GraalVM JavaScript.
 
 ### Standalone Distribution
@@ -73,7 +73,7 @@ Due to those limitations, running on a stock JVM is not a supported feature - pl
 ## Documentation
 
 Extensive documentation is available on [graalvm.org](https://www.graalvm.org/): see [Getting Started](https://www.graalvm.org/docs/getting-started/) and the more extensive [JavaScript and Node.js Reference Manual](https://www.graalvm.org/reference-manual/js/).
-In addition there is documentation in the source code repository in the [`docs`](https://github.com/graalvm/graaljs/tree/master/docs) folder, for [users](https://github.com/graalvm/graaljs/tree/master/docs/user) and [contributors](https://github.com/graalvm/graaljs/tree/master/docs/contributor).
+In addition, there is documentation in the source code repository in the [`docs`](https://github.com/graalvm/graaljs/tree/master/docs) directory, for [users](https://github.com/graalvm/graaljs/tree/master/docs/user) and [contributors](https://github.com/graalvm/graaljs/tree/master/docs/contributor).
 
 For contributors, a guide how to build GraalVM JavaScript from source code can be found in [`Building.md`](https://github.com/graalvm/graaljs/tree/master/docs/Building.md).
 

docs/user/FAQ.md

@@ -85,7 +85,7 @@ Additionally, you can upload your `package-lock.json` or `package.json` file int
 ### My application is slower on GraalVM JavaScript than on another engine
 Reason:
 * Ensure your benchmark considers warmup. During the first few iterations, GraalVM JavaScript may be slower than other engines, but after sufficient warmup, this difference should level out.
-* GraalVM JavaScript is shipped in two different standalones: Native (default) and JVM (with a `-jvm` infix). While the default _native_ mode offers faster startup and lower latency, it might exhibit slower peak performance (lower throughput) once the application is warmed up. In the _JVM_ mode, the application might need hundreds of milliseconds more to start, but typically shows better peak performance.
+* GraalVM JavaScript is shipped in two different standalones: Native (default) and JVM (with a `-jvm` infix). While the default _Native_ mode offers faster startup and lower latency, it might exhibit slower peak performance (lower throughput) once the application is warmed up. In the _JVM_ mode, the application might need hundreds of milliseconds more to start, but typically shows better peak performance.
 * Repeated execution of code via newly created `org.graalvm.polyglot.Context` is slow, despite the same code being executed every time.
 
 Solution:

docs/user/JavaScriptCompatibility.md

@@ -223,23 +223,23 @@ The Graal object is available in GraalVM JavaScript by default, unless deactivat
 ### `Graal.setUnhandledPromiseRejectionHandler(handler)`
 
 - provides the unhandled promise rejection handler when using option (`js.unhandled-rejections=handler`).
-- the handler is called with two arguments: (rejection, promise).
-- `Graal.setUnhandledPromiseRejectionHandler` can be called with null, undefined, or empty args to clear the handler.
+- the handler is called with two arguments: (rejectionReason, unhandledPromise).
+- `Graal.setUnhandledPromiseRejectionHandler` can be called with `null`, `undefined`, or empty arguments to clear the handler.
 
 ### Java
 
 The `Java` object is only available when [host class lookup](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Context.Builder.html#allowHostClassLookup-java.util.function.Predicate-) is allowed.
-In order to access Java host classes and its members, they first need to be allowed by the [host access policy](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/HostAccess.html) and when running on a Native Image, be registered for [run time reflection](https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/Reflection/).
+In order to access Java host classes and its members, they first need to be allowed by the [host access policy](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/HostAccess.html), and when running from a Native Image, be registered for [run time reflection](https://www.graalvm.org/latest/reference-manual/native-image/dynamic-features/Reflection/).
 
 Note that some functions require the Nashorn compatibility mode flag to be set.
-When running on the standalone distribution, this flag can be set with:
+When running from the JVM standalone distribution, this flag can be set with:
 ```shell
 js --experimental-options --js.nashorn-compat=true
 ```
 
 #### `Java.type(className)`
 
-Loads the specified Java class and returns a constructible object that has the static members (i.e. methods and fields) of the class and can be used with the `new` keyword to construct new instances:
+`Java.type` loads the specified Java class and returns a constructible object that has the static members (i.e. methods and fields) of the class and can be used with the `new` keyword to construct new instances:
 ```js
 var BigDecimal = Java.type('java.math.BigDecimal');
 var point1 = new BigDecimal("0.1");
@@ -253,36 +253,39 @@ console.log(new (Java.type('java.math.BigDecimal'))("1.1").pow(15));
 
 #### `Java.from(javaData)`
 
-- creates a shallow copy of the Java datastructure (Array, List) as a JavaScript array
+`Java.from` creates a shallow copy of the Java data structure (Array, List) as a JavaScript array.
 
-In many cases, this is not necessary; you can typically use the Java datastructure directly from JavaScript.
+In many cases, this is not necessary; you can typically use the Java data structure directly from JavaScript.
 
-#### `Java.to(jsData, toType)`
+#### `Java.to(jsData, javaType)`
 
-- converts the argument to a Java dataype
+`Java.to` converts the argument to the Java type.
 
-The source object `jsData` is expected to be a JavaScript array, or an object with a `length` property.
-The target `toType` can either be a String (e.g. `"int[]"`) or a type object (e.g., `Java.type("int[]")`).
+The source object `jsData` is expected to be a JavaScript array, or an array-like object with a `length` property.
+The target `javaType` can either be a String (e.g. `"int[]"`) or a type object (e.g., `Java.type("int[]")`).
 Valid target types are Java arrays.
-When no target type is provided, `Object[]` is assumed:
+When the target type is omitted, it defaults to `Object[]`.
+
 ```js
-var jsArr = ["a", "b", "c"];
-var strArrType = Java.type("java.lang.String[]");
-var javaArr = Java.to(jsArr, strArrType);
-assertEquals('class java.lang.String[]', String(javaArr.getClass()));
+var jsArray = ["a", "b", "c"];
+var stringArrayType = Java.type("java.lang.String[]");
+var javaArray = Java.to(jsArray, stringArrayType);
+assertEquals('class java.lang.String[]', String(javaArray.getClass()));
+var javaArray = Java.to(jsArray);
+assertEquals('class java.lang.Object[]', String(javaArray.getClass()));
 ```
 
 The conversion methods as defined by ECMAScript (e.g., `ToString` and `ToDouble`) are executed when a JavaScript value has to be converted to a Java type.
-Lossy conversion is disallowed and results in a TypeError.
+Lossy conversion is disallowed and results in a `TypeError`.
 
 #### `Java.isJavaObject(obj)`
 
-- returns whether `obj` is an object of the Java language
+- returns `true` if `obj` is a Java host object
 - returns `false` for native JavaScript objects, as well as for objects of other polyglot languages
 
 #### `Java.isType(obj)`
 
-- returns `true` if `obj` is an object representing the constructor and static members of a Java class, as obtained (for example) by `Java.type()`
+- returns `true` if `obj` is an object representing the constructor and static members of a Java class, as obtained by `Java.type()` or package objects.
 - returns `false` for all other arguments
 
 #### `Java.typeName(obj)`
@@ -295,25 +298,25 @@ Lossy conversion is disallowed and results in a TypeError.
 - returns whether `fn` is an object of the Java language that represents a Java function
 - returns `false` for all other types, including native JavaScript function, and functions of other polyglot languages
 
-This function requires the Nashorn compatibility mode flag.
+> This function is only available in Nashorn compatibility mode (`--js.nashorn-compat=true`).
 
 #### `Java.isScriptObject(obj)`
 
 - returns whether `obj` is an object of the JavaScript language
 - returns `false` for all other types, including objects of Java and other polyglot languages
 
-This function requires the Nashorn compatibility mode flag.
+> This function is only available in Nashorn compatibility mode (`--js.nashorn-compat=true`).
 
 #### `Java.isScriptFunction(fn)`
 
 - returns whether `fn` is a JavaScript function
 - returns `false` for all other types, including Java function, and functions of other polyglot languages
 
-This function requires the Nashorn compatibility mode flag.
+> This function is only available in Nashorn compatibility mode (`--js.nashorn-compat=true`).
 
 #### `Java.addToClasspath(location)`
 
-- adds the specified location (file name or path name, as String) to Java's classpath
+- adds the specified location (a `.jar` file or directory path string) to Java's classpath
 
 ### Polyglot
 

docs/user/Options.md

@@ -81,7 +81,7 @@ For a complete list, use `js --help:js:internal`
 This option provides compatibility to a specific version of the ECMAScript specification.
 It expects an integer value, where both the edition numbers (`5`, `6`, ...) and the publication years (starting from `2015`) are supported.
 As of GraalVM 21.2, `latest`, `staging` are supported, too.
-The default in GraalVM 23.1 is the [`ECMAScript 2023 specification`](https://tc39.es/ecma262/).
+The default in GraalVM 23.1 is the [`ECMAScript 2023 specification`](https://262.ecma-international.org/14.0/).
 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 a released, finalized version of the specification (e.g., `2022`).
 

docs/user/README.md

@@ -13,12 +13,12 @@ To migrate the code previously targeted to the Nashorn or Rhino engines, [migrat
 
 ## Getting Started
 
-As of GraalVM for JDK 21, the JavaScript (GraalJS) and Node.js runtimes are available as standalone distributions. 
+As of GraalVM for JDK 21, the JavaScript (GraalJS) and Node.js runtimes are available as standalone distributions.
 Two standalone language runtime options are available for both Oracle GraalVM and GraalVM Community Edition: a Native Image compiled native launcher or a JVM-based runtime (included).
-To distinguish between them, the GraalVM Community Edition version has the suffix `-community` in the name: `graaljs-community-<version>-<os>-<arch>.tar.gz`, `graalnodejs-community-<version>-<os>-<arch>.tar.gz`, 
+To distinguish between them, the GraalVM Community Edition version has the suffix `-community` in the name: `graaljs-community-<version>-<os>-<arch>.tar.gz`, `graalnodejs-community-<version>-<os>-<arch>.tar.gz`.
 A standalone that comes with a JVM has a `-jvm` suffix in a name.
 
-1. Navigate to [GitHub releases](https://github.com/oracle/graaljs/releases/) and select a desired standalone for your operating system. 
+1. Navigate to [GitHub releases](https://github.com/oracle/graaljs/releases/) and select a desired standalone for your operating system.
 
 2. Unzip the archive:
 

docs/user/RunOnJDK.md

@@ -16,17 +16,17 @@ This document describes how to run GraalVM JavaScript on stock Java VMs, and sho
 
 ## GraalVM JavaScript on Maven Central
 GraalVM JavaScript is open source and regularly pushed to Maven Central Repository by the community.
-You can find it as pom artifact [org.graalvm.polyglot:js](https://mvnrepository.com/artifact/org.graalvm.polyglot/js).
+You can find it as a POM artifact, under [`org.graalvm.polyglot:js`](https://mvnrepository.com/artifact/org.graalvm.polyglot/js).
 
-There are example Maven projects for GraalVM JavaScript on JDK21 (or later) using the Graal compiler:
+There are example Maven projects for GraalVM JavaScript on JDK 21 (or later) using the Graal compiler:
 * [Polyglot Embedding Demo](https://github.com/graalvm/polyglot-embedding-demo).
 Example Maven and Gradle projects for a simple JavaScript "Hello World" application.
-* [JS Maven Demo](https://github.com/oracle/graaljs/tree/master/graal-js/test/maven-demo)
+* [JS Maven Demo](https://github.com/oracle/graaljs/tree/master/graal-js/test/maven-demo).
 This example contains a Maven project for a JavaScript benchmark (a prime number generator).
 It allows a user to compare the performance of GraalVM JavaScript running with or without the GraalVM compiler as the optimizing compiler.
 Running with the GraalVM compiler will significantly improve the execution performance of any relatively large JavaScript codebase.
 
-In essence, the example `pom.xml` file activates JVMCI to install additional JIT compilers, and configures the JIT compiler to be the Graal Compiler by providing it on `--module-path` and `--upgrade-module-path`.
+In essence, the example `pom.xml` file activates the JVM Compiler Interface (JVMCI) and configures the JIT compiler to be the Graal compiler by providing it on `--module-path` and `--upgrade-module-path`.
 
 ### ScriptEngine JSR 223
 GraalVM JavaScript can be started via `ScriptEngine` when _js-scriptengine.jar_ is included on the module path.