Skip to content

Commit 622fd8e

Browse files
Trottaddaleax
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 32a2b40 commit 622fd8e

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
@@ -85,7 +85,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)
8585
} // namespace demo
8686
```
8787
88-
All Node.js Addons must export an initialization function following
88+
All Node.js addons must export an initialization function following
8989
the pattern:
9090
9191
```cpp
@@ -317,7 +317,7 @@ Once the source code has been written, it must be compiled into the binary
317317
`addon.node` file. To do so, create a file called `binding.gyp` in the
318318
top-level of the project describing the build configuration of the module
319319
using a JSON-like format. This file is used by [node-gyp][], a tool written
320-
specifically to compile Node.js Addons.
320+
specifically to compile Node.js addons.
321321

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

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

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

356356
```js
@@ -361,12 +361,12 @@ console.log(addon.hello());
361361
// Prints: 'world'
362362
```
363363

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

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

371371
```js
372372
try {
@@ -379,31 +379,31 @@ try {
379379
### Linking to libraries included with Node.js
380380

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

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

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

398398
### Loading addons using `require()`
399399

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

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

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

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

428428
## N-API
429429

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

514-
Once the `binding.gyp` file is ready, the example Addons can be configured and
514+
Once the `binding.gyp` file is ready, the example addons can be configured and
515515
built using `node-gyp`:
516516

517517
```console
@@ -588,7 +588,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
588588
} // namespace demo
589589
```
590590
591-
Once compiled, the example Addon can be required and used from within Node.js:
591+
Once compiled, the example addon can be required and used from within Node.js:
592592
593593
```js
594594
// test.js
@@ -599,7 +599,7 @@ console.log('This should be eight:', addon.add(3, 5));
599599

600600
### Callbacks
601601

602-
It is common practice within Addons to pass JavaScript functions to a C++
602+
It is common practice within addons to pass JavaScript functions to a C++
603603
function and execute them from there. The following example illustrates how
604604
to invoke such callbacks:
605605

@@ -642,7 +642,7 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
642642
```
643643
644644
This example uses a two-argument form of `Init()` that receives the full
645-
`module` object as the second argument. This allows the Addon to completely
645+
`module` object as the second argument. This allows the addon to completely
646646
overwrite `exports` with a single function instead of adding the function as a
647647
property of `exports`.
648648

0 commit comments

Comments
 (0)