1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: fix a few n-api doc issues

Browse Source 
- Add doc for napi_create_string_latin1().
- Fix signatures where c string was specified instead of napi_value.
- Fix return type of napi_callback.
- Update to specify that napi_escape_handle() can only be called once
  for a given scope.

PR-URL: https://github.com/nodejs/node/pull/13650
Fixes: https://github.com/nodejs/node/issues/13555
Fixes: https://github.com/nodejs/node/issues/13556
Fixes: https://github.com/nodejs/node/issues/13562
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jason Ginchereau <jasongin@microsoft.com>
Reviewed-By: Ingvar Stepanyan <me@rreverser.com>
This commit is contained in:
Michael Dawson 2017-06-13 01:02:52 -04:00 committed by Michael Dawson
parent 2777a7e04f
commit 62e940dfa6
1 changed files with 49 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
doc/api/n-api.md
View File

@ -406,11 +406,12 @@ added: v8.0.0
--> -->
```C ```C
NODE_EXTERN napi_status napi_create_error(napi_env env, NODE_EXTERN napi_status napi_create_error(napi_env env,
const char* msg, napi_value msg,
napi_value* result); napi_value* result);
``` ```
- `[in] env`: The environment that the API is invoked under. - `[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. - `[out] result`: `napi_value` representing the error created.
Returns `napi_ok` if the API succeeded. Returns `napi_ok` if the API succeeded.
@ -423,11 +424,12 @@ added: v8.0.0
--> -->
```C ```C
NODE_EXTERN napi_status napi_create_type_error(napi_env env, NODE_EXTERN napi_status napi_create_type_error(napi_env env,
const char* msg, napi_value msg,
napi_value* result); napi_value* result);
``` ```
- `[in] env`: The environment that the API is invoked under. - `[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. - `[out] result`: `napi_value` representing the error created.
Returns `napi_ok` if the API succeeded. Returns `napi_ok` if the API succeeded.
@ -445,7 +447,8 @@ NODE_EXTERN napi_status napi_create_range_error(napi_env env,
napi_value* result); napi_value* result);
``` ```
- `[in] env`: The environment that the API is invoked under. - `[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. - `[out] result`: `napi_value` representing the error created.
Returns `napi_ok` if the API succeeded. Returns `napi_ok` if the API succeeded.
@ -564,14 +567,15 @@ for (int i = 0; i < 1000000; i++) {
When nesting scopes, there are cases where a handle from an 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 'escapable scope' in order to support this case. An escapable scope
allows one or more handles to be 'promoted' so that they 'escape' the allows one handle to be 'promoted' so that it 'escapes' the
current scope and the lifespan of the handle(s) changes from the current current scope and the lifespan of the handle changes from the current
scope to that of the outer scope. scope to that of the outer scope.
The methods available to open/close escapable scopes are The methods available to open/close escapable scopes are
[`napi_open_escapable_handle_scope`][] and [`napi_close_escapable_handle_scope`][]. [`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 #### napi_open_handle_scope
<!-- YAML <!-- YAML
@ -618,7 +622,7 @@ NODE_EXTERN napi_status
Returns `napi_ok` if the API succeeded. 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. to the outer scope.
#### napi_close_escapable_handle_scope #### napi_close_escapable_handle_scope
@ -657,9 +661,9 @@ Object in the outer scope.
Returns `napi_ok` if the API succeeded. Returns `napi_ok` if the API succeeded.
This API promotes the handle to the JavaScript object so that it valid This API promotes the handle to the JavaScript object so that it is valid
for the lifetime of the outer scope. 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 ### 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 In some cases an addon will need to be able to create and reference objects
@ -1212,13 +1216,13 @@ added: v8.0.0
--> -->
```C ```C
napi_status napi_create_symbol(napi_env env, napi_status napi_create_symbol(napi_env env,
const char* description, napi_value description,
napi_value* result) napi_value* result)
``` ```
- `[in] env`: The environment that the API is invoked under. - `[in] env`: The environment that the API is invoked under.
- `[in] description`: Null-terminated character buffer representing a - `[in] description`: Optional napi_value which refers to a JavaScript
UTF8-encoded string to describe the symbol. String to be set as the description for the symbol.
- `[out] result`: A `napi_value` representing a JavaScript Symbol. - `[out] result`: A `napi_value` representing a JavaScript Symbol.
Returns `napi_ok` if the API succeeded. Returns `napi_ok` if the API succeeded.
@ -1299,8 +1303,8 @@ napi_status napi_create_string_utf16(napi_env env,
- `[in] env`: The environment that the API is invoked under. - `[in] env`: The environment that the API is invoked under.
- `[in] str`: Character buffer representing a UTF16-LE-encoded string. - `[in] str`: Character buffer representing a UTF16-LE-encoded string.
- `[in] length`: The length of the string in characters, or -1 if it is - `[in] length`: The length of the string in two-byte code units, or -1 if
null-terminated. it is null-terminated.
- `[out] result`: A `napi_value` representing a JavaScript String. - `[out] result`: A `napi_value` representing a JavaScript String.
Returns `napi_ok` if the API succeeded. Returns `napi_ok` if the API succeeded.
@ -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) [Section 6.1.4](https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type)
of the ECMAScript Language Specification. 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* #### *napi_create_string_utf8*
<!-- YAML <!-- YAML
added: v8.0.0 added: v8.0.0
@ -1323,8 +1352,8 @@ napi_status napi_create_string_utf8(napi_env env,
``` ```
- `[in] env`: The environment that the API is invoked under. - `[in] env`: The environment that the API is invoked under.
- `[in] s`: Character buffer representing a UTF8-encoded string. - `[in] str`: Character buffer representing a UTF8-encoded string.
- `[in] length`: The length of the string in characters, or -1 if it is - `[in] length`: The length of the string in bytes, or -1 if it is
null-terminated. null-terminated.
- `[out] result`: A `napi_value` representing a JavaScript String. - `[out] result`: A `napi_value` representing a JavaScript String.