Skip to content

Commit c27ffad

Browse files
mhdawsonaddaleax
authored andcommitted
doc: fix a few n-api doc issues
- 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: #13650 Fixes: #13555 Fixes: #13556 Fixes: #13562 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jason Ginchereau <[email protected]> Reviewed-By: Ingvar Stepanyan <[email protected]>
1 parent c142f1d commit c27ffad

File tree

1 file changed

+49
-20
lines changed

1 file changed

+49
-20
lines changed

doc/api/n-api.md

+49-20
Original file line numberDiff line numberDiff line change
@@ -406,11 +406,12 @@ added: v8.0.0
406406
-->
407407
```C
408408
NODE_EXTERN napi_status napi_create_error(napi_env env,
409-
const char* msg,
409+
napi_value msg,
410410
napi_value* result);
411411
```
412412
- `[in] env`: The environment that the API is invoked under.
413-
- `[in] msg`: C string representing the text to be associated with.
413+
- `[in] msg`: napi_value that references a JavaScript String to be
414+
used as the message for the Error.
414415
- `[out] result`: `napi_value` representing the error created.
415416
416417
Returns `napi_ok` if the API succeeded.
@@ -423,11 +424,12 @@ added: v8.0.0
423424
-->
424425
```C
425426
NODE_EXTERN napi_status napi_create_type_error(napi_env env,
426-
const char* msg,
427+
napi_value msg,
427428
napi_value* result);
428429
```
429430
- `[in] env`: The environment that the API is invoked under.
430-
- `[in] msg`: C string representing the text to be associated with.
431+
- `[in] msg`: napi_value that references a JavaScript String to be
432+
used as the message for the Error.
431433
- `[out] result`: `napi_value` representing the error created.
432434

433435
Returns `napi_ok` if the API succeeded.
@@ -445,7 +447,8 @@ NODE_EXTERN napi_status napi_create_range_error(napi_env env,
445447
napi_value* result);
446448
```
447449
- `[in] env`: The environment that the API is invoked under.
448-
- `[in] msg`: C string representing the text to be associated with.
450+
- `[in] msg`: napi_value that references a JavaScript String to be
451+
used as the message for the Error.
449452
- `[out] result`: `napi_value` representing the error created.
450453
451454
Returns `napi_ok` if the API succeeded.
@@ -562,16 +565,17 @@ for (int i = 0; i < 1000000; i++) {
562565
```
563566

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

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

574-
The request to promote a handle is made through the [`napi_escape_handle`][].
577+
The request to promote a handle is made through [`napi_escape_handle`][] which
578+
can only be called once.
575579

576580
#### napi_open_handle_scope
577581
<!-- YAML
@@ -618,7 +622,7 @@ NODE_EXTERN napi_status
618622
619623
Returns `napi_ok` if the API succeeded.
620624
621-
This API open a new scope from which objects can be promoted
625+
This API open a new scope from which one object can be promoted
622626
to the outer scope.
623627
624628
#### napi_close_escapable_handle_scope
@@ -657,9 +661,9 @@ Object in the outer scope.
657661
658662
Returns `napi_ok` if the API succeeded.
659663
660-
This API promotes the handle to the JavaScript object so that it valid
661-
for the lifetime of the outer scope.
662-
664+
This API promotes the handle to the JavaScript object so that it is valid
665+
for the lifetime of the outer scope. It can only be called once per scope.
666+
If it is called more than once an error will be returned.
663667
664668
### References to objects with a lifespan longer than that of the native method
665669
In some cases an addon will need to be able to create and reference objects
@@ -1212,13 +1216,13 @@ added: v8.0.0
12121216
-->
12131217
```C
12141218
napi_status napi_create_symbol(napi_env env,
1215-
const char* description,
1219+
napi_value description,
12161220
napi_value* result)
12171221
```
12181222
12191223
- `[in] env`: The environment that the API is invoked under.
1220-
- `[in] description`: Null-terminated character buffer representing a
1221-
UTF8-encoded string to describe the symbol.
1224+
- `[in] description`: Optional napi_value which refers to a JavaScript
1225+
String to be set as the description for the symbol.
12221226
- `[out] result`: A `napi_value` representing a JavaScript Symbol.
12231227
12241228
Returns `napi_ok` if the API succeeded.
@@ -1299,8 +1303,8 @@ napi_status napi_create_string_utf16(napi_env env,
12991303

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

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

1318+
#### *napi_create_string_latin1*
1319+
<!-- YAML
1320+
added: v8.0.0
1321+
-->
1322+
```C
1323+
NAPI_EXTERN napi_status napi_create_string_latin1(napi_env env,
1324+
const char* str,
1325+
size_t length,
1326+
napi_value* result);
1327+
```
1328+
1329+
- `[in] env`: The environment that the API is invoked under.
1330+
- `[in] str`: Character buffer representing a latin1-encoded string.
1331+
- `[in] length`: The length of the string in bytes, or -1 if it is
1332+
null-terminated.
1333+
- `[out] result`: A `napi_value` representing a JavaScript String.
1334+
1335+
Returns `napi_ok` if the API succeeded.
1336+
1337+
This API creates a JavaScript String object from a latin1-encoded C string.
1338+
1339+
The JavaScript String type is described in
1340+
[Section 6.1.4](https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type)
1341+
of the ECMAScript Language Specification.
1342+
13141343
#### *napi_create_string_utf8*
13151344
<!-- YAML
13161345
added: v8.0.0
@@ -1323,8 +1352,8 @@ napi_status napi_create_string_utf8(napi_env env,
13231352
```
13241353

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

0 commit comments

Comments
 (0)