Address review comments

Author: KevinEady

doc/basic_env.md

@@ -1,7 +1,6 @@
 # BasicEnv
 
-The opaque data structure containing the environment in which the request is
-being run.
+The data structure containing the environment in which the request is being run.
 
 The `Napi::BasicEnv` object is usually created and passed by the Node.js runtime
 or node-addon-api infrastructure.
@@ -50,13 +49,13 @@ void SetInstanceData(T* data) const;
 - `[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.
+operator to destroy `T*` when the add-on 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.
+the add-on 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.
+add-on. The item will be passed to the function `fini` which gets called when an
+instance of the add-on is unloaded.
 
 ### SetInstanceData
 
@@ -73,16 +72,16 @@ void SetInstanceData(DataType* data, HintType* hint) const;
 - `[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.
+uses the `delete` operator to destroy `T*` when the add-on 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.
+the add-on 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.
+the add-on for the duration of its lifecycle and will be passed as a hint to
+`fini` when the add-on 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
+add-on. The item will be passed to the function `fini` which gets called when an
+instance of the add-on is unloaded. This overload accepts an additional hint to
 be passed to `fini`.
 
 ### GetModuleFileName
@@ -91,10 +90,10 @@ be passed to `fini`.
 const char* Napi::Env::GetModuleFileName() const;
 ```
 
-Returns a A URL containing the absolute path of the location from which the
-add-on was loaded. For a file on the local file system it will start with
-`file://`. The string is null-terminated and owned by env and must thus not be
-modified or freed. It is only valid while the add-on is loaded.
+Returns a URL containing the absolute path of the location from which the add-on
+was loaded. For a file on the local file system it will start with `file://`.
+The string is null-terminated and owned by env and must thus not be modified or
+freed. It is only valid while the add-on is loaded.
 
 ### AddCleanupHook
 

doc/env.md

@@ -1,7 +1,8 @@
 # Env
 
-The opaque data structure containing the environment in which the request is
-being run.
+Class `Napi::Env` inherits from class [`Napi::BasicEnv`][].
+
+The data structure containing the environment in which the request is being run.
 
 The `Napi::Env` object is usually created and passed by the Node.js runtime or
 node-addon-api infrastructure.
@@ -82,4 +83,5 @@ The `script` can be any of the following types:
 - `const char *`
 - `const std::string &`
 
+[`Napi::BasicEnv`]: ./basic_env.md
 [Finalization]: ./finalization.md

doc/finalization.md

@@ -4,7 +4,8 @@ Various node-addon-api methods accept a templated `Finalizer finalizeCallback`
 parameter. This parameter represents a native callback function that runs in
 response to a garbage collection event. A finalizer is considered a _basic_
 finalizer if the callback only utilizes a certain subset of APIs, which may
-provide optimizations, improved execution, or other benefits.
+provide more efficient memory management, optimizations, improved execution, or
+other benefits.
 
 In general, it is best to use basic finalizers whenever possible (eg. when
 access to JavaScript is _not_ needed).
@@ -28,7 +29,7 @@ Use of basic finalizers may allow the engine to perform optimizations when
 scheduling or executing the callback. For example, V8 does not allow access to
 the engine heap during garbage collection. Restricting finalizers from accessing
 the engine heap allows the callback to execute during garbage collection,
-providing a chance to free native memory on the current tick.
+providing a chance to free native memory eagerly.
 
 In general, APIs that access engine heap are not allowed in basic finalizers.
 
@@ -46,12 +47,13 @@ Napi::ArrayBuffer::New(
 ## Scheduling Finalizers
 
 In addition to passing finalizers to `Napi::External`s and other Node-API
-constructs, use `Napi::BasicEnv::PostFinalize(Napi::BasicEnv, Finalizer)` to
-schedule a callback to run outside of the garbage collector finalization. Since
-the associated native memory may already be freed by the basic finalizer, any
-additional data may be passed eg. via the finalizer's parameters (`T data*`,
-`Hint hint*`) or via lambda capture. This allows for freeing native data in a
-basic finalizer, while executing any JavaScript code in an additional finalizer.
+constructs, `Napi::BasicEnv::PostFinalize(Napi::BasicEnv, Finalizer)` can be
+used to schedule a callback to run outside of the garbage collector
+finalization. Since the associated native memory may already be freed by the
+basic finalizer, any additional data may be passed eg. via the finalizer's
+parameters (`T data*`, `Hint hint*`) or via lambda capture. This allows for
+freeing native data in a basic finalizer, while executing any JavaScript code in
+an additional finalizer.
 
 ### Example
 

napi.h

@@ -187,7 +187,6 @@ namespace NAPI_CPP_CUSTOM_NAMESPACE {
 #endif
 
 // Forward declarations
-class BasicEnv;
 class Env;
 class Value;
 class Boolean;