From fcb143519020a464e88c30bb5af1dfc524485877 Mon Sep 17 00:00:00 2001
From: Gireesh Punathil <gpunathi@in.ibm.com>
Date: Wed, 30 Oct 2024 09:05:10 +0530
Subject: [PATCH] doc: improve c++ embedder API doc

normalise the headers, fixup bullet points and
expand `node::IsolateData` scope for clarity.
---
 doc/api/embedding.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/doc/api/embedding.md b/doc/api/embedding.md
index d4ae090c255f97..e7f0b2c1a5e0cc 100644
--- a/doc/api/embedding.md
+++ b/doc/api/embedding.md
@@ -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