doc: ArrayBuffer and Buffer documentation

PR-URL: nodejs/node-addon-api#256
Reviewed-By: Michael Dawson <[email protected]>

doc/array_buffer.md

@@ -1,5 +1,127 @@
-# Array buffer
+# ArrayBuffer
 
-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 `ArrayBuffer` class corresponds to the JavaScript `ArrayBuffer` class.
+
+## Methods
+
+### New
+
+Allocates a new `ArrayBuffer` object 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] byteLength`: The length to be allocated, in bytes.
+
+Returns a new `ArrayBuffer` object.
+
+### New
+
+Wraps the provided external data into a new `ArrayBuffer` object.
+
+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
+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] externalData`: The pointer to the external data to wrap.
+- `[in] byteLength`: The length of the `externalData`, in bytes.
+
+Returns a new `ArrayBuffer` object.
+
+### New
+
+Wraps the provided external data into a new `ArrayBuffer` object.
+
+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
+released.
+
+```cpp
+template <typename Finalizer>
+static ArrayBuffer New(napi_env env,
+                       void* externalData,
+                       size_t byteLength,
+                       Finalizer finalizeCallback);
+```
+
+- `[in] env`: The environment in which to create the `ArrayBuffer` object.
+- `[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.
+
+### New
+
+Wraps the provided external data into a new `ArrayBuffer` object.
+
+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
+released.
+
+```cpp
+template <typename Finalizer, typename Hint>
+static ArrayBuffer New(napi_env env,
+                       void* externalData,
+                       size_t byteLength,
+                       Finalizer finalizeCallback,
+                       Hint* finalizeHint);
+```
+
+- `[in] env`: The environment in which to create the `ArrayBuffer` object.
+- `[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
+  destroyed. It must implement `operator()`, accept a `void*` (which is the
+  `externalData` pointer) and `Hint*`, and return `void`.
+- `[in] finalizeHint`: The hint to be passed as the second parameter of the
+  finalize callback.
+
+Returns a new `ArrayBuffer` object.
+
+### Constructor
+
+Initializes an empty instance of the `ArrayBuffer` class.
+
+```cpp
+ArrayBuffer();
+```
+
+### Constructor
+
+Initializes a wrapper instance of an existing `ArrayBuffer` object.
+
+```cpp
+ArrayBuffer(napi_env env, napi_value value);
+```
+
+- `[in] env`: The environment in which to create the `ArrayBuffer` object.
+- `[in] value`: The `ArrayBuffer` reference to wrap.
+
+### ByteLength
+
+```cpp
+size_t ByteLength() const;
+```
+
+Returns the length of the wrapped data, in bytes.
+
+### Data
+
+```cpp
+T* Data() const;
+```
+
+Returns a pointer the wrapped data.

doc/buffer.md

@@ -1,5 +1,140 @@
 # Buffer
 
-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 `Buffer` class creates a projection of raw data that can be consumed by
+script.
+
+## Methods
+
+### New
+
+Allocates a new `Buffer` object with a given length.
+
+```cpp
+static Buffer<T> New(napi_env env, size_t length);
+```
+
+- `[in] env`: The environment in which to create the `Buffer` object.
+- `[in] length`: The number of `T` elements to allocate.
+
+Returns a new `Buffer` object.
+
+### New
+
+Wraps the provided external data into a new `Buffer` object.
+
+The `Buffer` object does not assume ownership for the data and expects it to be
+valid for the lifetime of the object. Since the `Buffer` is subject to garbage
+collection this overload is only suitable for data which is static and never
+needs to be freed.
+
+```cpp
+static Buffer<T> New(napi_env env, T* data, size_t length);
+```
+
+- `[in] env`: The environment in which to create the `Buffer` object.
+- `[in] data`: The pointer to the external data to expose.
+- `[in] length`: The number of `T` elements in the external data.
+
+Returns a new `Buffer` object.
+
+### New
+
+Wraps the provided external data into a new `Buffer` object.
+
+The `Buffer` 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 `Buffer` has been released.
+
+```cpp
+template <typename Finalizer>
+static Buffer<T> New(napi_env env,
+                     T* data,
+                     size_t length,
+                     Finalizer finalizeCallback);
+```
+
+- `[in] env`: The environment in which to create the `Buffer` object.
+- `[in] data`: The pointer to the external data to expose.
+- `[in] length`: The number of `T` elements in the external data.
+- `[in] finalizeCallback`: The function to be called when the `Buffer` is
+  destroyed. It must implement `operator()`, accept a `T*` (which is the
+  external data pointer), and return `void`.
+
+Returns a new `Buffer` object.
+
+### New
+
+Wraps the provided external data into a new `Buffer` object.
+
+The `Buffer` 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 `Buffer` has been released.
+
+```cpp
+template <typename Finalizer, typename Hint>
+static Buffer<T> New(napi_env env,
+                     T* data,
+                     size_t length,
+                     Finalizer finalizeCallback,
+                     Hint* finalizeHint);
+```
+
+- `[in] env`: The environment in which to create the `Buffer` object.
+- `[in] data`: The pointer to the external data to expose.
+- `[in] length`: The number of `T` elements in the external data.
+- `[in] finalizeCallback`: The function to be called when the `Buffer` is
+  destroyed. It must implement `operator()`, accept a `T*` (which is the
+  external data pointer) and `Hint*`, and return `void`.
+- `[in] finalizeHint`: The hint to be passed as the second parameter of the
+  finalize callback.
+
+Returns a new `Buffer` object.
+
+### Copy
+
+Allocates a new `Buffer` object and copies the provided external data into it.
+
+```cpp
+static Buffer<T> Copy(napi_env env, const T* data, size_t length);
+```
+
+- `[in] env`: The environment in which to create the `Buffer` object.
+- `[in] data`: The pointer to the external data to copy.
+- `[in] length`: The number of `T` elements in the external data.
+
+Returns a new `Buffer` object containing a copy of the data.
+
+### Constructor
+
+Initializes an empty instance of the `Buffer` class.
+
+```cpp
+Buffer();
+```
+
+### Constructor
+
+Initializes the `Buffer` object using an existing Uint8Array.
+
+```cpp
+Buffer(napi_env env, napi_value value);
+```
+
+- `[in] env`: The environment in which to create the `Buffer` object.
+- `[in] value`: The Uint8Array reference to wrap.
+
+### Data
+
+```cpp
+T* Data() const;
+```
+
+Returns a pointer the external data.
+
+### Length
+
+```cpp
+size_t Length() const;
+```
+
+Returns the number of `T` elements in the external data.