Improve documentation on native pointer API methods
Added extra notes on the native pointer API usages to clarify
when the free callback function is invoked. Also added a note
for the free callback typedef to inform users to not call API methods
in the callback.
JerryScript-DCO-1.0-Signed-off-by: Peter Gal
@@ -441,6 +441,9 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_
Native free callback of an object. It is used in `jerry_object_native_info_t` and for external Array buffers.
+*Note*:
+ - This callback method **must not** call any JerryScript API methods.
+
**Prototype**
```c
@@ -5542,7 +5545,8 @@ jerry_set_prototype (const jerry_value_t obj_val,
**Summary**
Get native pointer by the given type information.
-The pointer and the type information are previously associated with the object by jerry_set_object_native_pointer.
+The pointer and the type information are previously associated with the object by
+[jerry_set_object_native_pointer](#jerry_set_object_native_pointer).
*Note*: `out_native_pointer_p` can be NULL, and it means the
caller doesn't want to get the native_pointer.
@@ -5749,15 +5753,15 @@ main (void)
**Summary**
Set native pointer and an optional type information for the specified object.
-You can get them by calling jerry_get_object_native_pointer later.
-
-*Note*: If native pointer was already set for the object, its value is updated.
+You can get them by calling [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) later.
-*Note*: If a non-NULL free callback is specified in the native type information,
+*Notes*:
+ - If a native pointer was already set for the object with the same type information, its value is updated.
+ - If a non-NULL free callback is specified in the native type information,
it will be called by the garbage collector when the object is freed.
- This callback **must not** invoke API functions.
- The type info always overwrites the previous value, so passing
- a NULL value deletes the current type info.
+ - If the object is only referenced via the "global" object (or one of it's "child"),
+ the free callback will be invoked during the execution of `jerry_cleanup`.
+ - The free callback **must not** invoke API functions.
**Prototype**
@@ -5792,10 +5796,12 @@ best-practice example.
**Summary**
Delete the native pointer of the specified object associated with the given native type info.
-You can get them by calling jerry_get_object_native_pointer later.
-*Note*:
+*Notes*:
- If the specified object has no matching native pointer for the given native type info the operation has no effect.
+ - The method does not invoke the free callback specified in the type info.
+ If the native pointer should be freed then one must get the native pointer first and invoke the free callback manually
+ before calling this method.
- This operation cannot throw an exception.
**Prototype**
