From c079ce1be833b8ab7c187773f464eab66216e312 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 8 Apr 2020 16:17:37 -0400 Subject: [PATCH 1/3] doc: improve consistency in usage of NULL - add backticks around use of NULL - convert from null to NULL where we mean NULL Signed-off-by: Michael Dawson --- doc/api/n-api.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index a38ebbd6f8614b..bc2492e01b93bd 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -860,7 +860,7 @@ SemVer applying. In order to support this model with N-API, both in internal functionality and for module specific functionality (as its good practice), the `throw_` and `create_` functions take an optional code parameter which is the string for the code -to be added to the error object. If the optional parameter is NULL +to be added to the error object. If the optional parameter is `NULL` then no code will be associated with the error. If a code is provided, the name associated with the error is also updated to be: @@ -1058,7 +1058,7 @@ napi_status napi_get_and_clear_last_exception(napi_env env, ``` * `[in] env`: The environment that the API is invoked under. -* `[out] result`: The exception if one is pending, NULL otherwise. +* `[out] result`: The exception if one is pending, `NULL` otherwise. Returns `napi_ok` if the API succeeded. @@ -1117,10 +1117,10 @@ NAPI_NO_RETURN void napi_fatal_error(const char* location, * `[in] location`: Optional location at which the error occurred. * `[in] location_len`: The length of the location in bytes, or - `NAPI_AUTO_LENGTH` if it is null-terminated. + `NAPI_AUTO_LENGTH` if it is `NULL`-terminated. * `[in] message`: The message associated with the error. * `[in] message_len`: The length of the message in bytes, or `NAPI_AUTO_LENGTH` - if it is null-terminated. + if it is `NULL`-terminated. The function call does not return, the process will be terminated. @@ -1350,7 +1350,7 @@ then be modified through [`napi_reference_ref`][] and [`napi_reference_unref`][]. If an object is collected while the count for a reference is 0, all subsequent calls to get the object associated with the reference [`napi_get_reference_value`][] -will return NULL for the returned `napi_value`. An attempt to call +will return `NULL` for the returned `napi_value`. An attempt to call [`napi_reference_ref`][] for a reference whose object has been collected will result in an error. @@ -1473,7 +1473,7 @@ Returns `napi_ok` if the API succeeded. If still valid, this API returns the `napi_value` representing the JavaScript `Object` associated with the `napi_ref`. Otherwise, result -will be NULL. +will be `NULL`. ### Cleanup on exit of the current Node.js instance @@ -1549,7 +1549,7 @@ napi_value Init(napi_env env, napi_value exports); The return value from `Init` is treated as the `exports` object for the module. The `Init` method is passed an empty object via the `exports` parameter as a -convenience. If `Init` returns NULL, the parameter passed as `exports` is +convenience. If `Init` returns `NULL`, the parameter passed as `exports` is exported by the module. N-API modules cannot modify the `module` object but can specify anything as the `exports` property of the module. @@ -2342,7 +2342,7 @@ napi_status napi_create_string_latin1(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] str`: Character buffer representing an ISO-8859-1-encoded string. * `[in] length`: The length of the string in bytes, or `NAPI_AUTO_LENGTH` if it - is null-terminated. + is `NULL`-terminated. * `[out] result`: A `napi_value` representing a JavaScript `String`. Returns `napi_ok` if the API succeeded. @@ -2369,7 +2369,7 @@ 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 two-byte code units, or - `NAPI_AUTO_LENGTH` if it is null-terminated. + `NAPI_AUTO_LENGTH` if it is `NULL`-terminated. * `[out] result`: A `napi_value` representing a JavaScript `String`. Returns `napi_ok` if the API succeeded. @@ -2396,7 +2396,7 @@ napi_status napi_create_string_utf8(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] str`: Character buffer representing a UTF8-encoded string. * `[in] length`: The length of the string in bytes, or `NAPI_AUTO_LENGTH` if it - is null-terminated. + is `NULL`-terminated. * `[out] result`: A `napi_value` representing a JavaScript `String`. Returns `napi_ok` if the API succeeded. @@ -2827,11 +2827,11 @@ napi_status napi_get_value_string_latin1(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] value`: `napi_value` representing JavaScript string. -* `[in] buf`: Buffer to write the ISO-8859-1-encoded string into. If NULL is +* `[in] buf`: Buffer to write the ISO-8859-1-encoded string into. If `NULL` is passed in, the length of the string (in bytes) is returned. * `[in] bufsize`: Size of the destination buffer. When this value is insufficient, the returned string will be truncated. -* `[out] result`: Number of bytes copied into the buffer, excluding the null +* `[out] result`: Number of bytes copied into the buffer, excluding the `NULL` terminator. Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` @@ -2856,11 +2856,11 @@ napi_status napi_get_value_string_utf8(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] value`: `napi_value` representing JavaScript string. -* `[in] buf`: Buffer to write the UTF8-encoded string into. If NULL is passed +* `[in] buf`: Buffer to write the UTF8-encoded string into. If `NULL` is passed in, the length of the string (in bytes) is returned. * `[in] bufsize`: Size of the destination buffer. When this value is insufficient, the returned string will be truncated. -* `[out] result`: Number of bytes copied into the buffer, excluding the null +* `[out] result`: Number of bytes copied into the buffer, excluding the `NULL` terminator. Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` @@ -2884,12 +2884,12 @@ napi_status napi_get_value_string_utf16(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] value`: `napi_value` representing JavaScript string. -* `[in] buf`: Buffer to write the UTF16-LE-encoded string into. If NULL is +* `[in] buf`: Buffer to write the UTF16-LE-encoded string into. If `NULL` is passed in, the length of the string (in 2-byte code units) is returned. * `[in] bufsize`: Size of the destination buffer. When this value is insufficient, the returned string will be truncated. * `[out] result`: Number of 2-byte code units copied into the buffer, excluding - the null terminator. + the `NULL` terminator. Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` is passed in it returns `napi_string_expected`. @@ -4029,7 +4029,7 @@ napi_status napi_create_function(napi_env env, * `[in] utf8Name`: The name of the function encoded as UTF8. This is visible within JavaScript as the new function object's `name` property. * `[in] length`: The length of the `utf8name` in bytes, or `NAPI_AUTO_LENGTH` if - it is null-terminated. + it is `NULL`-terminated. * `[in] cb`: The native function which should be called when this function object is invoked. * `[in] data`: User-provided data context. This will be passed back into the @@ -4263,7 +4263,7 @@ napi_status napi_define_class(napi_env env, not required to be the same as the C++ class name, though it is recommended for clarity. * `[in] length`: The length of the `utf8name` in bytes, or `NAPI_AUTO_LENGTH` - if it is null-terminated. + if it is `NULL`-terminated. * `[in] constructor`: Callback function that handles constructing instances of the class. (This should be a static method on the class, not an actual C++ constructor function.) @@ -4555,7 +4555,7 @@ This API allocates a work object that is used to execute logic asynchronously. It should be freed using [`napi_delete_async_work`][] once the work is no longer required. -`async_resource_name` should be a null-terminated, UTF-8-encoded string. +`async_resource_name` should be a `NULL`-terminated, UTF-8-encoded string. The `async_resource_name` identifier is provided by the user and should be representative of the type of async work being performed. It is also recommended From 6a70a48f392df336471d3494c5bd40c613f34b56 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 13 Apr 2020 17:21:29 -0400 Subject: [PATCH 2/3] squash: address comments --- doc/api/n-api.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index bc2492e01b93bd..0ea2e4efb5bbf1 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -12,7 +12,7 @@ Node.js itself. This API will be Application Binary Interface (ABI) stable across versions of Node.js. It is intended to insulate Addons from changes in the underlying JavaScript engine and allow modules compiled for one major version to run on later major versions of Node.js without -recompilation. The [ABI Stability][] guide provides a more in-depth explanation. +recompilation. The [ABI Stability][] guide provides a mor'e in-depth explanation. Addons are built/packaged with the same approach/tools outlined in the section titled [C++ Addons][]. The only difference is the set of APIs that are used by @@ -1117,10 +1117,10 @@ NAPI_NO_RETURN void napi_fatal_error(const char* location, * `[in] location`: Optional location at which the error occurred. * `[in] location_len`: The length of the location in bytes, or - `NAPI_AUTO_LENGTH` if it is `NULL`-terminated. + `NAPI_AUTO_LENGTH` if it is null-terminated. * `[in] message`: The message associated with the error. * `[in] message_len`: The length of the message in bytes, or `NAPI_AUTO_LENGTH` - if it is `NULL`-terminated. + if it is null-terminated. The function call does not return, the process will be terminated. @@ -2342,7 +2342,7 @@ napi_status napi_create_string_latin1(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] str`: Character buffer representing an ISO-8859-1-encoded string. * `[in] length`: The length of the string in bytes, or `NAPI_AUTO_LENGTH` if it - is `NULL`-terminated. + is null-terminated. * `[out] result`: A `napi_value` representing a JavaScript `String`. Returns `napi_ok` if the API succeeded. @@ -2369,7 +2369,7 @@ 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 two-byte code units, or - `NAPI_AUTO_LENGTH` if it is `NULL`-terminated. + `NAPI_AUTO_LENGTH` if it is null-terminated. * `[out] result`: A `napi_value` representing a JavaScript `String`. Returns `napi_ok` if the API succeeded. @@ -2396,7 +2396,7 @@ napi_status napi_create_string_utf8(napi_env env, * `[in] env`: The environment that the API is invoked under. * `[in] str`: Character buffer representing a UTF8-encoded string. * `[in] length`: The length of the string in bytes, or `NAPI_AUTO_LENGTH` if it - is `NULL`-terminated. + is null-terminated. * `[out] result`: A `napi_value` representing a JavaScript `String`. Returns `napi_ok` if the API succeeded. @@ -2831,7 +2831,7 @@ napi_status napi_get_value_string_latin1(napi_env env, passed in, the length of the string (in bytes) is returned. * `[in] bufsize`: Size of the destination buffer. When this value is insufficient, the returned string will be truncated. -* `[out] result`: Number of bytes copied into the buffer, excluding the `NULL` +* `[out] result`: Number of bytes copied into the buffer, excluding the null terminator. Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` @@ -2860,7 +2860,7 @@ napi_status napi_get_value_string_utf8(napi_env env, in, the length of the string (in bytes) is returned. * `[in] bufsize`: Size of the destination buffer. When this value is insufficient, the returned string will be truncated. -* `[out] result`: Number of bytes copied into the buffer, excluding the `NULL` +* `[out] result`: Number of bytes copied into the buffer, excluding the null terminator. Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` @@ -2889,7 +2889,7 @@ napi_status napi_get_value_string_utf16(napi_env env, * `[in] bufsize`: Size of the destination buffer. When this value is insufficient, the returned string will be truncated. * `[out] result`: Number of 2-byte code units copied into the buffer, excluding - the `NULL` terminator. + the null terminator. Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` is passed in it returns `napi_string_expected`. @@ -4029,7 +4029,7 @@ napi_status napi_create_function(napi_env env, * `[in] utf8Name`: The name of the function encoded as UTF8. This is visible within JavaScript as the new function object's `name` property. * `[in] length`: The length of the `utf8name` in bytes, or `NAPI_AUTO_LENGTH` if - it is `NULL`-terminated. + it is null-terminated. * `[in] cb`: The native function which should be called when this function object is invoked. * `[in] data`: User-provided data context. This will be passed back into the @@ -4263,7 +4263,7 @@ napi_status napi_define_class(napi_env env, not required to be the same as the C++ class name, though it is recommended for clarity. * `[in] length`: The length of the `utf8name` in bytes, or `NAPI_AUTO_LENGTH` - if it is `NULL`-terminated. + if it is null-terminated. * `[in] constructor`: Callback function that handles constructing instances of the class. (This should be a static method on the class, not an actual C++ constructor function.) @@ -4555,7 +4555,7 @@ This API allocates a work object that is used to execute logic asynchronously. It should be freed using [`napi_delete_async_work`][] once the work is no longer required. -`async_resource_name` should be a `NULL`-terminated, UTF-8-encoded string. +`async_resource_name` should be a null-terminated, UTF-8-encoded string. The `async_resource_name` identifier is provided by the user and should be representative of the type of async work being performed. It is also recommended From 248df68234ac6ee34131e5019eb4afd1c7350b95 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 13 Apr 2020 17:22:14 -0400 Subject: [PATCH 3/3] squash: fixup --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 0ea2e4efb5bbf1..71796504b19da0 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -12,7 +12,7 @@ Node.js itself. This API will be Application Binary Interface (ABI) stable across versions of Node.js. It is intended to insulate Addons from changes in the underlying JavaScript engine and allow modules compiled for one major version to run on later major versions of Node.js without -recompilation. The [ABI Stability][] guide provides a mor'e in-depth explanation. +recompilation. The [ABI Stability][] guide provides a more in-depth explanation. Addons are built/packaged with the same approach/tools outlined in the section titled [C++ Addons][]. The only difference is the set of APIs that are used by