From 26c28d2294ed5b1b502e9a0fbeda6ccd30dfbd41 Mon Sep 17 00:00:00 2001 From: Kenvin Davies Date: Fri, 21 Sep 2018 21:27:34 +0200 Subject: [PATCH] doc: doc cleanup - Some fix on bigint and dataview. - Add section dedicated to prebuild tools. PR-URL: https://github.com/nodejs/node-addon-api/pull/353 Reviewed-By: Michael Dawson --- README.md | 2 ++ doc/bigint.md | 22 ++++++------ doc/dataview.md | 50 +++++++++++++-------------- doc/prebuild_tools.md | 16 +++++++++ doc/working_with_javascript_values.md | 17 ++++----- 5 files changed, 62 insertions(+), 45 deletions(-) create mode 100644 doc/prebuild_tools.md diff --git a/README.md b/README.md index 90c8bb0..febfbe6 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,7 @@ to ideas specified in the **ECMA262 Language Specification**. - [Conversion tool](doc/conversion-tool.md) - [Checker tool](doc/checker-tool.md) - [Generator](doc/generator.md) + - [Prebuild tools](doc/prebuild_tools.md) @@ -72,6 +73,7 @@ The following is the documentation for node-addon-api. - [String](doc/string.md) - [Name](doc/basic_types.md#name) - [Number](doc/number.md) + - [BigInt](doc/bigint.md) - [Boolean](doc/boolean.md) - [Env](doc/env.md) - [Value](doc/value.md) diff --git a/doc/bigint.md b/doc/bigint.md index 6d3b0af..cc98104 100644 --- a/doc/bigint.md +++ b/doc/bigint.md @@ -7,24 +7,23 @@ A JavaScript BigInt value. ### New ```cpp -static BigInt New(Napi::Env env, int64_t value); -static BigInt New(Napi::Env env, uint64_t value); +static Napi::BigInt Napi::BigInt::New(Napi::Env env, int64_t value); ``` - - `[in] env`: The environment in which to construct the `BigInt` object. + - `[in] env`: The environment in which to construct the `Napi::BigInt` object. - `[in] value`: The value the JavaScript `BigInt` will contain These APIs convert the C `int64_t` and `uint64_t` types to the JavaScript `BigInt` type. ```cpp -static BigInt New(Napi::Env env, +static Napi::BigInt Napi::BigInt::New(Napi::Env env, int sign_bit, size_t word_count, const uint64_t* words); ``` - - `[in] env`: The environment in which to construct the `BigInt` object. + - `[in] env`: The environment in which to construct the `Napi::BigInt` object. - `[in] sign_bit`: Determines if the resulting `BigInt` will be positive or negative. - `[in] word_count`: The length of the words array. - `[in] words`: An array of `uint64_t` little-endian 64-bit words. @@ -43,16 +42,15 @@ Returns a new JavaScript `BigInt`. Napi::BigInt(); ``` -Returns a new empty JavaScript `BigInt`. +Returns a new empty JavaScript `Napi::BigInt`. ### Int64Value ```cpp -int64_t Int64Value(bool* lossless) const; +int64_t Napi::BitInt::Int64Value(bool* lossless) const; ``` - - `[out] lossless`: Indicates whether the `BigInt` value was converted - losslessly. + - `[out] lossless`: Indicates whether the `BigInt` value was converted losslessly. Returns the C `int64_t` primitive equivalent of the given JavaScript `BigInt`. If needed it will truncate the value, setting lossless to false. @@ -60,7 +58,7 @@ Returns the C `int64_t` primitive equivalent of the given JavaScript ### Uint64Value ```cpp -uint64_t Uint64Value(bool* lossless) const; +uint64_t Napi::BigInt::Uint64Value(bool* lossless) const; ``` - `[out] lossless`: Indicates whether the `BigInt` value was converted @@ -72,7 +70,7 @@ Returns the C `uint64_t` primitive equivalent of the given JavaScript ### WordCount ```cpp -size_t WordCount() const; +size_t Napi::BigInt::WordCount() const; ``` Returns the number of words needed to store this `BigInt` value. @@ -80,7 +78,7 @@ Returns the number of words needed to store this `BigInt` value. ### ToWords ```cpp -void ToWords(size_t* word_count, int* sign_bit, uint64_t* words); +void Napi::BigInt::ToWords(size_t* word_count, int* sign_bit, uint64_t* words); ``` - `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive diff --git a/doc/dataview.md b/doc/dataview.md index 7f4af81..64b865b 100644 --- a/doc/dataview.md +++ b/doc/dataview.md @@ -11,7 +11,7 @@ class. Allocates a new `Napi::DataView` instance with a given `Napi::ArrayBuffer`. ```cpp -static Napi::DataView New(napi_env env, Napi::ArrayBuffer arrayBuffer); +static Napi::DataView Napi::DataView::New(napi_env env, Napi::ArrayBuffer arrayBuffer); ``` - `[in] env`: The environment in which to create the `Napi::DataView` instance. @@ -24,7 +24,7 @@ Returns a new `Napi::DataView` instance. Allocates a new `Napi::DataView` instance with a given `Napi::ArrayBuffer`. ```cpp -static Napi::DataView New(napi_env env, Napi::ArrayBuffer arrayBuffer, size_t byteOffset); +static Napi::DataView Napi::DataView::New(napi_env env, Napi::ArrayBuffer arrayBuffer, size_t byteOffset); ``` - `[in] env`: The environment in which to create the `Napi::DataView` instance. @@ -38,7 +38,7 @@ Returns a new `Napi::DataView` instance. Allocates a new `Napi::DataView` instance with a given `Napi::ArrayBuffer`. ```cpp -static Napi::DataView New(napi_env env, Napi::ArrayBuffer arrayBuffer, size_t byteOffset, size_t byteLength); +static Napi::DataView Napi::DataView::New(napi_env env, Napi::ArrayBuffer arrayBuffer, size_t byteOffset, size_t byteLength); ``` - `[in] env`: The environment in which to create the `Napi::DataView` instance. @@ -53,7 +53,7 @@ Returns a new `Napi::DataView` instance. Initializes an empty instance of the `Napi::DataView` class. ```cpp -DataView(); +Napi::DataView(); ``` ### Constructor @@ -61,7 +61,7 @@ DataView(); Initializes a wrapper instance of an existing `Napi::DataView` instance. ```cpp -DataView(napi_env env, napi_value value); +Napi::DataView(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to create the `Napi::DataView` instance. @@ -70,7 +70,7 @@ DataView(napi_env env, napi_value value); ### ArrayBuffer ```cpp -Napi::ArrayBuffer ArrayBuffer() const; +Napi::ArrayBuffer Napi::DataView::ArrayBuffer() const; ``` Returns the backing array buffer. @@ -78,7 +78,7 @@ Returns the backing array buffer. ### ByteOffset ```cpp -size_t ByteOffset() const; +size_t Napi::DataView::ByteOffset() const; ``` Returns the offset into the `Napi::DataView` where the array starts, in bytes. @@ -86,7 +86,7 @@ Returns the offset into the `Napi::DataView` where the array starts, in bytes. ### ByteLength ```cpp -size_t ByteLength() const; +size_t Napi::DataView::ByteLength() const; ``` Returns the length of the array, in bytes. @@ -94,17 +94,17 @@ Returns the length of the array, in bytes. ### GetFloat32 ```cpp -float GetFloat32(size_t byteOffset) const; +float Napi::DataView::GetFloat32(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. -Returns a signed 32-bit float (float) at the specified byte offset from the start of the `DataView`. +Returns a signed 32-bit float (float) at the specified byte offset from the start of the `Napi::DataView`. ### GetFloat64 ```cpp -double GetFloat64(size_t byteOffset) const; +double Napi::DataView::GetFloat64(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -114,7 +114,7 @@ Returns a signed 64-bit float (double) at the specified byte offset from the sta ### GetInt8 ```cpp -int8_t GetInt8(size_t byteOffset) const; +int8_t Napi::DataView::GetInt8(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -124,7 +124,7 @@ Returns a signed 8-bit integer (byte) at the specified byte offset from the star ### GetInt16 ```cpp -int16_t GetInt16(size_t byteOffset) const; +int16_t Napi::DataView::GetInt16(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -134,7 +134,7 @@ Returns a signed 16-bit integer (short) at the specified byte offset from the st ### GetInt32 ```cpp -int32_t GetInt32(size_t byteOffset) const; +int32_t Napi::DataView::GetInt32(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -144,7 +144,7 @@ Returns a signed 32-bit integer (long) at the specified byte offset from the sta ### GetUint8 ```cpp -uint8_t GetUint8(size_t byteOffset) const; +uint8_t Napi::DataView::GetUint8(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -154,7 +154,7 @@ Returns a unsigned 8-bit integer (unsigned byte) at the specified byte offset fr ### GetUint16 ```cpp -uint16_t GetUint16(size_t byteOffset) const; +uint16_t Napi::DataView::GetUint16(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -164,7 +164,7 @@ Returns a unsigned 16-bit integer (unsigned short) at the specified byte offset ### GetUint32 ```cpp -uint32_t GetUint32(size_t byteOffset) const; +uint32_t Napi::DataView::GetUint32(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -174,7 +174,7 @@ Returns a unsigned 32-bit integer (unsigned long) at the specified byte offset f ### SetFloat32 ```cpp -void SetFloat32(size_t byteOffset, float value) const; +void Napi::DataView::SetFloat32(size_t byteOffset, float value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -183,7 +183,7 @@ void SetFloat32(size_t byteOffset, float value) const; ### SetFloat64 ```cpp -void SetFloat64(size_t byteOffset, double value) const; +void Napi::DataView::SetFloat64(size_t byteOffset, double value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -192,7 +192,7 @@ void SetFloat64(size_t byteOffset, double value) const; ### SetInt8 ```cpp -void SetInt8(size_t byteOffset, int8_t value) const; +void Napi::DataView::SetInt8(size_t byteOffset, int8_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -201,7 +201,7 @@ void SetInt8(size_t byteOffset, int8_t value) const; ### SetInt16 ```cpp -void SetInt16(size_t byteOffset, int16_t value) const; +void Napi::DataView::SetInt16(size_t byteOffset, int16_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -210,7 +210,7 @@ void SetInt16(size_t byteOffset, int16_t value) const; ### SetInt32 ```cpp -void SetInt32(size_t byteOffset, int32_t value) const; +void Napi::DataView::SetInt32(size_t byteOffset, int32_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -219,7 +219,7 @@ void SetInt32(size_t byteOffset, int32_t value) const; ### SetUint8 ```cpp -void SetUint8(size_t byteOffset, uint8_t value) const; +void Napi::DataView::SetUint8(size_t byteOffset, uint8_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -228,7 +228,7 @@ void SetUint8(size_t byteOffset, uint8_t value) const; ### SetUint16 ```cpp -void SetUint16(size_t byteOffset, uint16_t value) const; +void Napi::DataView::SetUint16(size_t byteOffset, uint16_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. @@ -237,7 +237,7 @@ void SetUint16(size_t byteOffset, uint16_t value) const; ### SetUint32 ```cpp -void SetUint32(size_t byteOffset, uint32_t value) const; +void Napi::DataView::SetUint32(size_t byteOffset, uint32_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. diff --git a/doc/prebuild_tools.md b/doc/prebuild_tools.md new file mode 100644 index 0000000..4025a58 --- /dev/null +++ b/doc/prebuild_tools.md @@ -0,0 +1,16 @@ +# Prebuild tools + +The distribution of a native add-on is just as important as its implementation. +In order to install a native add-on it's important to have all the necessary +dependencies installed and well configured (see the [setup](doc/setum.md) section). +The end-user will need to compile the add-on when they will do an `npm install` +and in some cases this could create problems. To avoid the compilation process it's +possible to ditribute the native add-on in pre-built form for different platform +and architectures. The prebuild tools help to create and distrubute the pre-built +form of a native add-on. + +The following list report two of the tools that are compatible with **N-API**: + +- **[node-pre-gyp](https://www.npmjs.com/package/node-pre-gyp)** +- **[prebuild](https://www.npmjs.com/package/prebuild)** +- **[prebuildify](https://www.npmjs.com/package/prebuildify)** diff --git a/doc/working_with_javascript_values.md b/doc/working_with_javascript_values.md index fc208f1..00dad25 100644 --- a/doc/working_with_javascript_values.md +++ b/doc/working_with_javascript_values.md @@ -3,11 +3,12 @@ `node-addon-api` provides a set of classes that allow to create and manage JavaScript object: -- [Function](doc/function.md) - - [FunctionReference](doc/function_reference.md) -- [ObjectWrap](doc/object_wrap.md) - - [ClassPropertyDescriptor](doc/class_property_descriptor.md) -- [Buffer](doc/buffer.md) -- [ArrayBuffer](doc/array_buffer.md) -- [TypedArray](doc/typed_array.md) - - [TypedArrayOf](doc/typed_array_of.md) +- [Function](function.md) + - [FunctionReference](function_reference.md) +- [ObjectWrap](object_wrap.md) + - [ClassPropertyDescriptor](class_property_descriptor.md) +- [Buffer](buffer.md) +- [ArrayBuffer](array_buffer.md) +- [TypedArray](typed_array.md) + - [TypedArrayOf](typed_array_of.md) +- [DataView](dataview.md)