Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: fix a few n-api doc issues #13650

Closed
wants to merge 2 commits into from
Closed

doc: fix a few n-api doc issues #13650

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
05bc598
doc: fix a few n-api doc issues
mhdawson Jun 13, 2017
02a9e77
squash: address comments
mhdawson Jun 15, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 49 additions & 20 deletions doc/api/n-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -406,11 +406,12 @@ added: v8.0.0
-->
```C
NODE_EXTERN napi_status napi_create_error(napi_env env,
const char* msg,
napi_value msg,
napi_value* result);
```
- `[in] env`: The environment that the API is invoked under.
- `[in] msg`: C string representing the text to be associated with.
- `[in] msg`: napi_value that references a JavaScript String to be
used as the message for the Error.
- `[out] result`: `napi_value` representing the error created.

Returns `napi_ok` if the API succeeded.
Expand All @@ -423,11 +424,12 @@ added: v8.0.0
-->
```C
NODE_EXTERN napi_status napi_create_type_error(napi_env env,
const char* msg,
napi_value msg,
napi_value* result);
```
- `[in] env`: The environment that the API is invoked under.
- `[in] msg`: C string representing the text to be associated with.
- `[in] msg`: napi_value that references a JavaScript String to be
used as the message for the Error.
- `[out] result`: `napi_value` representing the error created.

Returns `napi_ok` if the API succeeded.
Expand All @@ -445,7 +447,8 @@ NODE_EXTERN napi_status napi_create_range_error(napi_env env,
napi_value* result);
```
- `[in] env`: The environment that the API is invoked under.
- `[in] msg`: C string representing the text to be associated with.
- `[in] msg`: napi_value that references a JavaScript String to be
used as the message for the Error.
- `[out] result`: `napi_value` representing the error created.

Returns `napi_ok` if the API succeeded.
Expand Down Expand Up @@ -562,16 +565,17 @@ for (int i = 0; i < 1000000; i++) {
```

When nesting scopes, there are cases where a handle from an
inner scope needs to live beyond the lifespan of that scope. N-API supports an
inner scope needs to live beyond the lifespan of that scope. N-API supports an
'escapable scope' in order to support this case. An escapable scope
allows one or more handles to be 'promoted' so that they 'escape' the
current scope and the lifespan of the handle(s) changes from the current
allows one handle to be 'promoted' so that it 'escapes' the
current scope and the lifespan of the handle changes from the current
scope to that of the outer scope.

The methods available to open/close escapable scopes are
[`napi_open_escapable_handle_scope`][] and [`napi_close_escapable_handle_scope`][].

The request to promote a handle is made through the [`napi_escape_handle`][].
The request to promote a handle is made through [`napi_escape_handle`][] which
can only be called once.

#### napi_open_handle_scope
<!-- YAML
Expand Down Expand Up @@ -618,7 +622,7 @@ NODE_EXTERN napi_status

Returns `napi_ok` if the API succeeded.

This API open a new scope from which objects can be promoted
This API open a new scope from which one object can be promoted
to the outer scope.

#### napi_close_escapable_handle_scope
Expand Down Expand Up @@ -657,9 +661,9 @@ Object in the outer scope.

Returns `napi_ok` if the API succeeded.

This API promotes the handle to the JavaScript object so that it valid
for the lifetime of the outer scope.

This API promotes the handle to the JavaScript object so that it is valid
for the lifetime of the outer scope. It can only be called once per scope.
If it is called more than once an error will be returned.

### References to objects with a lifespan longer than that of the native method
In some cases an addon will need to be able to create and reference objects
Expand Down Expand Up @@ -1212,13 +1216,13 @@ added: v8.0.0
-->
```C
napi_status napi_create_symbol(napi_env env,
const char* description,
napi_value description,
napi_value* result)
```

- `[in] env`: The environment that the API is invoked under.
- `[in] description`: Null-terminated character buffer representing a
UTF8-encoded string to describe the symbol.
- `[in] description`: Optional napi_value which refers to a JavaScript
String to be set as the description for the symbol.
- `[out] result`: A `napi_value` representing a JavaScript Symbol.

Returns `napi_ok` if the API succeeded.
Expand Down Expand Up @@ -1299,8 +1303,8 @@ napi_status napi_create_string_utf16(napi_env env,

- `[in] env`: The environment that the API is invoked under.
- `[in] str`: Character buffer representing a UTF16-LE-encoded string.
- `[in] length`: The length of the string in characters, or -1 if it is
null-terminated.
- `[in] length`: The length of the string in two-byte code units, or -1 if
it is null-terminated.
- `[out] result`: A `napi_value` representing a JavaScript String.

Returns `napi_ok` if the API succeeded.
Expand All @@ -1311,6 +1315,31 @@ The JavaScript String type is described in
[Section 6.1.4](https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type)
of the ECMAScript Language Specification.

#### *napi_create_string_latin1*
<!-- YAML
added: v8.0.0
-->
```C
NAPI_EXTERN napi_status napi_create_string_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);
```

- `[in] env`: The environment that the API is invoked under.
- `[in] str`: Character buffer representing a latin1-encoded string.
- `[in] length`: The length of the string in bytes, or -1 if it is
null-terminated.
- `[out] result`: A `napi_value` representing a JavaScript String.

Returns `napi_ok` if the API succeeded.

This API creates a JavaScript String object from a latin1-encoded C string.

The JavaScript String type is described in
[Section 6.1.4](https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type)
of the ECMAScript Language Specification.

#### *napi_create_string_utf8*
<!-- YAML
added: v8.0.0
Expand All @@ -1323,8 +1352,8 @@ napi_status napi_create_string_utf8(napi_env env,
```

- `[in] env`: The environment that the API is invoked under.
- `[in] s`: Character buffer representing a UTF8-encoded string.
- `[in] length`: The length of the string in characters, or -1 if it is
- `[in] str`: Character buffer representing a UTF8-encoded string.
- `[in] length`: The length of the string in bytes, or -1 if it is
null-terminated.
- `[out] result`: A `napi_value` representing a JavaScript String.

Expand Down