[GR-26149] JavaScript documentation review as part of the task force.

PullRequest: js/1722

Author: olyagpl

docs/user/FAQ.md

@@ -1,21 +1,20 @@
 # Multithreading
 
-GraalVM JavaScript supports multithreading.
+Running JavaScript on GraalVM supports multithreading.
 Depending on the usage scenario, threads can be used to execute parallel JavaScript code using multiple [`Context`](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Context.html) objects, or multiple [Worker](https://nodejs.org/api/worker_threads.html) threads.
 
 ## Multithreading with Java and JavaScript
 
-GraalVM JavaScript supports multithreading in the context of Java interoperability.
-The basic model of multi-threaded execution supported by GraalVM JavaScript is a "share-nothing" model that should be familiar to any JavaScript developer:
+Multithreading is supported when running JavaScript in the context of Java interoperability.
+The basic model of multi-threaded execution supported by GraalVM is a "share-nothing" model that should be familiar to any JavaScript developer:
 
-1. An arbitrary number of JS `Context`s can be created, but they should be used by one thread at a time.
+1. An arbitrary number of JavaScript `Context`s can be created, but they should be used by one thread at a time.
 2. Concurrent access to JavaScript objects is not allowed: any JavaScript object cannot be accessed by more than one thread at a time.
 3. Concurrent access to Java objects is allowed: any Java object can be accessed by any Java or JavaScript thread, concurrently.
 
-A JavaScript `Context` cannot be accessed by two or more threads, concurrently.
-It is however possible to access a same `Context` from multiple threads using proper syncronization, to ensure that concurrent access never happens.
+A JavaScript `Context` cannot be accessed by two or more threads, concurrently, but it is possible to access the same `Context` from multiple threads using proper syncronization, to ensure that concurrent access never happens.
 
-#### Examples
+### Examples
 
 The GraalVM JavaScript [unit tests](https://github.com/graalvm/graaljs/tree/master/graal-js/src/com.oracle.truffle.js.test.threading/src/com/oracle/truffle/js/test/threading) contain several examples of multi-threaded Java/JavaScript interactions.
 The most notable ones describe how:
@@ -28,16 +27,16 @@ The most notable ones describe how:
 
 ## Multithreading with Node.js
 
-The basic multi-threading model of GraalVM JavaScript applies to Node.js applications as well.
-In Node.js, a [Worker](https://nodejs.org/api/worker_threads.html#worker_threads_worker_threads) thread can be created to execute JavaScript code in parallel, but JavaScript objects cannot be shared between workers.
-On the contrary, a Java object created with GraalVM Java interoperability (e.g., using `Java.type()`) _can_ be shared between Node.js workers.
+The basic multithreading model of GraalVM JavaScript applies to Node.js applications as well.
+In Node.js, a [Worker](https://nodejs.org/api/worker_threads.html#worker_threads_worker_threads) thread can be created to execute JavaScript code in parallel, but JavaScript objects cannot be shared between Workers.
+On the contrary, a Java object created with GraalVM Java interoperability (e.g., using `Java.type()`) can be shared between Node.js Workers.
 This allows multi-threaded Node.js applications to share Java objects.
 
-#### Examples
+### Examples
 
 The GraalVM Node.js [unit tests](https://github.com/graalvm/graaljs/tree/master/graal-nodejs/test/graal/unit) contain several examples of multi-threaded Node.js applications.
 The most notable examples show how:
 
 1. [Node.js worker threads can execute Java code](https://github.com/graalvm/graaljs/blob/master/graal-nodejs/test/graal/unit/worker.js).
 2. [Java objects can be shared between Node.js worker threads](https://github.com/graalvm/graaljs/blob/master/graal-nodejs/test/graal/unit/javaMessages.js).
-3. [JavaScript `Promise` objects can be used to `await` on messages from workers, using Java objects to bind promises to worker messages](https://github.com/graalvm/graaljs/blob/master/graal-nodejs/test/graal/unit/workerInteropPromises.js)
+3. [JavaScript `Promise` objects can be used to `await` on messages from workers, using Java objects to bind promises to worker messages](https://github.com/graalvm/graaljs/blob/master/graal-nodejs/test/graal/unit/workerInteropPromises.js).

docs/user/JavaInteroperability.md

@@ -5,26 +5,30 @@ Applications can freely import and use NPM packages, including native ones.
 
 ## Running Node.js Applications
 
-To run Node.js-based applications, use the `node` binary executable in the GraalVM distribution:
-```
+To run Node.js-based applications, use the `node` launcher in the GraalVM distribution:
+```shell
 $GRAALVM_HOME/bin/node [options] [filename] [args]
 ```
 
-GraalVM's Node.js is based on a recent version of Node.js, and runs the GraalVM JavaScript engine instead of Google V8. Thus, some internal features (e.g., VM-internal statistics or configuration, profiling, debugging, etc.) are unsupported, or supported with potentially different behavior.
+GraalVM's Node.js runtime is based on a recent version of Node.js, and runs the
+GraalVM JavaScript engine instead of Google V8. Thus, some internal features (e.g.,
+VM-internal statistics, configuration, profiling, debugging, etc.) are
+unsupported, or supported with potentially different behavior.
 
-The `node` executable is largely compatible with Node.js, and features additional GraalVM-specific functionalities (e.g., interoperability with Java and all other GraalVM languages).
+The `node` command is largely compatible with Node.js, and features additional GraalVM-specific functionalities (e.g., interoperability with Java and all other GraalVM languages).
 A list of available options can be obtained with `node --help`.
 
 ## Installing Packages Using `npm`
 
-To install a Node.js package, you can use the `npm` executable in the `$GRAALVM_HOME/bin` folder of GraalVM.
-The `npm` executable is equivalent to the default NPM command, and supports most of its options.
+To install a Node.js package, you can use the `npm` launcher from the GraalVM's `/bin` folder.
+The `npm` command is equivalent to the default NPM command, and supports most of its options.
 
 An NPM package can be installed with:
-```
+```shell
 $GRAALVM_HOME/bin/npm install <package>
 ```
-As the `npm` executable of GraalVM is largely compatible with NPM, packages will be installed in the `node_modules` folder, as expected.
+
+As the `npm` command of GraalVM is largely compatible with NPM, packages will be installed in the `node_modules` folder, as expected.
 
 ### Installing `npm` Packages Globally
 
@@ -33,7 +37,7 @@ By default, `npm` installs global packages in the path where the `node` executab
 In GraalVM, this means that global packages will create files in the GraalVM folder.
 To avoid writing to the GraalVM folder, the default global installation folder of `npm` can be modified by setting the `$PREFIX` environment variable, or by specifying the `--prefix` option when running `npm install`.
 For example, the following command will install global packages in the `/foo/bar` folder:
-```
+```shell
 $GRAALVM_HOME/bin/npm install --prefix /foo/bar -g <package>
 ```
-More details about `prefix` can be found in the official npm documentation.
+More details about `prefix` can be found in the [official NPM documentation](https://docs.npmjs.com/cli/prefix.html).

docs/user/JavaScriptCompatibility.md

@@ -1,11 +1,12 @@
 # Differences Between Node.js and Java Embeddings
 
-GraalVM's JavaScript engine is a fully-compliant ECMA2020 language runtime.
-As such, it can run JavaScript code in a variety of embedding scenarios, including the Oracle [RDBMS](https://www.graalvm.org/docs/examples/mle-oracle/), any Java-based application and Node.js.
+GraalVM provides a fully-compliant ECMAScript 2020 JavaScript language runtime.
+As such, it can run JavaScript code in a variety of embedding scenarios, including the Oracle [RDBMS](https://www.graalvm.org/docs/examples/mle-oracle/), any Java-based application, and Node.js.
 
 Depending on the GraalVM's JavaScript embedding scenario, applications have access to different built-in capabilities.
-For example, Node.js applications running on GraalVM's JavaScript engine have access to all of Node.js' APIs, including built-in Node.js' modules such as `'fs'`, `'http'`, etc.
-Conversely, JavaScript code embedded in a Java application has access to limited capabilities, as specified through the [Context API](https://www.graalvm.org/reference-manual/embed-languages/#compile-and-run-a-polyglot-application), and do _not_ have access to Node.js built-in modules.
+For example, Node.js applications running on GraalVM's have access to all of Node.js' APIs, including built-in Node.js modules such as `fs` and `http`, etc.
+
+Conversely, JavaScript code embedded in a Java application has access to limited capabilities, as specified through the [Context API](https://www.graalvm.org/reference-manual/embed-languages/#compile-and-run-a-polyglot-application), and do not have access to Node.js built-in modules.
 
 This guide describes the main differences between a Node.js application and a GraalVM JavaScript application embedded in Java.
 
@@ -27,75 +28,70 @@ In this scenario, Java classes can be exposed to the Node.js application by usin
 JavaScript applications can interact with Java classes using the `Java` built-in object.
 The object is not available by default, and can be enabled in the following way:
 
-1. In Node.js, start GraalVM using the `bin/node --jvm` command
+1. In Node.js, start GraalVM using the `bin/node --jvm` command.
 2. In Java, create a GraalVM context using the `withHostInterop()` option, e.g.:
-```
+```java
 Context.create("js").withHostInterop()
 ```
-More details on the Java interoperability capabilities of GraalVM JavaScript are available in the [Java Interoperability](https://github.com/graalvm/graaljs/blob/master/docs/user/JavaInteroperability.md) guide.
+More details on the Java interoperability capabilities of GraalVM JavaScript are available in [Java Interoperability](https://github.com/graalvm/graaljs/blob/master/docs/user/JavaInteroperability.md).
 
 ## Multithreading
 
 A GraalVM context running JavaScript enforces a "share-nothing" model of parallelism: no JavaScript values can be accessed by two concurrent Java threads at the same time.
-In order to leverage parallel execution, multiple contexts have to be created and executed from multiple threads.
+In order to leverage parallel execution, multiple contexts have to be created and executed from multiple threads:
 
 1. In Node.js, multiple contexts can be created using Node.js' [Worker threads](https://nodejs.org/api/worker_threads.html) API.
-The worker threads API ensures that no sharing can happen between two parallel contexts.
+The Worker threads API ensures that no sharing can happen between two parallel contexts.
 2. In Java, multiple contexts can be executed from multiple threads.
 As long as a context is not accessed by two threads at the same time, parallel execution happens safely.
 
 More details on parallel execution in GraalVM JavaScript are available in [this blog post](https://medium.com/graalvm/multi-threaded-java-javascript-language-interoperability-in-graalvm-2f19c1f9c37b).
 
-
 ## Java Libraries
 
 Java libraries can be accessed from JavaScript in GraalVM through the `Java` built-in object.
-In order for a Java library to be accessible from a `Context`, its `jar` files need to be added to the GraalVM class path.
-This can be done in the following way:
+In order for a Java library to be accessible from a `Context`, its `jar` files need to be added to the GraalVM classpath. This can be done in the following way:
 
 1. In Node.js, the classpath can be modified using the `--jvm.cp` option.
 2. In Java, the default Java's `-cp` option can be used.
 
-More details on GraalVM command line options are available in the [Options](https://github.com/graalvm/graaljs/blob/master/docs/user/Options.md) guide.
+More details on GraalVM command line options are available in [Options](https://github.com/graalvm/graaljs/blob/master/docs/user/Options.md).
 
 ## JavaScript Modules
 
 Many popular JavaScript modules such as those available on the `npm` package registry can be used from Node.js as well as from Java.
 GraalVM JavaScript is compatible with the latest ECMA standard, and supports ECMAScript modules (ECM).
 CommonJS (CJS) modules are supported when running with Node.js.
-CommonJS modules cannot be used _directly_ from Java; to this end, any popular package bundlers (such as Parcel, Browserify or Webpack) can be used.
+CommonJS modules cannot be used _directly_ from Java; to this end, any popular package bundlers (such as Parcel, Browserify, or Webpack) can be used.
 
 ### ECMAScript Modules (ECM)
-
 ECMAScript modules can be loaded in GraalVM JavaScript in the following ways:
 
 1. The support of ECMAScript modules in Node.js is still experimental.
-GraalVM  supports all features supported by the Node.js version that is compatible with GraalVM.
-To check such version, simply run `bin/node --version`.
+GraalVM  Enterprise supports all features supported by the Node.js version that is compatible with GraalVM.
+To check and verify the version, simply run `bin/node --version`.
 2. ECMAScript modules can be loaded in a `Context` simply by evaluating the module sources.
 Currently, GraalVM JavaScript loads ECMAScript modules based on their file extension.
 Therefore, any ECMAScript module must have file name extension `.mjs`.
 This might change in future versions of GraalVM JavaScript.
 
-More details about evaluating files using the Context API are available in the [API Javadoc](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Source.html).
+More details about evaluating files using the Context API are available in the [javadoc](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Source.html).
 
 ### CommonJS Modules (CJS)
-
 CommonJS modules can be loaded in GraalVM JavaScript in the following way:
 
 1. In Node.js, modules can be loaded using the `require()` built-in function, as expected.
 2. By default, the `Context` API does not support CommonJS modules, and has no built-in `require()` function.
-In order to be loaded and used from a `Context` in Java, a CJS module needs to be _bundled_ into a self-contained JavaScript source file.
-This can be done using one of the many popular open-source bundling tools such as Parcel, Browserify and Webpack.
+In order to be loaded and used from a `Context` in Java, a CommonJS module needs to be _bundled_ into a self-contained JavaScript source file.
+This can be done using one of the many popular open-source bundling tools such as Parcel, Browserify, and Webpack.
 Experimental support for CommonJS modules can be enabled through the `js.commonjs-require` option as described below.
 
 #### Experimental support for CommonJS NPM modules in the `Context` API
-
 The `js.commonjs-require` option provides a built-in `require()` function that can be used to load NPM-compatible CommonJS modules in a JavaScript `Context`.
 Currently, this is an experimental feature not for production usage.
 
 To enable CommonJS support, a JavaScript context can be created in the following way:
-```
+```java
 Map<String, String> options = new HashMap<>();
 // Enable CommonJS experimental support.
 options.put("js.commonjs-require", "true");
@@ -118,43 +114,39 @@ Value module = cx.eval("js", "require('some-module');");
 ```
 
 ##### Differences with Node.js built-in `require()` function
-
-The `Context` built-in `require()` function can load regular NPM modules implemented in JavaScript, but cannot load _native_ NPM modules.
-The built-in `require()` relies on the [Truffle FileSystem](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html), therefore I/O access needs to be enabled at context creation time using the [`allowIO` option](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/Context.Builder.html#allowIO-boolean-).
+The `Context` built-in `require()` function can load regular NPM modules implemented in JavaScript, but cannot load native NPM modules.
+The built-in `require()` relies on the [FileSystem](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/io/FileSystem.html), therefore I/O access needs to be enabled at context creation time using the [`allowIO` option](https://www.graalvm.org/truffle/javadoc/org/graalvm/polyglot/Context.Builder.html#allowIO-boolean-).
 The built-in `require()` aims to be largely compatible with Node.js, and we expect it to work with any NPM module that would work in a browser (e.g., created using a package bundler).
 
 ##### Installing an NPM module to be used via the `Context` API
-
 In order to be used from a JavaScript `Context`, an NPM module needs to be installed to a local folder.
 This can be done using GraalVM JavaScript's `npm install` command like one would normally do for Node.js applications.
 At runtime, the option `js.commonjs-require-cwd` can be used to specify the main installation folder for NPM packages.
 The `require()` built-in function will resolve packages according to the default Node.js' [package resolution protocol](https://nodejs.org/api/modules.html#modules_all_together) starting from the directory specified via `js.commonjs-require-cwd`.
 When no directory is provided with the option, the current working directory of the application will be used.
 
 ##### Node.js core modules mockups
-
-Some JavaScript applications or NPM modules might need functionalities that are available in Node.js' built-in modules (e.g., `'fs'`, `'buffer'`, etc.)
+Some JavaScript applications or NPM modules might need functionalities that are available in Node.js' built-in modules (e.g., `'fs'` and `'buffer'`, etc.).
 Such modules are not available in the `Context` API.
-Thankfully, the Node.js community has developed high-quality JavaScript implementations for many Node.js core modules (e.g.,: the ['buffer'](https://www.npmjs.com/package/buffer) module for the browser).
+Thankfully, the Node.js community has developed high-quality JavaScript implementations for many Node.js core modules (e.g., the ['buffer'](https://www.npmjs.com/package/buffer) module for the browser).
 Such alternative module implementations can be exposed to a JavaScript `Context` using the `js.commonjs-core-modules-replacements` option, in the following way:
+```java
+options.put("js.commonjs-core-modules-replacements", "buffer:my-buffer-implementation");
 ```
-options.put("js.commonjs-core-modules-replacements",
-    "buffer:my-buffer-implementation");
-```
+
 As the code suggests, the option instructs the GraalVM JavaScript runtime to load a module called `my-buffer-implementation` when an application attempts to load the Node.js `'buffer'` built-in module using `require('buffer')`.
 
 ##### Global symbols pre-initialization
-
 An NPM module or a JavaScript application might expect certain global properties to be defined in the global scope.
 For example, applications or modules might expect the `Buffer` global symbol to be defined in the JavaScript global object.
 The option `js.commonjs-global-properties` can be used to pre-initialize such global symbols using the `Context` API.
 The option can be used in the following way:
-```
+```java
 options.put("js.commonjs-global-properties", "./globals.js");
 ```
-Once specified, the file `globals.js` will be loaded at context creation time, that is, before any JavaScript source execution.
+Once specified, the file `globals.js` will be loaded at context creation time. That is, before any JavaScript source execution.
 An example `globals.js` file might perform the following initialization steps:
-```
+```java
 // define an empty object called 'process'
 globalThis.process = {}
 // define the 'Buffer' global symbol