From 5a4cc72fdd2adecd9dcfadd9b4ed982da144aba3 Mon Sep 17 00:00:00 2001
From: Marly Fleitas <marly.fleitas826@gmail.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
PR-URL: https://github.com/nodejs/node-addon-api/pull/708
Reviewed-By: Nicola Del Gobbo <nicoladelgobbo@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
---
 doc/env.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/doc/env.md b/doc/env.md
index 70c6418..66575ea 100644
--- a/doc/env.md
+++ b/doc/env.md
@@ -75,3 +75,58 @@ The `script` can be any of the following types:
 - [`Napi::String`](string.md)
 - `const char *`
 - `const std::string &`
+
+### GetInstanceData
+```cpp
+template <typename T> T* GetInstanceData();
+```
+
+Returns the instance data that was previously associated with the environment,
+or `nullptr` if none was associated.
+
+### 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`.