Skip to content

Commit b69ff2f

Browse files
Trottcodebytere
authored andcommitted
doc: use consistent capitalization for addons
Sometimes _addon_ is capitalized and sometimes not. Capitalizing it seems peculiar and hard to justify. Standardize on treating it like other common nouns. PR-URL: #34536 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]>
1 parent 8cc9e5e commit b69ff2f

File tree

1 file changed

+35
-35
lines changed

1 file changed

+35
-35
lines changed

doc/api/addons.md

+35-35
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,16 @@
33
<!--introduced_in=v0.10.0-->
44
<!-- type=misc -->
55

6-
Addons are dynamically-linked shared objects written in C++. The
7-
[`require()`][require] function can load Addons as ordinary Node.js modules.
6+
_Addons_ are dynamically-linked shared objects written in C++. The
7+
[`require()`][require] function can load addons as ordinary Node.js modules.
88
Addons provide an interface between JavaScript and C/C++ libraries.
99

10-
There are three options for implementing Addons: N-API, nan, or direct
10+
There are three options for implementing addons: N-API, nan, or direct
1111
use of internal V8, libuv and Node.js libraries. Unless there is a need for
1212
direct access to functionality which is not exposed by N-API, use N-API.
13-
Refer to [C/C++ Addons with N-API](n-api.html) for more information on N-API.
13+
Refer to [C/C++ addons with N-API](n-api.html) for more information on N-API.
1414

15-
When not using N-API, implementing Addons is complicated,
15+
When not using N-API, implementing addons is complicated,
1616
involving knowledge of several components and APIs:
1717

1818
* V8: the C++ library Node.js uses to provide the
@@ -27,27 +27,27 @@ involving knowledge of several components and APIs:
2727
access across all major operating systems to many common system tasks, such
2828
as interacting with the filesystem, sockets, timers, and system events. libuv
2929
also provides a pthreads-like threading abstraction that may be used to
30-
power more sophisticated asynchronous Addons that need to move beyond the
30+
power more sophisticated asynchronous addons that need to move beyond the
3131
standard event loop. Addon authors are encouraged to think about how to
3232
avoid blocking the event loop with I/O or other time-intensive tasks by
3333
off-loading work via libuv to non-blocking system operations, worker threads
3434
or a custom use of libuv's threads.
3535

36-
* Internal Node.js libraries. Node.js itself exports C++ APIs that Addons can
36+
* Internal Node.js libraries. Node.js itself exports C++ APIs that addons can
3737
use, the most important of which is the `node::ObjectWrap` class.
3838

3939
* Node.js includes other statically linked libraries including OpenSSL. These
4040
other libraries are located in the `deps/` directory in the Node.js source
4141
tree. Only the libuv, OpenSSL, V8 and zlib symbols are purposefully
42-
re-exported by Node.js and may be used to various extents by Addons. See
42+
re-exported by Node.js and may be used to various extents by addons. See
4343
[Linking to libraries included with Node.js][] for additional information.
4444

4545
All of the following examples are available for [download][] and may
46-
be used as the starting-point for an Addon.
46+
be used as the starting-point for an addon.
4747

4848
## Hello world
4949

50-
This "Hello world" example is a simple Addon, written in C++, that is the
50+
This "Hello world" example is a simple addon, written in C++, that is the
5151
equivalent of the following JavaScript code:
5252

