From 3a952d9ba503121c913e5fabec7f91e9f7d3658c Mon Sep 17 00:00:00 2001
From: Peter Gal <pgal.u-szeged@partner.samsung.com>
Date: Wed, 2 Oct 2019 16:39:17 +0200
Subject: [PATCH] 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 pgal.u-szeged@partner.samsung.com
---
 docs/02.API-REFERENCE.md | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 8020a2cbce..927da6600e 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -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,
-        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.
+*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.
+ - 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**