From 5de25676445ff6c12c8e34a7d8f560d5d3ae972a Mon Sep 17 00:00:00 2001
From: Gireesh Punathil <gpunathi@in.ibm.com>
Date: Fri, 1 Nov 2024 09:13:53 +0530
Subject: [PATCH] doc: improve c++ embedder API doc

normalise the headers, fixup bullet points and
expand `node::IsolateData` scope for clarity.

PR-URL: https://github.com/nodejs/node/pull/55597
Reviewed-By: Akhil Marsonya <akhil.marsonya27@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
---
 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..114f1128af0a42 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