Improve documentation of api v3

The documentation is improved to reflect the new version.

Tune the options

Change-Id: I894c3db3bc0c10e89db66a9a51a9ad049bb8c0c4
Signed-off-by: José Bollo <jose.bollo@iot.bzh>

1 files changed, 90 insertions, 14 deletions

diff --git a/docs/afb-migration-to-binding-v3.md b/docs/afb-migration-to-binding-v3.md
index 8f1e678c..4cfb3a71 100644
--- a/docs/afb-migration-to-binding-v3.md
+++ b/docs/afb-migration-to-binding-v3.md
@@ -20,7 +20,7 @@ This guide covers the migration of bindings from version 2 to version 3.
 
 The migration from version 1 is not treated here because bindings version 1
 are very old and probably does not exist anymore. If needed you can refer
-to the old [guide to migrate bindings from v1 to v2](afb-migration-v1-to-v2.md).
+to the old [guide to migrate bindings from v1 to v2](legacy/afb-migration-v1-to-v2.md).
 
 
 Differences between version 2 and version 3
@@ -28,7 +28,7 @@ Differences between version 2 and version 3
 
 ### in v3 all is api
 
-The version 3 introduce the concept of "API" that gather what was called before
+The version 3 introduces the concept of "API" that gather what was called before
 the daemon and the service. This is the new concept that predates the 2 others.
 
 The concept of API is intended to allow the definition of multiple APIs
@@ -37,7 +37,7 @@ by a same "binding" (a dynamically loaded library).
 Because there is potentially several "API", the functions that were without
 context in bindings version 2 need now to tell what API is consumer.
 
-To be compatible with version 2, the bindings v3 still have a default hidden
+To be compatible with version 2, bindings v3 still have a default hidden
 context: the default API named **afbBindingV3root**.
 
 To summarize, the functions of class **daemon** and **service** use the default
@@ -76,9 +76,10 @@ Task list for the migration
 This task list is:
 
 1. Use the automatic migration procedure described below
-2. Adapt the init and preinit functions
-3. Consider to change to use the new reply
-4. Consider to change to use the new (sub)call
+2. Adapt the functions **preinit**, **init** and **onevent**
+3. Consider use of the new reply
+4. Consider use of the new (sub)call
+5. Consider use of event handlers
 
 The remaining chapters explain these task with more details.
 
@@ -86,7 +87,7 @@ Automatic migration!
 --------------------
 
 A tiny **sed** script is intended to perform a first pass on the code that
-you want to upgrade. It can be down using **curl** and applied using **sed**
+you want to upgrade. It can be done using **curl** and applied using **sed**
 as below.
 
 ```bash
@@ -96,15 +97,90 @@ curl -o $SED $BASE/docs/$SED
 sed -i -f $SED file1 file2 file3...
 ```
 
-This automatic action does most of the boring job nut not all the job.
+This automatic action does most of the boring job but not all the job.
 The remaining of this guide explains the missing part.
 
-Adapt the init and preinit functions
-------------------------------------
+Adapt the functions preinit, init and onevent
+----------------------------------------------
 
-Consider to change to use the new reply
----------------------------------------
+The signature of the functions **preinit**, **init** and **onevent** changed
+to include the target api.
 
-Consider to change to use the new (sub)call
--------------------------------------------
+The functions of the v2:
+
+```C
+int (*preinit)();
+int (*init)();
+void (*onevent)(const char *event, struct json_object *object);
+```
+
+Gain a new first argument of type **afb_api_t** as below:
+
+```C
+int (*preinit)(afb_api_t api);
+int (*init)(afb_api_t api);
+void (*onevent)(afb_api_t api, const char *event, struct json_object *object);
+```
+
+For the migration, it is enough to just add the new argument without
+using it.
+
+Consider use of the new reply
+-----------------------------
+
+The v3 allows error reply with JSON object. To achieve it, an unified
+reply function's family is introduced:
+
+```C
+void afb_req_reply(afb_req_t req, json_object *obj, const char *error, const char *info);
+void afb_req_reply_v(afb_req_t req, json_object *obj, const char *error, const char *info, va_list args);
+void afb_req_reply_f(afb_req_t req, json_object *obj, const char *error, const char *info, ...);
+```
+
+The functions **success** and **fail** are still supported.
+These functions are now implemented as the following macros:
+
+
+```C
+#define afb_req_success(r,o,i)		afb_req_reply(r,o,NULL,i)
+#define afb_req_success_f(r,o,...)	afb_req_reply_f(r,o,NULL,__VA_ARGS__)
+#define afb_req_success_v(r,o,f,v)	afb_req_reply_v(r,o,NULL,f,v)
+#define afb_req_fail(r,e,i)		afb_req_reply(r,NULL,e,i)
+#define afb_req_fail_f(r,e,...)		afb_req_reply_f(r,NULL,e,__VA_ARGS__)
+#define afb_req_fail_v(r,e,f,v)		afb_req_reply_v(r,NULL,e,f,v)
+```
+
+This is a decision of the developer to switch to the new family
+**afb_req_reply** or to keep the good old functions **afb_req_fail**
+adn **afb_req_success**.
+
+Consider use of the new (sub)call
+---------------------------------
+
+The new call and subcall (the functions **afb_api_call**, **afb_api_call_sync**,
+**afb_req_subcall** and **afb_req_subcall_sync**) functions are redesigned
+to better fit the new reply behaviour. In most case the developer will benefit
+of the new behavior that directly gives result and error without enforcing
+to parse the JSON object result.
+
+The subcall functions are also fully redesigned to allow precise handling
+of the context and event subscriptions. The new design allows you to specify:
+
+ - whether the subcall is made in the session of the caller or in the session
+   of the service
+ - whether the credentials to use are those of the caller or those of the
+   service
+ - whether the caller or the service or both or none will receive the
+   eventually events during the subcall.
+
+See [calls](reference-v3/func-api/#calls-and-job-functions) and
+[subcalls](reference-v3/func-req/#subcall-functions).
+
+
+Consider use of event handlers
+------------------------------
+
+Binding V3 brings new ways of handling event in services. You can register
+functions that will handle specific events and that accept closure arguments.
 
+See [**afb_api_event_handler_add** and **afb_api_event_handler_del**](reference-v3/func-api/#event-functions)