5353
```js
@@ -84,7 +84,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)
8484
} // namespace demo
8585
```
8686
87-
All Node.js Addons must export an initialization function following
87+
All Node.js addons must export an initialization function following
8888
the pattern:
8989
9090
```cpp
@@ -315,7 +315,7 @@ Once the source code has been written, it must be compiled into the binary
315315
`addon.node` file. To do so, create a file called `binding.gyp` in the
316316
top-level of the project describing the build configuration of the module
317317
using a JSON-like format. This file is used by [node-gyp][], a tool written
318-
specifically to compile Node.js Addons.
318+
specifically to compile Node.js addons.
319319

320320
```json
321321
{
@@ -331,7 +331,7 @@ specifically to compile Node.js Addons.
331331
A version of the `node-gyp` utility is bundled and distributed with
332332
Node.js as part of `npm`. This version is not made directly available for
333333
developers to use and is intended only to support the ability to use the
334-
`npm install` command to compile and install Addons. Developers who wish to
334+
`npm install` command to compile and install addons. Developers who wish to
335335
use `node-gyp` directly can install it using the command
336336
`npm install -g node-gyp`. See the `node-gyp` [installation instructions][] for
337337
more information, including platform-specific requirements.
@@ -344,11 +344,11 @@ will generate either a `Makefile` (on Unix platforms) or a `vcxproj` file
344344
Next, invoke the `node-gyp build` command to generate the compiled `addon.node`
345345
file. This will be put into the `build/Release/` directory.
346346

347-
When using `npm install` to install a Node.js Addon, npm uses its own bundled
347+
When using `npm install` to install a Node.js addon, npm uses its own bundled
348348
version of `node-gyp` to perform this same set of actions, generating a
349-
compiled version of the Addon for the user's platform on demand.
349+
compiled version of the addon for the user's platform on demand.
350350

351-
Once built, the binary Addon can be used from within Node.js by pointing
351+
Once built, the binary addon can be used from within Node.js by pointing
352352
[`require()`][require] to the built `addon.node` module:
353353

354354
```js
@@ -359,12 +359,12 @@ console.log(addon.hello());
359359
// Prints: 'world'
360360
```
361361

362-
Because the exact path to the compiled Addon binary can vary depending on how
363-
it is compiled (i.e. sometimes it may be in `./build/Debug/`), Addons can use
362+
Because the exact path to the compiled addon binary can vary depending on how
363+
it is compiled (i.e. sometimes it may be in `./build/Debug/`), addons can use
364364
the [bindings][] package to load the compiled module.
365365

366366
While the `bindings` package implementation is more sophisticated in how it
367-
locates Addon modules, it is essentially using a `try…catch` pattern similar to:
367+
locates addon modules, it is essentially using a `try…catch` pattern similar to:
368368

369369
```js
370370
try {
@@ -377,31 +377,31 @@ try {
377377
### Linking to libraries included with Node.js
378378

379379
Node.js uses statically linked libraries such as V8, libuv and OpenSSL. All
380-
Addons are required to link to V8 and may link to any of the other dependencies
380+
addons are required to link to V8 and may link to any of the other dependencies
381381
as well. Typically, this is as simple as including the appropriate
382382
`#include <...>` statements (e.g. `#include <v8.h>`) and `node-gyp` will locate
383383
the appropriate headers automatically. However, there are a few caveats to be
384384
aware of:
385385

386386
* When `node-gyp` runs, it will detect the specific release version of Node.js
387387
and download either the full source tarball or just the headers. If the full
388-
source is downloaded, Addons will have complete access to the full set of
388+
source is downloaded, addons will have complete access to the full set of
389389
Node.js dependencies. However, if only the Node.js headers are downloaded, then
390390
only the symbols exported by Node.js will be available.
391391

392392
* `node-gyp` can be run using the `--nodedir` flag pointing at a local Node.js
393-
source image. Using this option, the Addon will have access to the full set of
393+
source image. Using this option, the addon will have access to the full set of
394394
dependencies.
395395

396396
### Loading addons using `require()`
397397

398-
The filename extension of the compiled Addon binary is `.node` (as opposed
398+
The filename extension of the compiled addon binary is `.node` (as opposed
399399
to `.dll` or `.so`). The [`require()`][require] function is written to look for
400400
files with the `.node` file extension and initialize those as dynamically-linked
401401
libraries.
402402

403403
When calling [`require()`][require], the `.node` extension can usually be
404-
omitted and Node.js will still find and initialize the Addon. One caveat,
404+
omitted and Node.js will still find and initialize the addon. One caveat,
405405
however, is that Node.js will first attempt to locate and load modules or
406406
JavaScript files that happen to share the same base name. For instance, if
407407
there is a file `addon.js` in the same directory as the binary `addon.node`,
@@ -411,26 +411,26 @@ and load it instead.
411411
## Native abstractions for Node.js
412412

413413
Each of the examples illustrated in this document make direct use of the
414-
Node.js and V8 APIs for implementing Addons. The V8 API can, and has, changed
414+
Node.js and V8 APIs for implementing addons. The V8 API can, and has, changed
415415
dramatically from one V8 release to the next (and one major Node.js release to
416-
the next). With each change, Addons may need to be updated and recompiled in
416+
the next). With each change, addons may need to be updated and recompiled in
417417
order to continue functioning. The Node.js release schedule is designed to
418418
minimize the frequency and impact of such changes but there is little that
419419
Node.js can do to ensure stability of the V8 APIs.
420420

421421
The [Native Abstractions for Node.js][] (or `nan`) provide a set of tools that
422-
Addon developers are recommended to use to keep compatibility between past and
422+
addon developers are recommended to use to keep compatibility between past and
423423
future releases of V8 and Node.js. See the `nan` [examples][] for an
424424
illustration of how it can be used.
425425

426426
## N-API
427427

428428
> Stability: 2 - Stable
429429
430-
N-API is an API for building native Addons. It is independent from
430+
N-API is an API for building native addons. It is independent from
431431
the underlying JavaScript runtime (e.g. V8) and is maintained as part of
432432
Node.js itself. This API will be Application Binary Interface (ABI) stable
433-
across versions of Node.js. It is intended to insulate Addons from
433+
across versions of Node.js. It is intended to insulate addons from
434434
changes in the underlying JavaScript engine and allow modules
435435
compiled for one version to run on later versions of Node.js without
436436
recompilation. Addons are built/packaged with the same approach/tools
@@ -479,11 +479,11 @@ NAPI_MODULE(NODE_GYP_MODULE_NAME, init)
479479
```
480480
481481
The functions available and how to use them are documented in
482-
[C/C++ Addons with N-API](n-api.html).
482+
[C/C++ addons with N-API](n-api.html).
483483
484484
## Addon examples
485485
486-
Following are some example Addons intended to help developers get started. The
486+
Following are some example addons intended to help developers get started. The
487487
examples make use of the V8 APIs. Refer to the online [V8 reference][v8-docs]
488488
for help with the various V8 calls, and V8's [Embedder's Guide][] for an
489489
explanation of several concepts used such as handles, scopes, function
@@ -509,7 +509,7 @@ filename to the `sources` array:
509509
"sources": ["addon.cc", "myexample.cc"]
510510
```
511511

512-
Once the `binding.gyp` file is ready, the example Addons can be configured and
512+
Once the `binding.gyp` file is ready, the example addons can be configured and
513513
built using `node-gyp`:
514514

515515
```console
@@ -583,7 +583,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
583583
} // namespace demo
584584
```
585585
586-
Once compiled, the example Addon can be required and used from within Node.js:
586+
Once compiled, the example addon can be required and used from within Node.js:
587587
588588
```js
589589
// test.js
@@ -594,7 +594,7 @@ console.log('This should be eight:', addon.add(3, 5));
594594

595595
### Callbacks
596596

597-
It is common practice within Addons to pass JavaScript functions to a C++
597+
It is common practice within addons to pass JavaScript functions to a C++
598598
function and execute them from there. The following example illustrates how
599599
to invoke such callbacks:
600600

@@ -635,7 +635,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
635635
```
636636
637637
This example uses a two-argument form of `Init()` that receives the full
638-
`module` object as the second argument. This allows the Addon to completely
638+
`module` object as the second argument. This allows the addon to completely
639639
overwrite `exports` with a single function instead of adding the function as a
640640
property of `exports`.
641641

0 commit comments

Comments
 (0)