test: add basic tests and doc for scopes#250
Conversation
| As the methods and classes within the node-addon-api are used, | ||
| handles to objects in the heap for the underlying | ||
| VM may be created. A handle may be created for any new node-addon-api | ||
| Value(and subclasses) created or returned. These handles must hold the |
There was a problem hiding this comment.
A handle may be created when any new node-addon-api Value and its subclasses have been created or returned.
| keep an object alive in the heap in order to ensure that the objects | ||
| are not collected while native code is using them. A handle may be | ||
| created any time a node-addon-api Value(and subclasses) are created | ||
| or returned. |
There was a problem hiding this comment.
A handle may be created when any new node-addon-api Value and its subclasses have been created or returned.
| or returned. | ||
|
|
||
| For more details refer to the section title "Object lifetime management". | ||
|
|
There was a problem hiding this comment.
It could be better add the link to "Object lifetime management"
| Value(and subclasses) created or returned. These handles must hold the | ||
| objects 'live' until they are no longer required by the native code, | ||
| otherwise the objects could be collected before the native code was | ||
| finished using them. |
There was a problem hiding this comment.
otherwise the objects could be collected by the garbage collector before the native code was finished using them.
| The EscapableHandleScope class is used to manage the lifetime of object handles | ||
| which are created through the use of node-addon-api. These handles | ||
| keep an object alive in the heap in order to ensure that the objects | ||
| are not collected while native code is using them. A handle may be |
There was a problem hiding this comment.
are not collected by garbage collector
| which allows a single handle to be "promoted" to an outer scope. | ||
|
|
||
| For more details refer to the section title "Object lifetime management". | ||
|
|
There was a problem hiding this comment.
It could be better add the link to "Object lifetime management"
| - `[in] scope`: pre-existing napi_handle_scope. | ||
|
|
||
| Creates a new EscapableHandleScope instance which wraps the | ||
| napi_escapable_handle_scope handle passed in. This can be used |
There was a problem hiding this comment.
Remove extra space here: in. This can be used
| ``` | ||
|
|
||
| Deletes the EscapableHandleScope instance and allows any objects/handles created | ||
| in the scope to be collected by the garbage collector. There is no |
There was a problem hiding this comment.
Remove extra space here: collector. There is no
| - `[in] escapee`: Napi::Value or napi_env to promote to the outer scope | ||
|
|
||
| Returns Napi:Value which can be used in the outer scope. This method can | ||
| be called at most once on a given EscapableHandleScope. If it is called |
There was a problem hiding this comment.
Remove extra space here: EscapableHandleScope. If
|
|
||
| Returns Napi:Value which can be used in the outer scope. This method can | ||
| be called at most once on a given EscapableHandleScope. If it is called | ||
| more than once and exception will be thrown. |
There was a problem hiding this comment.
If it is called more than once an exception will be thrown.
|
@NickNaso, thanks for the comments. Pushed commit which should address them. |
| Creates a new escapable handle scope. | ||
|
|
||
| ```cpp | ||
| EscapableHandleScope::New(napi_env env, napi_handle_scope scope); |
There was a problem hiding this comment.
For consistency does it make sense to include return types?
|
|
||
| - `[in] Env`: The environment in which to construct the EscapableHandleScope object. | ||
|
|
||
| Creates a new EscapableHandleScope |
There was a problem hiding this comment.
Maybe it makes more sense to use "Returns" for consistency. In working on my documentation it seems like the pattern should be:
- Description/Remarks
- Signature
- Parameters
- Returns
There was a problem hiding this comment.
Agreed is should say "Returns" will update
|
addressed second set of comments will land. |
PR-URL: #250 Reviewed-By: Kyle Farnung <kfarnung@microsoft.com> Reviewed-By: Nicola Del Gobbo <nicoladelgobbo@NickNaso.local>
|
Landed as 75086da |
PR-URL: nodejs/node-addon-api#250 Reviewed-By: Kyle Farnung <kfarnung@microsoft.com> Reviewed-By: Nicola Del Gobbo <nicoladelgobbo@NickNaso.local>
PR-URL: nodejs/node-addon-api#250 Reviewed-By: Kyle Farnung <kfarnung@microsoft.com> Reviewed-By: Nicola Del Gobbo <nicoladelgobbo@NickNaso.local>
PR-URL: nodejs/node-addon-api#250 Reviewed-By: Kyle Farnung <kfarnung@microsoft.com> Reviewed-By: Nicola Del Gobbo <nicoladelgobbo@NickNaso.local>
PR-URL: nodejs/node-addon-api#250 Reviewed-By: Kyle Farnung <kfarnung@microsoft.com> Reviewed-By: Nicola Del Gobbo <nicoladelgobbo@NickNaso.local>
No description provided.