From 22ee1d9828e2f3ceccc671a8e11237c6d1cf943e Mon Sep 17 00:00:00 2001
From: Gabriel Schulhof <gabriel.schulhof@intel.com>
Date: Sat, 25 Apr 2020 21:33:07 -0700
Subject: [PATCH] doc: add instance data APIs

Signed-off-by: Gabriel Schulhof <gabriel.schulhof@intel.com>
Re: https://github.com/nodejs/node-addon-api/issues/567#issuecomment-619478767
---
 doc/env.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/doc/env.md b/doc/env.md
index 70c641850..6e2410e99 100644
--- a/doc/env.md
+++ b/doc/env.md
@@ -75,3 +75,50 @@ The `script` can be any of the following types:
 - [`Napi::String`](string.md)
 - `const char *`
 - `const std::string &`
+
+### SetInstanceData
+
+```cpp
+    template <typename T> using Finalizer = void (*)(Env, T*);
+    template <typename T, Finalizer<T> fini = Env::DefaultFini<T>>
+    void SetInstanceData(T* data);
+```
+
+- `[template] fini`: A function to call when the instance data is to be deleted.
+Accepts a function of the form `void CleanupData(Napi::Env env, T* data)`. If
+not given, the default finalizer will be used, which simply uses the `delete`
+operator to destroy `T*` when the addon instance is unloaded.
+- `[in] data`: A pointer to data that will be associated with the instance of
+the addon for the duration of its lifecycle.
+
+Associates a data item stored at `T* data` with the current instance of the
+addon. The item will be passed to the function `fini` which gets called when an
+instance of the addon is unloaded.
+
+### SetInstanceData
+
+```cpp
+    template <typename DataType, typename HintType>
+    using FinalizerWithHint = void (*)(Env, DataType*, HintType*);
+    template <typename DataType,
+              typename HintType,
+              FinalizerWithHint<DataType, HintType> fini =
+                Env::DefaultFiniWithHint<DataType, HintType>>
+    void SetInstanceData(DataType* data, HintType* hint);
+```
+
+- `[template] fini`: A function to call when the instance data is to be deleted.
+Accepts a function of the form
+`void CleanupData(Napi::Env env, DataType* data, HintType* hint)`. If not given,
+the default finalizer will be used, which simply uses the `delete` operator to
+destroy `T*` when the addon instance is unloaded.
+- `[in] data`: A pointer to data that will be associated with the instance of
+the addon for the duration of its lifecycle.
+- `[in] hint`: A pointer to data that will be associated with the instance of
+the addon for the duration of its lifecycle and will be passed as a hint to
+`fini` when the addon instance is unloaded.
+
+Associates a data item stored at `T* data` with the current instance of the
+addon. The item will be passed to the function `fini` which gets called when an
+instance of the addon is unloaded. This overload accepts an additional hint to
+be passed to `fini`.