doc: add TypedArray and TypedArrayOf

* Added documentation for `TypedArray` and `TypedArrayOf` * Tweaked the documentation for `ArrayBuffer` PR-URL: nodejs/node-addon-api#305 Reviewed-By: Michael Dawson <[email protected]>
kevindavies8 · Jul 18, 2018 · aa42cba · aa42cba
1 parent bd102b5
commit aa42cba
Show file tree

Hide file tree

Showing 3 changed files with 229 additions and 30 deletions.
diff --git a/doc/array_buffer.md b/doc/array_buffer.md
@@ -1,48 +1,50 @@
 # ArrayBuffer
 
-The `ArrayBuffer` class corresponds to the JavaScript `ArrayBuffer` class.
+The `ArrayBuffer` class corresponds to the
+[JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
+class.
 
 ## Methods
 
 ### New
 
-Allocates a new `ArrayBuffer` object with a given length.
+Allocates a new `ArrayBuffer` instance with a given length.
 
 ```cpp
 static ArrayBuffer New(napi_env env, size_t byteLength);
 ```
 
-- `[in] env`: The environment in which to create the ArrayBuffer object.
+- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
 - `[in] byteLength`: The length to be allocated, in bytes.
 
-Returns a new `ArrayBuffer` object.
+Returns a new `ArrayBuffer` instance.
 
 ### New
 
-Wraps the provided external data into a new `ArrayBuffer` object.
+Wraps the provided external data into a new `ArrayBuffer` instance.
 
-The `ArrayBuffer` object does not assume ownership for the data and expects it
-to be valid for the lifetime of the object. Since the `ArrayBuffer` is subject
+The `ArrayBuffer` instance does not assume ownership for the data and expects it
+to be valid for the lifetime of the instance. Since the `ArrayBuffer` is subject
 to garbage collection this overload is only suitable for data which is static
 and never needs to be freed.
 
 ```cpp
 static ArrayBuffer New(napi_env env, void* externalData, size_t byteLength);
 ```
 
-- `[in] env`: The environment in which to create the `ArrayBuffer` object.
+- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
 - `[in] externalData`: The pointer to the external data to wrap.
 - `[in] byteLength`: The length of the `externalData`, in bytes.
 
-Returns a new `ArrayBuffer` object.
+Returns a new `ArrayBuffer` instance.
 
 ### New
 
-Wraps the provided external data into a new `ArrayBuffer` object.
+Wraps the provided external data into a new `ArrayBuffer` instance.
 
-The `ArrayBuffer` object does not assume ownership for the data and expects it
-to be valid for the lifetime of the object. The data can only be freed once the
-`finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been
+The `ArrayBuffer` instance does not assume ownership for the data and expects it
+to be valid for the lifetime of the instance. The data can only be freed once
+the `finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been
 released.
 
 ```cpp
@@ -53,22 +55,22 @@ static ArrayBuffer New(napi_env env,
                        Finalizer finalizeCallback);
 ```
 
-- `[in] env`: The environment in which to create the `ArrayBuffer` object.
+- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
 - `[in] externalData`: The pointer to the external data to wrap.
 - `[in] byteLength`: The length of the `externalData`, in bytes.
 - `[in] finalizeCallback`: A function to be called when the `ArrayBuffer` is
   destroyed. It must implement `operator()`, accept a `void*` (which is the
   `externalData` pointer), and return `void`.
 
-Returns a new `ArrayBuffer` object.
+Returns a new `ArrayBuffer` instance.
 
 ### New
 
-Wraps the provided external data into a new `ArrayBuffer` object.
+Wraps the provided external data into a new `ArrayBuffer` instance.
 
-The `ArrayBuffer` object does not assume ownership for the data and expects it
-to be valid for the lifetime of the object. The data can only be freed once the
-`finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been
+The `ArrayBuffer` instance does not assume ownership for the data and expects it
+to be valid for the lifetime of the instance. The data can only be freed once
+the `finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been
 released.
 
 ```cpp
@@ -80,7 +82,7 @@ static ArrayBuffer New(napi_env env,
                        Hint* finalizeHint);
 ```
 
-- `[in] env`: The environment in which to create the `ArrayBuffer` object.
+- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
 - `[in] externalData`: The pointer to the external data to wrap.
 - `[in] byteLength`: The length of the `externalData`, in bytes.
 - `[in] finalizeCallback`: The function to be called when the `ArrayBuffer` is
@@ -89,7 +91,7 @@ static ArrayBuffer New(napi_env env,
 - `[in] finalizeHint`: The hint to be passed as the second parameter of the
   finalize callback.
 
-Returns a new `ArrayBuffer` object.
+Returns a new `ArrayBuffer` instance.
 
 ### Constructor
 
@@ -107,7 +109,7 @@ Initializes a wrapper instance of an existing `ArrayBuffer` object.
 ArrayBuffer(napi_env env, napi_value value);
 ```
 
-- `[in] env`: The environment in which to create the `ArrayBuffer` object.
+- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
 - `[in] value`: The `ArrayBuffer` reference to wrap.
 
 ### ByteLength

diff --git a/doc/typed_array.md b/doc/typed_array.md
@@ -1,5 +1,74 @@
-# Typed array
+# TypedArray
 
-You are reading a draft of the next documentation and it's in continuous update so
-if you don't find what you need please refer to:
-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+The `TypedArray` class corresponds to the
+[JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
+class.
+
+## Methods
+
+### Constructor
+
+Initializes an empty instance of the `TypedArray` class.
+
+```cpp
+TypedArray();
+```
+
+### Constructor
+
+Initializes a wrapper instance of an existing `TypedArray` instance.
+
+```cpp
+TypedArray(napi_env env, napi_value value);
+```
+
+- `[in] env`: The environment in which to create the `TypedArray` instance.
+- `[in] value`: The `TypedArray` reference to wrap.
+
+### TypedArrayType
+
+```cpp
+napi_typedarray_type TypedArrayType() const;
+```
+
+Returns the type of this instance.
+
+### ArrayBuffer
+
+```cpp
+Napi::ArrayBuffer ArrayBuffer() const;
+```
+
+Returns the backing array buffer.
+
+### ElementSize
+
+```cpp
+uint8_t ElementSize() const;
+```
+
+Returns the size of one element, in bytes.
+
+### ElementLength
+
+```cpp
+size_t ElementLength() const;
+```
+
+Returns the number of elements.
+
+### ByteOffset
+
+```cpp
+size_t ByteOffset() const;
+```
+
+Returns the offset into the `ArrayBuffer` where the array starts, in bytes.
+
+### ByteLength
+
+```cpp
+size_t ByteLength() const;
+```
+
+Returns the length of the array, in bytes.
diff --git a/doc/typed_array_of.md b/doc/typed_array_of.md
@@ -1,5 +1,133 @@
-# Typed array of
+# TypedArrayOf
 
-You are reading a draft of the next documentation and it's in continuous update so
-if you don't find what you need please refer to:
-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+The `TypedArrayOf` class corresponds to the various
+[JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
+classes.
+
+## Typedefs
+
+The common JavaScript `TypedArray` types are pre-defined for each of use:
+
+```cpp
+typedef TypedArrayOf<int8_t> Int8Array;
+typedef TypedArrayOf<uint8_t> Uint8Array;
+typedef TypedArrayOf<int16_t> Int16Array;
+typedef TypedArrayOf<uint16_t> Uint16Array;
+typedef TypedArrayOf<int32_t> Int32Array;
+typedef TypedArrayOf<uint32_t> Uint32Array;
+typedef TypedArrayOf<float> Float32Array;
+typedef TypedArrayOf<double> Float64Array;
+```
+
+The one exception is the `Uint8ClampedArray` which requires explicit
+initialization:
+
+```cpp
+Uint8Array::New(env, length, napi_uint8_clamped_array)
+```
+
+Note that while it's possible to create a "clamped" array the _clamping_
+behavior is only applied in JavaScript.
+
+## Methods
+
+### New
+
+Allocates a new `TypedArray` instance with a given length. The underlying
+`ArrayBuffer` is allocated automatically to the desired number of elements.
+
+The array type parameter can normally be omitted (because it is inferred from
+the template parameter T), except when creating a "clamped" array.
+
+```cpp
+static TypedArrayOf New(napi_env env,
+                        size_t elementLength,
+                        napi_typedarray_type type);
+```
+
+- `[in] env`: The environment in which to create the `TypedArrayOf` instance.
+- `[in] elementLength`: The length to be allocated, in elements.
+- `[in] type`: The type of array to allocate (optional).
+
+Returns a new `TypedArrayOf` instance.
+
+### New
+
+Wraps the provided `ArrayBuffer` into a new `TypedArray` instance.
+
+The array `type` parameter can normally be omitted (because it is inferred from
+the template parameter `T`), except when creating a "clamped" array.
+
+```cpp
+static TypedArrayOf New(napi_env env,
+                        size_t elementLength,
+                        Napi::ArrayBuffer arrayBuffer,
+                        size_t bufferOffset,
+                        napi_typedarray_type type);
+```
+
+- `[in] env`: The environment in which to create the `TypedArrayOf` instance.
+- `[in] elementLength`: The length to array, in elements.
+- `[in] arrayBuffer`: The backing `ArrayBuffer` instance.
+- `[in] bufferOffset`: The offset into the `ArrayBuffer` where the array starts,
+                       in bytes.
+- `[in] type`: The type of array to allocate (optional).
+
+Returns a new `TypedArrayOf` instance.
+
+### Constructor
+
+Initializes an empty instance of the `TypedArrayOf` class.
+
+```cpp
+TypedArrayOf();
+```
+
+### Constructor
+
+Initializes a wrapper instance of an existing `TypedArrayOf` object.
+
+```cpp
+TypedArrayOf(napi_env env, napi_value value);
+```
+
+- `[in] env`: The environment in which to create the `TypedArrayOf` object.
+- `[in] value`: The `TypedArrayOf` reference to wrap.
+
+### operator []
+
+```cpp
+T& operator [](size_t index);
+```
+
+- `[in] index: The element index into the array.
+
+Returns the element found at the given index.
+
+### operator []
+
+```cpp
+const T& operator [](size_t index) const;
+```
+
+- `[in] index: The element index into the array.
+
+Returns the element found at the given index.
+
+### Data
+
+```cpp
+T* Data() const;
+```
+
+Returns a pointer into the backing `ArrayBuffer` which is offset to point to the
+start of the array.
+
+### Data
+
+```cpp
+const T* Data() const
+```
+
+Returns a pointer into the backing `ArrayBuffer` which is offset to point to the
+start of the array.