Skip to content

doc: improve consistency in usage of NULL #32726

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

Closed
mhdawson wants to merge 3 commits into from
Closed

doc: improve consistency in usage of NULL #32726

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c079ce1
doc: improve consistency in usage of NULL
mhdawson Apr 8, 2020
6a70a48
squash: address comments
mhdawson Apr 13, 2020
248df68
squash: fixup
mhdawson Apr 13, 2020
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
Next Next commit
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 <michael_dawson@ca.ibm.com>
  • Loading branch information
@mhdawson
mhdawson committed Apr 8, 2020
commit c079ce1be833b8ab7c187773f464eab66216e312
38 changes: 19 additions & 19 deletions doc/api/n-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Comment thread
addaleax marked this conversation as resolved.
Outdated
* `[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.
Comment thread
addaleax marked this conversation as resolved.
Outdated

The function call does not return, the process will be terminated.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Comment thread
addaleax marked this conversation as resolved.
Outdated
* `[out] result`: A `napi_value` representing a JavaScript `String`.

Returns `napi_ok` if the API succeeded.
Expand All @@ -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.
Comment thread
addaleax marked this conversation as resolved.
Outdated
* `[out] result`: A `napi_value` representing a JavaScript `String`.

Returns `napi_ok` if the API succeeded.
Expand All @@ -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.
Comment thread
addaleax marked this conversation as resolved.
Outdated
* `[out] result`: A `napi_value` representing a JavaScript `String`.

Returns `napi_ok` if the API succeeded.
Expand Down Expand Up @@ -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`
Comment thread
addaleax marked this conversation as resolved.
Outdated
terminator.

Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value`
Expand All @@ -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`
Comment thread
addaleax marked this conversation as resolved.
Outdated
terminator.

Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value`
Expand All @@ -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.
Comment thread
addaleax marked this conversation as resolved.
Outdated

Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value`
is passed in it returns `napi_string_expected`.
Expand Down Expand Up @@ -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.
Comment thread
addaleax marked this conversation as resolved.
Outdated
* `[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
Expand Down Expand Up @@ -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.
Comment thread
addaleax marked this conversation as resolved.
Outdated
* `[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.)
Expand Down Expand Up @@ -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.
Comment thread
addaleax marked this conversation as resolved.
Outdated

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
Expand Down