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

doc: napi: make header style consistent

Browse Source 
Some of the API section headers had emphasis, while others did not.
Use a consistent style (no emphasis) for all of them, as that matches
our other API docs.

PR-URL: https://github.com/nodejs/node/pull/18122
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Kyle Farnung <kfarnung@microsoft.com>
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
This commit is contained in:
Ali Ijaz Sheikh 2018-01-12 10:25:02 -08:00
parent 3e062762e4
commit f75bc2c1a5
1 changed files with 88 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -71,7 +71,7 @@ N-API exposes the following fundamental datatypes as abstractions that are
consumed by the various APIs. These APIs should be treated as opaque,
introspectable only with other N-API calls.
### *napi_status*
### napi_status
Integral status code indicating the success or failure of a N-API call.
Currently, the following status codes are supported.
```C
@ -94,7 +94,7 @@ typedef enum {
If additional information is required upon an API returning a failed status,
it can be obtained by calling `napi_get_last_error_info`.
### *napi_extended_error_info*
### napi_extended_error_info
```C
typedef struct {
const char* error_message;
@ -114,7 +114,7 @@ typedef struct {
See the [Error Handling][] section for additional information.
### *napi_env*
### napi_env
`napi_env` is used to represent a context that the underlying N-API
implementation can use to persist VM-specific state. This structure is passed
to native functions when they're invoked, and it must be passed back when
@ -123,11 +123,11 @@ the initial native function was called must be passed to any subsequent
nested N-API calls. Caching the `napi_env` for the purpose of general reuse is
not allowed.
### *napi_value*
### napi_value
This is an opaque pointer that is used to represent a JavaScript value.
### N-API Memory Management types
#### *napi_handle_scope*
#### napi_handle_scope
This is an abstraction used to control and modify the lifetime of objects
created within a particular scope. In general, N-API values are created within
the context of a handle scope. When a native method is called from
@ -145,11 +145,11 @@ referenced from the current stack frame.
For more details, review the [Object Lifetime Management][].
#### *napi_escapable_handle_scope*
#### napi_escapable_handle_scope
Escapable handle scopes are a special type of handle scope to return values
created within a particular handle scope to a parent scope.
#### *napi_ref*
#### napi_ref
This is the abstraction to use to reference a `napi_value`. This allows for
users to manage the lifetimes of JavaScript values, including defining their
minimum lifetimes explicitly.
@ -157,12 +157,12 @@ minimum lifetimes explicitly.
For more details, review the [Object Lifetime Management][].
### N-API Callback types
#### *napi_callback_info*
#### napi_callback_info
Opaque datatype that is passed to a callback function. It can be used for
getting additional information about the context in which the callback was
invoked.
#### *napi_callback*
#### napi_callback
Function pointer type for user-provided native functions which are to be
exposed to JavaScript via N-API. Callback functions should satisfy the
following signature:
@ -170,7 +170,7 @@ following signature:
typedef napi_value (*napi_callback)(napi_env, napi_callback_info);
```
#### *napi_finalize*
#### napi_finalize
Function pointer type for add-on provided functions that allow the user to be
notified when externally-owned data is ready to be cleaned up because the
object with which it was associated with, has been garbage-collected. The user
@ -976,7 +976,7 @@ However, for better performance, it's better for the caller to make sure that
the `napi_value` in question is of the JavaScript type expected by the API.
### Enum types
#### *napi_valuetype*
#### napi_valuetype
```C
typedef enum {
// ES6 types (corresponds to typeof)
@ -999,7 +999,7 @@ the ECMAScript Language Specification.
In addition to types in that section, `napi_valuetype` can also represent
Functions and Objects with external data.
#### *napi_typedarray_type*
#### napi_typedarray_type
```C
typedef enum {
napi_int8_array,
@ -1020,7 +1020,7 @@ Elements of this enum correspond to
of the [ECMAScript Language Specification][].
### Object Creation Functions
#### *napi_create_array*
#### napi_create_array
<!-- YAML
added: v8.0.0
-->
@ -1038,7 +1038,7 @@ JavaScript arrays are described in
[Section 22.1](https://tc39.github.io/ecma262/#sec-array-objects) of the
ECMAScript Language Specification.
#### *napi_create_array_with_length*
#### napi_create_array_with_length
<!-- YAML
added: v8.0.0
-->
@ -1067,7 +1067,7 @@ JavaScript arrays are described in
[Section 22.1](https://tc39.github.io/ecma262/#sec-array-objects) of the
ECMAScript Language Specification.
#### *napi_create_arraybuffer*
#### napi_create_arraybuffer
<!-- YAML
added: v8.0.0
-->
@ -1099,7 +1099,7 @@ JavaScript ArrayBuffer objects are described in
[Section 24.1](https://tc39.github.io/ecma262/#sec-arraybuffer-objects)
of the ECMAScript Language Specification.
#### *napi_create_buffer*
#### napi_create_buffer
<!-- YAML
added: v8.0.0
-->
@ -1120,7 +1120,7 @@ Returns `napi_ok` if the API succeeded.
This API allocates a `node::Buffer` object. While this is still a
fully-supported data structure, in most cases using a TypedArray will suffice.
#### *napi_create_buffer_copy*
#### napi_create_buffer_copy
<!-- YAML
added: v8.0.0
-->
@ -1145,7 +1145,7 @@ This API allocates a `node::Buffer` object and initializes it with data copied
from the passed-in buffer. While this is still a fully-supported data
structure, in most cases using a TypedArray will suffice.
#### *napi_create_external*
#### napi_create_external
<!-- YAML
added: v8.0.0
-->
@ -1212,7 +1212,7 @@ JavaScript ArrayBuffers are described in
[Section 24.1](https://tc39.github.io/ecma262/#sec-arraybuffer-objects)
of the ECMAScript Language Specification.
#### *napi_create_external_buffer*
#### napi_create_external_buffer
<!-- YAML
added: v8.0.0
-->
@ -1243,7 +1243,7 @@ structure, in most cases using a TypedArray will suffice.
*Note*: For Node.js >=4 `Buffers` are Uint8Arrays.
#### *napi_create_function*
#### napi_create_function
<!-- YAML
added: v8.0.0
-->
@ -1276,7 +1276,7 @@ JavaScript Functions are described in
[Section 19.2](https://tc39.github.io/ecma262/#sec-function-objects)
of the ECMAScript Language Specification.
#### *napi_create_object*
#### napi_create_object
<!-- YAML
added: v8.0.0
-->
@ -1296,7 +1296,7 @@ The JavaScript Object type is described in
[Section 6.1.7](https://tc39.github.io/ecma262/#sec-object-type) of the
ECMAScript Language Specification.
#### *napi_create_symbol*
#### napi_create_symbol
<!-- YAML
added: v8.0.0
-->
@ -1319,7 +1319,7 @@ The JavaScript Symbol type is described in
[Section 19.4](https://tc39.github.io/ecma262/#sec-symbol-objects)
of the ECMAScript Language Specification.
#### *napi_create_typedarray*
#### napi_create_typedarray
<!-- YAML
added: v8.0.0
-->
@ -1355,7 +1355,7 @@ JavaScript TypedArray Objects are described in
of the ECMAScript Language Specification.
#### *napi_create_dataview*
#### napi_create_dataview
<!-- YAML
added: v8.3.0
-->
@ -1389,7 +1389,7 @@ JavaScript DataView Objects are described in
[Section 24.3][] of the ECMAScript Language Specification.
### Functions to convert from C types to N-API
#### *napi_create_int32*
#### napi_create_int32
<!-- YAML
added: v8.4.0
-->
@ -1410,7 +1410,7 @@ The JavaScript Number type is described in
[Section 6.1.6](https://tc39.github.io/ecma262/#sec-ecmascript-language-types-number-type)
of the ECMAScript Language Specification.
#### *napi_create_uint32*
#### napi_create_uint32
<!-- YAML
added: v8.4.0
-->
@ -1431,7 +1431,7 @@ The JavaScript Number type is described in
[Section 6.1.6](https://tc39.github.io/ecma262/#sec-ecmascript-language-types-number-type)
of the ECMAScript Language Specification.
#### *napi_create_int64*
#### napi_create_int64
<!-- YAML
added: v8.4.0
-->
@ -1458,7 +1458,7 @@ outside the range of
[`Number.MAX_SAFE_INTEGER`](https://tc39.github.io/ecma262/#sec-number.max_safe_integer)
(2^53 - 1) will lose precision.
#### *napi_create_double*
#### napi_create_double
<!-- YAML
added: v8.4.0
-->
@ -1479,7 +1479,7 @@ The JavaScript Number type is described in
[Section 6.1.6](https://tc39.github.io/ecma262/#sec-ecmascript-language-types-number-type)
of the ECMAScript Language Specification.
#### *napi_create_string_latin1*
#### napi_create_string_latin1
<!-- YAML
added: v8.0.0
-->
@ -1504,7 +1504,7 @@ 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_utf16*
#### napi_create_string_utf16
<!-- YAML
added: v8.0.0
-->
@ -1529,7 +1529,7 @@ 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
added: v8.0.0
-->
@ -1555,7 +1555,7 @@ The JavaScript String type is described in
of the ECMAScript Language Specification.
### Functions to convert from N-API to C types
#### *napi_get_array_length*
#### napi_get_array_length
<!-- YAML
added: v8.0.0
-->
@ -1578,7 +1578,7 @@ Array length is described in
[Section 22.1.4.1](https://tc39.github.io/ecma262/#sec-properties-of-array-instances-length)
of the ECMAScript Language Specification.
#### *napi_get_arraybuffer_info*
#### napi_get_arraybuffer_info
<!-- YAML
added: v8.0.0
-->
@ -1606,7 +1606,7 @@ which can be used to guarantee control over the lifetime of the
ArrayBuffer. It's also safe to use the returned data buffer within the same
callback as long as there are no calls to other APIs that might trigger a GC.
#### *napi_get_buffer_info*
#### napi_get_buffer_info
<!-- YAML
added: v8.0.0
-->
@ -1630,7 +1630,7 @@ and it's length.
*Warning*: Use caution while using this API since the underlying data buffer's
lifetime is not guaranteed if it's managed by the VM.
#### *napi_get_prototype*
#### napi_get_prototype
<!-- YAML
added: v8.0.0
-->
@ -1648,7 +1648,7 @@ not the same as the function's `prototype` property).
Returns `napi_ok` if the API succeeded.
#### *napi_get_typedarray_info*
#### napi_get_typedarray_info
<!-- YAML
added: v8.0.0
-->
@ -1680,7 +1680,7 @@ is managed by the VM
#### *napi_get_dataview_info*
#### napi_get_dataview_info
<!-- YAML
added: v8.3.0
-->
@ -1708,7 +1708,7 @@ Returns `napi_ok` if the API succeeded.
This API returns various properties of a DataView.
#### *napi_get_value_bool*
#### napi_get_value_bool
<!-- YAML
added: v8.0.0
-->
@ -1727,7 +1727,7 @@ passed in it returns `napi_boolean_expected`.
This API returns the C boolean primitive equivalent of the given JavaScript
Boolean.
#### *napi_get_value_double*
#### napi_get_value_double
<!-- YAML
added: v8.0.0
-->
@ -1749,7 +1749,7 @@ This API returns the C double primitive equivalent of the given JavaScript
Number.
#### *napi_get_value_external*
#### napi_get_value_external
<!-- YAML
added: v8.0.0
-->
@ -1769,7 +1769,7 @@ passed in it returns `napi_invalid_arg`.
This API retrieves the external data pointer that was previously passed to
`napi_create_external()`.
#### *napi_get_value_int32*
#### napi_get_value_int32
<!-- YAML
added: v8.0.0
-->
@ -1792,7 +1792,7 @@ of the given JavaScript Number. If the number exceeds the range of the
bottom 32 bits. This can result in a large positive number becoming
a negative number if the value is > 2^31 -1.
#### *napi_get_value_int64*
#### napi_get_value_int64
<!-- YAML
added: v8.0.0
-->
@ -1812,7 +1812,7 @@ is passed in it returns `napi_number_expected`.
This API returns the C int64 primitive equivalent of the given
JavaScript Number
#### *napi_get_value_string_latin1*
#### napi_get_value_string_latin1
<!-- YAML
added: v8.0.0
-->
@ -1839,7 +1839,7 @@ is passed in it returns `napi_string_expected`.
This API returns the ISO-8859-1-encoded string corresponding the value passed
in.
#### *napi_get_value_string_utf8*
#### napi_get_value_string_utf8
<!-- YAML
added: v8.0.0
-->
@ -1865,7 +1865,7 @@ is passed in it returns `napi_string_expected`.
This API returns the UTF8-encoded string corresponding the value passed in.
#### *napi_get_value_string_utf16*
#### napi_get_value_string_utf16
<!-- YAML
added: v8.0.0
-->
@ -1891,7 +1891,7 @@ is passed in it returns `napi_string_expected`.
This API returns the UTF16-encoded string corresponding the value passed in.
#### *napi_get_value_uint32*
#### napi_get_value_uint32
<!-- YAML
added: v8.0.0
-->
@ -1913,7 +1913,7 @@ This API returns the C primitive equivalent of the given `napi_value` as a
`uint32_t`.
### Functions to get global instances
#### *napi_get_boolean*
#### napi_get_boolean
<!-- YAML
added: v8.0.0
-->
@ -1931,7 +1931,7 @@ Returns `napi_ok` if the API succeeded.
This API is used to return the JavaScript singleton object that is used to
represent the given boolean value
#### *napi_get_global*
#### napi_get_global
<!-- YAML
added: v8.0.0
-->
@ -1946,7 +1946,7 @@ Returns `napi_ok` if the API succeeded.
This API returns the global Object.
#### *napi_get_null*
#### napi_get_null
<!-- YAML
added: v8.0.0
-->
@ -1961,7 +1961,7 @@ Returns `napi_ok` if the API succeeded.
This API returns the null Object.
#### *napi_get_undefined*
#### napi_get_undefined
<!-- YAML
added: v8.0.0
-->
@ -1989,7 +1989,7 @@ These APIs support doing one of the following:
2. Check the type of a JavaScript value
3. Check for equality between two JavaScript values
### *napi_coerce_to_bool*
### napi_coerce_to_bool
<!-- YAML
added: v8.0.0
-->
@ -2010,7 +2010,7 @@ This API implements the abstract operation ToBoolean as defined in
of the ECMAScript Language Specification.
This API can be re-entrant if getters are defined on the passed-in Object.
### *napi_coerce_to_number*
### napi_coerce_to_number
<!-- YAML
added: v8.0.0
-->
@ -2031,7 +2031,7 @@ This API implements the abstract operation ToNumber as defined in
of the ECMAScript Language Specification.
This API can be re-entrant if getters are defined on the passed-in Object.
### *napi_coerce_to_object*
### napi_coerce_to_object
<!-- YAML
added: v8.0.0
-->
@ -2052,7 +2052,7 @@ This API implements the abstract operation ToObject as defined in
of the ECMAScript Language Specification.
This API can be re-entrant if getters are defined on the passed-in Object.
### *napi_coerce_to_string*
### napi_coerce_to_string
<!-- YAML
added: v8.0.0
-->
@ -2073,7 +2073,7 @@ This API implements the abstract operation ToString as defined in
of the ECMAScript Language Specification.
This API can be re-entrant if getters are defined on the passed-in Object.
### *napi_typeof*
### napi_typeof
<!-- YAML
added: v8.0.0
-->
@ -2094,7 +2094,7 @@ the object as defined in [Section 12.5.5][] of the ECMAScript Language
Specification. However, it has support for detecting an External value.
If `value` has a type that is invalid, an error is returned.
### *napi_instanceof*
### napi_instanceof
<!-- YAML
added: v8.0.0
-->
@ -2119,7 +2119,7 @@ defined in
[Section 12.10.4](https://tc39.github.io/ecma262/#sec-instanceofoperator)
of the ECMAScript Language Specification.
### *napi_is_array*
### napi_is_array
<!-- YAML
added: v8.0.0
-->
@ -2137,7 +2137,7 @@ This API represents invoking the `IsArray` operation on the object
as defined in [Section 7.2.2](https://tc39.github.io/ecma262/#sec-isarray)
of the ECMAScript Language Specification.
### *napi_is_arraybuffer*
### napi_is_arraybuffer
<!-- YAML
added: v8.0.0
-->
@ -2153,7 +2153,7 @@ Returns `napi_ok` if the API succeeded.
This API checks if the Object passsed in is an array buffer.
### *napi_is_buffer*
### napi_is_buffer
<!-- YAML
added: v8.0.0
-->
@ -2170,7 +2170,7 @@ Returns `napi_ok` if the API succeeded.
This API checks if the Object passsed in is a buffer.
### *napi_is_error*
### napi_is_error
<!-- YAML
added: v8.0.0
-->
@ -2186,7 +2186,7 @@ Returns `napi_ok` if the API succeeded.
This API checks if the Object passsed in is an Error.
### *napi_is_typedarray*
### napi_is_typedarray
<!-- YAML
added: v8.0.0
-->
@ -2204,7 +2204,7 @@ This API checks if the Object passsed in is a typed array.
### *napi_is_dataview*
### napi_is_dataview
<!-- YAML
added: v8.3.0
-->
@ -2221,7 +2221,7 @@ Returns `napi_ok` if the API succeeded.
This API checks if the Object passed in is a DataView.
### *napi_strict_equals*
### napi_strict_equals
<!-- YAML
added: v8.0.0
-->
@ -2375,7 +2375,7 @@ if (status != napi_ok) return status;
```
### Structures
#### *napi_property_attributes*
#### napi_property_attributes
```C
typedef enum {
napi_default = 0,
@ -2409,7 +2409,7 @@ a static property on a class as opposed to an instance property, which is the
default. This is used only by [`napi_define_class`][]. It is ignored by
`napi_define_properties`.
#### *napi_property_descriptor*
#### napi_property_descriptor
```C
typedef struct {
// One of utf8name or name should be NULL.
@ -2455,7 +2455,7 @@ this function is invoked.
See [`napi_property_attributes`](#n_api_napi_property_attributes).
### Functions
#### *napi_get_property_names*
#### napi_get_property_names
<!-- YAML
added: v8.0.0
-->
@ -2476,7 +2476,7 @@ Returns `napi_ok` if the API succeeded.
This API returns the array of propertys for the Object passed in
#### *napi_set_property*
#### napi_set_property
<!-- YAML
added: v8.0.0
-->
@ -2496,7 +2496,7 @@ Returns `napi_ok` if the API succeeded.
This API set a property on the Object passed in.
#### *napi_get_property*
#### napi_get_property
<!-- YAML
added: v8.0.0
-->
@ -2517,7 +2517,7 @@ Returns `napi_ok` if the API succeeded.
This API gets the requested property from the Object passed in.
#### *napi_has_property*
#### napi_has_property
<!-- YAML
added: v8.0.0
-->
@ -2538,7 +2538,7 @@ Returns `napi_ok` if the API succeeded.
This API checks if the Object passed in has the named property.
#### *napi_delete_property*
#### napi_delete_property
<!-- YAML
added: v8.2.0
-->
@ -2560,7 +2560,7 @@ Returns `napi_ok` if the API succeeded.
This API attempts to delete the `key` own property from `object`.
#### *napi_has_own_property*
#### napi_has_own_property
<!-- YAML
added: v8.2.0
-->
@ -2583,7 +2583,7 @@ be a string or a Symbol, or an error will be thrown. N-API will not perform any
conversion between data types.
#### *napi_set_named_property*
#### napi_set_named_property
<!-- YAML
added: v8.0.0
-->
@ -2604,7 +2604,7 @@ Returns `napi_ok` if the API succeeded.
This method is equivalent to calling [`napi_set_property`][] with a `napi_value`
created from the string passed in as `utf8Name`
#### *napi_get_named_property*
#### napi_get_named_property
<!-- YAML
added: v8.0.0
-->
@ -2625,7 +2625,7 @@ Returns `napi_ok` if the API succeeded.
This method is equivalent to calling [`napi_get_property`][] with a `napi_value`
created from the string passed in as `utf8Name`
#### *napi_has_named_property*
#### napi_has_named_property
<!-- YAML
added: v8.0.0
-->
@ -2646,7 +2646,7 @@ Returns `napi_ok` if the API succeeded.
This method is equivalent to calling [`napi_has_property`][] with a `napi_value`
created from the string passed in as `utf8Name`
#### *napi_set_element*
#### napi_set_element
<!-- YAML
added: v8.0.0
-->
@ -2666,7 +2666,7 @@ Returns `napi_ok` if the API succeeded.
This API sets and element on the Object passed in.
#### *napi_get_element*
#### napi_get_element
<!-- YAML
added: v8.0.0
-->
@ -2686,7 +2686,7 @@ Returns `napi_ok` if the API succeeded.
This API gets the element at the requested index.
#### *napi_has_element*
#### napi_has_element
<!-- YAML
added: v8.0.0
-->
@ -2707,7 +2707,7 @@ Returns `napi_ok` if the API succeeded.
This API returns if the Object passed in has an element at the
requested index.
#### *napi_delete_element*
#### napi_delete_element
<!-- YAML
added: v8.2.0
-->
@ -2728,7 +2728,7 @@ Returns `napi_ok` if the API succeeded.
This API attempts to delete the specified `index` from `object`.
#### *napi_define_properties*
#### napi_define_properties
<!-- YAML
added: v8.0.0
-->
@ -2771,7 +2771,7 @@ like a regular JavaScript function call, or as a constructor
function.
### *napi_call_function*
### napi_call_function
<!-- YAML
added: v8.0.0
-->
@ -2837,7 +2837,7 @@ status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;
```
### *napi_create_function*
### napi_create_function
<!-- YAML
added: v8.0.0
-->
@ -2905,7 +2905,7 @@ myaddon.sayHello();
`NAPI_MODULE` in the earlier snippet but the name of the target in `binding.gyp`
responsible for creating the `.node` file.
### *napi_get_cb_info*
### napi_get_cb_info
<!-- YAML
added: v8.0.0
-->
@ -2935,7 +2935,7 @@ Returns `napi_ok` if the API succeeded.
This method is used within a callback function to retrieve details about the
call like the arguments and the `this` pointer from a given callback info.
### *napi_get_new_target*
### napi_get_new_target
<!-- YAML
added: v8.6.0
-->
@ -2954,7 +2954,7 @@ Returns `napi_ok` if the API succeeded.
This API returns the `new.target` of the constructor call. If the current
callback is not a constructor call, the result is `NULL`.
### *napi_new_instance*
### napi_new_instance
<!-- YAML
added: v8.0.0
-->
@ -3049,7 +3049,7 @@ if (is_instance) {
The reference must be freed once it is no longer needed.
### *napi_define_class*
### napi_define_class
<!-- YAML
added: v8.0.0
-->
@ -3105,7 +3105,7 @@ case, to prevent the function value from being garbage-collected, create a
persistent reference to it using [`napi_create_reference`][] and ensure the
reference count is kept >= 1.
### *napi_wrap*
### napi_wrap
<!-- YAML
added: v8.0.0
-->
@ -3167,7 +3167,7 @@ native instance associated with it by virtue of a previous call to
another native instance with the given object, call `napi_remove_wrap()` on it
first.
### *napi_unwrap*
### napi_unwrap
<!-- YAML
added: v8.0.0
-->
@ -3192,7 +3192,7 @@ method or accessor, then the `this` argument to the callback is the wrapper
object; the wrapped C++ instance that is the target of the call can be obtained
then by calling `napi_unwrap()` on the wrapper object.
### *napi_remove_wrap*
### napi_remove_wrap
<!-- YAML
added: v8.5.0
-->