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>

diff --git a/docs/reference-v3/func-api.md b/docs/reference-v3/func-api.md
index aa28932..454bc0f 100644 (file)
--- 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 2564405..a91508d 100644 (file)
--- 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

diff --git a/include/afb/afb-api-x3.h b/include/afb/afb-api-x3.h
index fc72d07..ca92bb5 100644 (file)
--- a/include/afb/afb-api-x3.h
+++ b/include/afb/afb-api-x3.h
@@ -814,6 +814,9 @@ int afb_api_x3_event_handler_del(
  *  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
@@ -821,7 +824,6 @@ int afb_api_x3_event_handler_del(
  * @param callback The to call on completion
  * @param closure  The closure to pass to the callback
  *
- *
  * @see afb_req_subcall
  * @see afb_req_subcall_sync
  * @see afb_api_x3_call_sync

diff --git a/include/afb/afb-req-x2.h b/include/afb/afb-req-x2.h
index 9695ef6..5111f2f 100644 (file)
--- a/include/afb/afb-req-x2.h
+++ b/include/afb/afb-req-x2.h
@@ -739,6 +739,9 @@ struct json_object *afb_req_x2_get_client_info(
  *  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