From 62e940dfa6eb93644b29af45584559077f62996d Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 13 Jun 2017 01:02:52 -0400 Subject: [PATCH] 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: 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 Reviewed-By: James M Snell Reviewed-By: Jason Ginchereau Reviewed-By: Ingvar Stepanyan --- doc/api/n-api.md | 69 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 20 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 379af3b53c8b1e..d7a93c3c5c5a2a 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -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. @@ -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. @@ -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. @@ -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 ```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. @@ -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. @@ -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* + +```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*