Skip to content

Commit

Permalink
doc: doc cleanup
Browse files Browse the repository at this point in the history
- Some fix on bigint and dataview.
- Add section dedicated to prebuild tools.

PR-URL: nodejs/node-addon-api#353
Reviewed-By: Michael Dawson <[email protected]>
  • Loading branch information
Marlyfleitas committed Sep 28, 2018
1 parent cf32c3b commit 5fdf783
Show file tree
Hide file tree
Showing 5 changed files with 62 additions and 45 deletions.
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<a name="api"></a>

Expand All @@ -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)
Expand Down
22 changes: 10 additions & 12 deletions doc/bigint.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -43,24 +42,23 @@ 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.
### 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
Expand All @@ -72,15 +70,15 @@ 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.

### 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
Expand Down
50 changes: 25 additions & 25 deletions doc/dataview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -53,15 +53,15 @@ Returns a new `Napi::DataView` instance.
Initializes an empty instance of the `Napi::DataView` class.
```cpp
DataView();
Napi::DataView();
```

### Constructor

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.
Expand All @@ -70,41 +70,41 @@ DataView(napi_env env, napi_value value);
### ArrayBuffer
```cpp
Napi::ArrayBuffer ArrayBuffer() const;
Napi::ArrayBuffer Napi::DataView::ArrayBuffer() const;
```

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.

### ByteLength

```cpp
size_t ByteLength() const;
size_t Napi::DataView::ByteLength() const;
```

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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand Down
16 changes: 16 additions & 0 deletions doc/prebuild_tools.md
Original file line number Diff line number Diff line change
@@ -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)**
17 changes: 9 additions & 8 deletions doc/working_with_javascript_values.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

0 comments on commit 5fdf783

Please sign in to comment.