Skip to content

Commit 19f4b3f

Browse files
preveen-stackwide4head
authored andcommitted
doc: add clarity to available addon options
bullet pointed addon optons; wording clarity; fixes typo
1 parent 32ff100 commit 19f4b3f

File tree

1 file changed

+16
-14
lines changed

1 file changed

+16
-14
lines changed

doc/api/addons.md

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,22 @@ _Addons_ are dynamically-linked shared objects written in C++. The
88
[`require()`][require] function can load addons as ordinary Node.js modules.
99
Addons provide an interface between JavaScript and C/C++ libraries.
1010

11-
There are three options for implementing addons: Node-API, nan, or direct
12-
use of internal V8, libuv, and Node.js libraries. Unless there is a need for
13-
direct access to functionality which is not exposed by Node-API, use Node-API.
11+
There are three options for implementing addons:
12+
* Node-API
13+
* `nan` ([Native Abstractions for Node.js][])
14+
* direct use of internal V8, libuv, and Node.js libraries
15+
16+
Unless there is a need fordirect access to functionality which is not exposed by Node-API, use Node-API.
1417
Refer to [C/C++ addons with Node-API](n-api.md) for more information on
1518
Node-API.
1619

17-
When not using Node-API, implementing addons is complicated,
18-
involving knowledge of several components and APIs:
20+
When not using Node-API, implementing addons becomes more complex, requiring knowledge of multiple components and APIs:
1921

2022
* [V8][]: the C++ library Node.js uses to provide the
21-
JavaScript implementation. V8 provides the mechanisms for creating objects,
22-
calling functions, etc. V8's API is documented mostly in the
23+
JavaScript implementation. It provides the mechanisms for creating objects,
24+
calling functions, etc. The V8's API is documented mostly in the
2325
`v8.h` header file (`deps/v8/include/v8.h` in the Node.js source
24-
tree), which is also available [online][v8-docs].
26+
tree), and is also available [online][v8-docs].
2527

2628
* [libuv][]: The C library that implements the Node.js event loop, its worker
2729
threads and all of the asynchronous behaviors of the platform. It also
@@ -35,10 +37,10 @@ involving knowledge of several components and APIs:
3537
offloading work via libuv to non-blocking system operations, worker threads,
3638
or a custom use of libuv threads.
3739

38-
* Internal Node.js libraries. Node.js itself exports C++ APIs that addons can
40+
* Internal Node.js libraries: Node.js itself exports C++ APIs that addons can
3941
use, the most important of which is the `node::ObjectWrap` class.
4042

41-
* Node.js includes other statically linked libraries including OpenSSL. These
43+
* Other statically linked libraries (including OpenSSL): These
4244
other libraries are located in the `deps/` directory in the Node.js source
4345
tree. Only the libuv, OpenSSL, V8, and zlib symbols are purposefully
4446
re-exported by Node.js and may be used to various extents by addons. See
@@ -148,8 +150,8 @@ invocation of `NODE_MODULE_INIT()`:
148150
* `Local<Value> module`, and
149151
* `Local<Context> context`
150152
151-
The choice to build a context-aware addon carries with it the responsibility of
152-
carefully managing global static data. Since the addon may be loaded multiple
153+
Building a context-aware addon requires careful management of global static data
154+
to ensure stability and correctness. Since the addon may be loaded multiple
153155
times, potentially even from different threads, any global static data stored
154156
in the addon must be properly protected, and must not contain any persistent
155157
references to JavaScript objects. The reason for this is that JavaScript
@@ -255,7 +257,7 @@ such as a main thread and a Worker thread, an add-on needs to either:
255257
* Be declared as context-aware using `NODE_MODULE_INIT()` as described above
256258
257259
In order to support [`Worker`][] threads, addons need to clean up any resources
258-
they may have allocated when such a thread exists. This can be achieved through
260+
they may have allocated when such a thread exits. This can be achieved through
259261
the usage of the `AddEnvironmentCleanupHook()` function:
260262
261263
```cpp
@@ -1273,7 +1275,7 @@ class MyObject : public node::ObjectWrap {
12731275
#endif
12741276
```
12751277

1276-
The implementation of `myobject.cc` is similar to before:
1278+
The implementation of `myobject.cc` remains similar to the previous version:
12771279

12781280
```cpp
12791281
// myobject.cc

0 commit comments

Comments
 (0)