Repository: nodejs/node
Pull request: doc: improve c++ embedder API doc

normalise the headers, fixup bullet points and expand `node::IsolateData` scope for clarity.

<!--
Before submitting a pull request, please read:

- the CONTRIBUTING guide at https://github.com/nodejs/node/blob/HEAD/CONTRIBUTING.md
- the commit message formatting guidelines at
  https://github.com/nodejs/node/blob/HEAD/doc/contributing/pull-requests.md#commit-message-guidelines

For code changes:
1. Include tests for any bug fixes or new features.
2. Update documentation if relevant.
3. Ensure that `make -j4 test` (UNIX), or `vcbuild test` (Windows) passes.

If you believe this PR should be highlighted in the Node.js CHANGELOG
please add the `notable-change` label.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
-->


Changed files:
filename: doc/api/embedding.md
patch: @@ -23,7 +23,7 @@ a Node.js-specific environment.
 
 The full code can be found [in the Node.js source tree][embedtest.cc].
 
-### Setting up per-process state
+### Setting up a per-process state
 
 Node.js requires some per-process state management in order to run:
 
@@ -72,7 +72,7 @@ int main(int argc, char** argv) {
 }
 ```
 
-### Per-instance state
+### Setting up a per-instance state
 
 <!-- YAML
 changes:
@@ -86,11 +86,12 @@ Node.js has a concept of a “Node.js instance”, that is commonly being referr
 to as `node::Environment`. Each `node::Environment` is associated with:
 
 * Exactly one `v8::Isolate`, i.e. one JS Engine instance,
-* Exactly one `uv_loop_t`, i.e. one event loop, and
-* A number of `v8::Context`s, but exactly one main `v8::Context`.
+* Exactly one `uv_loop_t`, i.e. one event loop,
+* A number of `v8::Context`s, but exactly one main `v8::Context`, and
 * One `node::IsolateData` instance that contains information that could be
-  shared by multiple `node::Environment`s that use the same `v8::Isolate`.
-  Currently, no testing is performed for this scenario.
+  shared by multiple `node::Environment`s. The embedder should make sure
+  that `node::IsolateData` is shared only among `node::Environment`s that
+  use the same `v8::Isolate`, Node.js does not perform this check.
 
 In order to set up a `v8::Isolate`, an `v8::ArrayBuffer::Allocator` needs
 to be provided. One possible choice is the default Node.js allocator, which