doc: Improve comment on asynchronous calls

Following the remarks of fellow developers, the status
of the object received by the callback function
needs to be explained better.

Change-Id: I0e6bcd51849bbc5af92af08675949a901bfd683e
Signed-off-by: Jose Bollo <jose.bollo@iot.bzh>

2 files changed, 6 insertions, 0 deletions

diff --git a/docs/reference-v3/func-api.md b/docs/reference-v3/func-api.md
index aa28932a..454bc0f6 100644
--- a/docs/reference-v3/func-api.md
+++ b/docs/reference-v3/func-api.md
@@ -293,6 +293,9 @@ struct json_object *afb_api_settings(
  *  4. 'info'    a string handling some info (can be NULL)
  *  5. 'api'     the api
  *
+ * NOTE: For convenience, *json_object_put* is called on 'object' after the
+ * callback returns. So, it is wrong to call *json_object_put* in the callback.
+ *
  * @param api      The api that makes the call
  * @param apiname  The api name of the method to call
  * @param verb     The verb name of the method to call
diff --git a/docs/reference-v3/func-req.md b/docs/reference-v3/func-req.md
index 25644056..a91508dc 100644
--- a/docs/reference-v3/func-req.md
+++ b/docs/reference-v3/func-req.md
@@ -436,6 +436,9 @@ void afb_req_reply_f(
  *  4. 'info'    a string handling some info (can be NULL)
  *  5. 'req'     the req
  *
+ * NOTE: For convenience, *json_object_put* is called on 'object' after the
+ * callback returns. So, it is wrong to call *json_object_put* in the callback.
+ *
  * @param req      The request
  * @param api      The api name of the method to call
  * @param verb     The verb name of the method to call