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>

25 files changed, 287 insertions, 74 deletions

diff --git a/include/afb/afb-api-x3-itf.h b/include/afb/afb-api-x3-itf.h
index 38b29196..b8cfadf6 100644
--- a/include/afb/afb-api-x3-itf.h
+++ b/include/afb/afb-api-x3-itf.h
@@ -30,6 +30,9 @@ struct afb_auth;
 struct afb_verb_v2;
 struct afb_verb_v3;
 
+/** @addtogroup AFB_API
+ *  @{ */
+
 /**
  * Structure for the APIv3
  */
@@ -260,3 +263,4 @@ struct afb_api_x3_itf
 		struct afb_api_x3 *api);
 };
 
+/** @} */
diff --git a/include/afb/afb-api-x3.h b/include/afb/afb-api-x3.h
index 81323ef5..9f06172b 100644
--- a/include/afb/afb-api-x3.h
+++ b/include/afb/afb-api-x3.h
@@ -20,6 +20,9 @@
 #include "afb-verbosity.h"
 #include "afb-api-x3-itf.h"
 
+/** @defgroup AFB_API
+ *  @{ */
+
 /**
  * Get the name of the 'api'.
  *
@@ -30,7 +33,8 @@
  * The returned value must not be changed nor freed.
  */
 static inline
-const char *afb_api_x3_name(struct afb_api_x3 *api)
+const char *afb_api_x3_name(
+			struct afb_api_x3 *api)
 {
 	return api->apiname;
 }
@@ -45,7 +49,8 @@ const char *afb_api_x3_name(struct afb_api_x3 *api)
  * @see afb_api_x3_set_userdata
  */
 static inline
-void *afb_api_x3_get_userdata(struct afb_api_x3 *api)
+void *afb_api_x3_get_userdata(
+			struct afb_api_x3 *api)
 {
 	return api->userdata;
 }
@@ -59,7 +64,9 @@ void *afb_api_x3_get_userdata(struct afb_api_x3 *api)
  * @see afb_api_x3_get_userdata
  */
 static inline
-void afb_api_x3_set_userdata(struct afb_api_x3 *api, void *value)
+void afb_api_x3_set_userdata(
+			struct afb_api_x3 *api,
+			void *value)
 {
 	api->userdata = value;
 }
@@ -84,16 +91,18 @@ void afb_api_x3_set_userdata(struct afb_api_x3 *api, void *value)
  * @see syslog
  */
 static inline
-int afb_api_x3_wants_log_level(struct afb_api_x3 *api, int level)
+int afb_api_x3_wants_log_level(
+			struct afb_api_x3 *api,
+			int level)
 {
 	return AFB_SYSLOG_MASK_WANT(api->logmask, level);
 }
 
 /**
- * Send to the journal with the log 'level' a message described
+ * Send to the journal with the logging 'level' a message described
  * by 'fmt' applied to the va-list 'args'.
  *
- * 'file', 'line' and 'func' are indicators of position of the code in source files
+ * 'file', 'line' and 'func' are indicators of code position in source files
  * (see macros __FILE__, __LINE__ and __func__).
  *
  * 'level' is defined by syslog standard:
@@ -111,7 +120,7 @@ int afb_api_x3_wants_log_level(struct afb_api_x3 *api, int level)
  * @param level the level of the message
  * @param file the source file that logs the messages or NULL
  * @param line the line in the source file that logs the message
- * @param func the name of the function in the source file that logs
+ * @param func the name of the function in the source file that logs (or NULL)
  * @param fmt the format of the message as in printf
  * @param args the arguments to the format string of the message as a va_list
  *
@@ -119,7 +128,14 @@ int afb_api_x3_wants_log_level(struct afb_api_x3 *api, int level)
  * @see printf
  */
 static inline
-void afb_api_x3_vverbose(struct afb_api_x3 *api, int level, const char *file, int line, const char *func, const char *fmt, va_list args)
+void afb_api_x3_vverbose(
+			struct afb_api_x3 *api,
+			int level,
+			const char *file,
+			int line,
+			const char *func,
+			const char *fmt,
+			va_list args)
 {
 	api->itf->vverbose(api, level, file, line, func, fmt, args);
 }
@@ -145,7 +161,7 @@ void afb_api_x3_vverbose(struct afb_api_x3 *api, int level, const char *file, in
  * @param level the level of the message
  * @param file the source file that logs the messages or NULL
  * @param line the line in the source file that logs the message
- * @param func the name of the function in the source file that logs
+ * @param func the name of the function in the source file that logs (or NULL)
  * @param fmt the format of the message as in printf
  * @param ... the arguments to the format string of the message
  *
@@ -180,7 +196,8 @@ void afb_api_x3_verbose(
  * @see afb_api_x3_get_system_bus
  */
 static inline
-struct sd_event *afb_api_x3_get_event_loop(struct afb_api_x3 *api)
+struct sd_event *afb_api_x3_get_event_loop(
+			struct afb_api_x3 *api)
 {
 	return api->itf->get_event_loop(api);
 }
@@ -196,7 +213,8 @@ struct sd_event *afb_api_x3_get_event_loop(struct afb_api_x3 *api)
  * @see afb_api_x3_get_system_bus
  */
 static inline
-struct sd_bus *afb_api_x3_get_user_bus(struct afb_api_x3 *api)
+struct sd_bus *afb_api_x3_get_user_bus(
+			struct afb_api_x3 *api)
 {
 	return api->itf->get_user_bus(api);
 }
@@ -213,7 +231,8 @@ struct sd_bus *afb_api_x3_get_user_bus(struct afb_api_x3 *api)
  */
 
 static inline
-struct sd_bus *afb_api_x3_get_system_bus(struct afb_api_x3 *api)
+struct sd_bus *afb_api_x3_get_system_bus(
+			struct afb_api_x3 *api)
 {
 	return api->itf->get_system_bus(api);
 }
@@ -228,10 +247,10 @@ struct sd_bus *afb_api_x3_get_system_bus(struct afb_api_x3 *api)
  * This can be used to get the path of the root directory using:
  *
  * ```C
- * char buffer[MAX_PATH];
- * int dirfd = afb_api_x3_rootdir_get_fd(api);
- * snprintf(buffer, sizeof buffer, "/proc/self/fd/%d", dirfd);
- * readlink(buffer, buffer, sizeof buffer);
+ * char buffer[MAX_PATH], proc[100];
+ * int dirfd = afb_api_rootdir_get_fd(api);
+ * snprintf(proc, sizeof proc, "/proc/self/fd/%d", dirfd);
+ * readlink(proc, buffer, sizeof buffer);
  * ```
  *
  * But note that within AGL this is the value given by the environment variable
@@ -244,7 +263,8 @@ struct sd_bus *afb_api_x3_get_system_bus(struct afb_api_x3 *api)
  * @see afb_api_x3_rootdir_open_locale
  */
 static inline
-int afb_api_x3_rootdir_get_fd(struct afb_api_x3 *api)
+int afb_api_x3_rootdir_get_fd(
+			struct afb_api_x3 *api)
 {
 	return api->itf->rootdir_get_fd(api);
 }
@@ -273,7 +293,11 @@ int afb_api_x3_rootdir_get_fd(struct afb_api_x3 *api)
  * @see afb_api_x3_rootdir_get_fd
  */
 static inline
-int afb_api_x3_rootdir_open_locale(struct afb_api_x3 *api, const char *filename, int flags, const char *locale)
+int afb_api_x3_rootdir_open_locale(
+			struct afb_api_x3 *api,
+			const char *filename,
+			int flags,
+			const char *locale)
 {
 	return api->itf->rootdir_open_locale(api, filename, flags, locale);
 }
@@ -297,14 +321,14 @@ int afb_api_x3_rootdir_open_locale(struct afb_api_x3 *api, const char *filename,
  *  - int signum: the signal catched if any or zero at the beginning
  *  - void *arg: the parameter 'argument'
  *
- * A typical implmentation of the job callback is:
+ * A typical implementation of the job callback is:
  *
  * ```C
  * void my_job_cb(int signum, void *arg)
  * {
  *	struct myarg_t *myarg = arg;
  *	if (signum)
- *		AFB_API_ERROR(myarg->api, "job interupted with signal %s", strsignal(signum));
+ *		AFB_API_ERROR(myarg->api, "job interrupted with signal %s", strsignal(signum));
  *	else
  *		really_do_my_job(myarg);
  * }
@@ -319,27 +343,38 @@ int afb_api_x3_rootdir_open_locale(struct afb_api_x3 *api, const char *filename,
  * @return 0 in case of success or -1 in case of error with errno set appropriately.
  */
 static inline
-int afb_api_x3_queue_job(struct afb_api_x3 *api, void (*callback)(int signum, void *arg), void *argument, void *group, int timeout)
+int afb_api_x3_queue_job(
+			struct afb_api_x3 *api,
+			void (*callback)(int signum, void *arg),
+			void *argument,
+			void *group,
+			int timeout)
 {
 	return api->itf->queue_job(api, callback, argument, group, timeout);
 }
 
 /**
- * Tells that it requires the API of "name" to exist
- * and if 'initialized' is not null to be initialized.
+ * Check that it requires the API of 'name'.
+ * If 'initialized' is not zero it request the API to be
+ * initialized, implying its initialization if needed.
+ * 
  * Calling this function is only allowed within init.
  *
  * A single request allows to require multiple apis.
  *
  * @param api the api that requires the other api by its name
- * @param name a space separated list of the names of the required api
+ * @param name a space separated list of required api names
  * @param initialized if zero, the api is just required to exist. If not zero,
- * the api is required to exist and to be initialized.
+ * the api is required to exist and to be initialized at return of the call
+ * (initializing it if needed and possible as a side effect of the call).
  *
  * @return 0 in case of success or -1 in case of error with errno set appropriately.
  */
 static inline
-int afb_api_x3_require_api(struct afb_api_x3 *api, const char *name, int initialized)
+int afb_api_x3_require_api(
+			struct afb_api_x3 *api,
+			const char *name,
+			int initialized)
 {
 	return api->itf->require_api(api, name, initialized);
 }
@@ -355,7 +390,10 @@ int afb_api_x3_require_api(struct afb_api_x3 *api, const char *name, int initial
  * @return 0 in case of success or -1 in case of error with errno set appropriately.
  */
 static inline
-int afb_api_x3_add_alias(struct afb_api_x3 *api, const char *name, const char *as_name)
+int afb_api_x3_add_alias(
+			struct afb_api_x3 *api,
+			const char *name,
+			const char *as_name)
 {
 	return api->itf->add_alias(api, name, as_name);
 }
@@ -380,7 +418,10 @@ int afb_api_x3_add_alias(struct afb_api_x3 *api, const char *name, const char *a
  * @return the count of clients that received the event.
  */
 static inline
-int afb_api_x3_broadcast_event(struct afb_api_x3 *api, const char *name, struct json_object *object)
+int afb_api_x3_broadcast_event(
+			struct afb_api_x3 *api,
+			const char *name,
+			struct json_object *object)
 {
 	return api->itf->event_broadcast(api, name, object);
 }
@@ -404,7 +445,9 @@ int afb_api_x3_broadcast_event(struct afb_api_x3 *api, const char *name, struct
  * @see afb_event_is_valid
  */
 static inline
-struct afb_event_x2 *afb_api_x3_make_event_x2(struct afb_api_x3 *api, const char *name)
+struct afb_event_x2 *afb_api_x3_make_event_x2(
+			struct afb_api_x3 *api,
+			const char *name)
 {
 	return api->itf->event_make(api, name);
 }
@@ -439,12 +482,15 @@ struct afb_event_x2 *afb_api_x3_make_event_x2(struct afb_api_x3 *api, const char
  */
 static inline
 void afb_api_x3_call_legacy(
-	struct afb_api_x3 *api,
-	const char *apiname,
-	const char *verb,
-	struct json_object *args,
-	void (*callback)(void *closure, int status, struct json_object *result, struct afb_api_x3 *api),
-	void *closure)
+			struct afb_api_x3 *api,
+			const char *apiname,
+			const char *verb,
+			struct json_object *args,
+			void (*callback)(void *closure,
+					int status,
+					struct json_object *result,
+					struct afb_api_x3 *api),
+			void *closure)
 {
 	api->itf->legacy_call(api, apiname, verb, args, callback, closure);
 }
@@ -475,11 +521,11 @@ void afb_api_x3_call_legacy(
  */
 static inline
 int afb_api_x3_call_sync_legacy(
-	struct afb_api_x3 *api,
-	const char *apiname,
-	const char *verb,
-	struct json_object *args,
-	struct json_object **result)
+			struct afb_api_x3 *api,
+			const char *apiname,
+			const char *verb,
+			struct json_object *args,
+			struct json_object **result)
 {
 	return api->itf->legacy_call_sync(api, apiname, verb, args, result);
 }
@@ -511,12 +557,12 @@ int afb_api_x3_call_sync_legacy(
  */
 static inline
 struct afb_api_x3 *afb_api_x3_new_api(
-	struct afb_api_x3 *api,
-	const char *apiname,
-	const char *info,
-	int noconcurrency,
-	int (*preinit)(void*, struct afb_api_x3 *),
-	void *closure)
+			struct afb_api_x3 *api,
+			const char *apiname,
+			const char *info,
+			int noconcurrency,
+			int (*preinit)(void*, struct afb_api_x3 *),
+			void *closure)
 {
 	return api->itf->api_new_api(api, apiname, info, noconcurrency, preinit, closure);
 }
@@ -537,8 +583,8 @@ struct afb_api_x3 *afb_api_x3_new_api(
  */
 static inline 
 int afb_api_x3_set_verbs_v2(
-	struct afb_api_x3 *api,
-	const struct afb_verb_v2 *verbs)
+			struct afb_api_x3 *api,
+			const struct afb_verb_v2 *verbs)
 {
 	return api->itf->api_set_verbs_v2(api, verbs);
 }
@@ -624,7 +670,10 @@ int afb_api_x3_del_verb(
 static inline
 int afb_api_x3_on_event(
 			struct afb_api_x3 *api,
-			void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object))
+			void (*onevent)(
+				struct afb_api_x3 *api,
+				const char *event,
+				struct json_object *object))
 {
 	return api->itf->api_set_on_event(api, onevent);
 }
@@ -719,7 +768,11 @@ static inline
 int afb_api_x3_event_handler_add(
 			struct afb_api_x3 *api,
 			const char *pattern,
-			void (*callback)(void *, const char*, struct json_object*, struct afb_api_x3*),
+			void (*callback)(
+				void *,
+				const char*,
+				struct json_object*,
+				struct afb_api_x3*),
 			void *closure)
 {
 	return api->itf->event_handler_add(api, pattern, callback, closure);
@@ -779,7 +832,12 @@ void afb_api_x3_call(
 			const char *apiname,
 			const char *verb,
 			struct json_object *args,
-			void (*callback)(void *closure, struct json_object *object, const char *error, const char * info, struct afb_api_x3 *api),
+			void (*callback)(
+				void *closure,
+				struct json_object *object,
+				const char *error,
+				const char * info,
+				struct afb_api_x3 *api),
 			void *closure)
 {
 	api->itf->call(api, apiname, verb, args, callback, closure);
@@ -850,7 +908,7 @@ int afb_api_x3_provide_class(
  * This function is only valid during the pre-initialization stage.
  *
  * @param api  the api that requires the classes
- * @param name a space separated list of the names of the requireded classes
+ * @param name a space separated list of the names of the required classes
  *
  * @returns 0 in case of success or a negative value in case of error.
  *
@@ -882,3 +940,5 @@ int afb_api_x3_delete_api(
 {
 	return api->itf->delete_api(api);
 }
+
+/** @} */
diff --git a/include/afb/afb-arg.h b/include/afb/afb-arg.h
index de3fb9b5..61b78afa 100644
--- a/include/afb/afb-arg.h
+++ b/include/afb/afb-arg.h
@@ -17,6 +17,9 @@
 
 #pragma once
 
+/** @addtogroup AFB_REQ
+ *  @{ */
+
 /**
  * Describes an argument (or parameter) of a request.
  *
@@ -31,3 +34,5 @@ struct afb_arg
 				/**< when the request is finalized this file is removed */
 };
 
+
+/** @} */
diff --git a/include/afb/afb-auth.h b/include/afb/afb-auth.h
index 3ce78666..31cbf6f8 100644
--- a/include/afb/afb-auth.h
+++ b/include/afb/afb-auth.h
@@ -17,6 +17,10 @@
 
 #pragma once
 
+/** @defgroup AFB_AUTH
+ *  @{ */
+
+
 /**
  * Enumeration  for authority (Session/Token/Assurance) definitions.
  *
@@ -72,3 +76,4 @@ struct afb_auth
 	const struct afb_auth *next;
 };
 
+/** @} */
\ No newline at end of file
diff --git a/include/afb/afb-binding-postdefs.h b/include/afb/afb-binding-postdefs.h
index 93cd46ef..9de630ab 100644
--- a/include/afb/afb-binding-postdefs.h
+++ b/include/afb/afb-binding-postdefs.h
@@ -74,8 +74,11 @@ typedef struct afb_binding_v3           afb_binding_t;
 typedef struct afb_event_x2            *afb_event_t;
 typedef struct afb_req_x2              *afb_req_t;
 typedef struct afb_api_x3              *afb_api_t;
+typedef enum afb_req_subcall_flags	afb_req_subcall_flags_t;
 
 #define afbBindingExport		afbBindingV3
+#define afbBindingRoot			afbBindingV3root
+#define afbBindingEntry			afbBindingV3entry
 
 /* compatibility with previous versions */
 
diff --git a/include/afb/afb-binding-predefs.h b/include/afb/afb-binding-predefs.h
index f1765edb..f8806165 100644
--- a/include/afb/afb-binding-predefs.h
+++ b/include/afb/afb-binding-predefs.h
@@ -282,10 +282,12 @@
 #define afb_req_x2_get_uid		afb_req_get_uid
 #define afb_req_x2_get_client_info	afb_req_get_client_info
 
+#define afb_req_x2_subcall_flags	afb_req_subcall_flags
 #define afb_req_x2_subcall_catch_events	afb_req_subcall_catch_events
 #define afb_req_x2_subcall_pass_events	afb_req_subcall_pass_events
 #define afb_req_x2_subcall_on_behalf	afb_req_subcall_on_behalf
-
+#define afb_req_x2_subcall_api_session	afb_req_subcall_api_session
+	
 #define afb_event_x2			afb_event
 #define afb_event_x2_is_valid		afb_event_is_valid
 #define afb_event_x2_broadcast		afb_event_broadcast
diff --git a/include/afb/afb-binding-v3.h b/include/afb/afb-binding-v3.h
index ece3f1c4..52a3a8d2 100644
--- a/include/afb/afb-binding-v3.h
+++ b/include/afb/afb-binding-v3.h
@@ -257,6 +257,6 @@ extern const struct afb_binding_v3 afbBindingV3;
 #define afb_daemon_require_api_v3(...)		afb_api_require_api(afbBindingV3root,__VA_ARGS__)
 #define afb_daemon_add_alias_v3(...)		afb_api_add_alias(afbBindingV3root,__VA_ARGS__)
 
-#define afb_service_call_v3(...)		afb_api_call_legacy(afbBindingV3root,__VA_ARGS__)
-#define afb_service_call_sync_v3(...)		afb_api_call_sync_legacy(afbBindingV3root,__VA_ARGS__)
+#define afb_service_call_v3(...)		afb_api_call(afbBindingV3root,__VA_ARGS__)
+#define afb_service_call_sync_v3(...)		afb_api_call_sync(afbBindingV3root,__VA_ARGS__)
 
diff --git a/include/afb/afb-binding.hpp b/include/afb/afb-binding.hpp
index 27715f39..21847722 100644
--- a/include/afb/afb-binding.hpp
+++ b/include/afb/afb-binding.hpp
@@ -496,16 +496,21 @@ inline bool wants_debugs()
 	{ return AFB_SYSLOG_MASK_WANT_DEBUG(logmask()); }
 
 #if AFB_BINDING_VERSION >= 3
-inline void call(const char *api, const char *verb, struct json_object *args, void (*callback)(void*closure, int iserror, struct json_object *result, afb_api_t api), void *closure)
+inline void call(const char *api, const char *verb, struct json_object *args, void (*callback)(void*closure, struct json_object *result, const char *error, const char *info, afb_api_t api), void *closure)
 {
 	afb_service_call(api, verb, args, callback, closure);
 }
 
 template <class T>
-inline void call(const char *api, const char *verb, struct json_object *args, void (*callback)(T*closure, int iserror, struct json_object *result, afb_api_t api), T *closure)
+inline void call(const char *api, const char *verb, struct json_object *args, void (*callback)(T*closure, struct json_object *result, const char *error, const char *info, afb_api_t api), T *closure)
 {
 	afb_service_call(api, verb, args, reinterpret_cast<void(*)(void*,int,json_object*,afb_api_t)>(callback), reinterpret_cast<void*>(closure));
 }
+
+inline bool callsync(const char *api, const char *verb, struct json_object *args, struct json_object *&result, char *&error, char *&info)
+{
+	return !!afb_service_call_sync(api, verb, args, &result, &error, &info);
+}
 #else
 inline void call(const char *api, const char *verb, struct json_object *args, void (*callback)(void*closure, int iserror, struct json_object *result), void *closure)
 {
@@ -517,12 +522,12 @@ inline void call(const char *api, const char *verb, struct json_object *args, vo
 {
 	afb_service_call(api, verb, args, reinterpret_cast<void(*)(void*,int,json_object*)>(callback), reinterpret_cast<void*>(closure));
 }
-#endif
 
 inline bool callsync(const char *api, const char *verb, struct json_object *args, struct json_object *&result)
 {
 	return !!afb_service_call_sync(api, verb, args, &result);
 }
+#endif
 
 /*************************************************************************/
 /* declaration of the binding's authorization s                          */
diff --git a/include/afb/afb-daemon-itf-x1.h b/include/afb/afb-daemon-itf-x1.h
index 3ca12eba..744892d4 100644
--- a/include/afb/afb-daemon-itf-x1.h
+++ b/include/afb/afb-daemon-itf-x1.h
@@ -27,6 +27,9 @@ struct afb_req_x1;
 struct afb_event_x1;
 struct afb_api_x3;
 
+/** @defgroup AFB_DAEMON
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -89,3 +92,4 @@ struct afb_daemon_x1
 	struct afb_api_x3 *closure;             /**< the closure when calling these functions */
 };
 
+/** @} */
diff --git a/include/afb/afb-daemon-v1.h b/include/afb/afb-daemon-v1.h
index d84517d1..c268bb83 100644
--- a/include/afb/afb-daemon-v1.h
+++ b/include/afb/afb-daemon-v1.h
@@ -19,6 +19,9 @@
 
 #include "afb-daemon-itf-x1.h"
 
+/** @addtogroup AFB_DAEMON
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -236,3 +239,5 @@ static inline int afb_daemon_new_api_v1(
 {
 	return -!daemon.itf->new_api(daemon.closure, api, info, noconcurrency, preinit, closure);
 }
+
+/** @} */
diff --git a/include/afb/afb-daemon-v2.h b/include/afb/afb-daemon-v2.h
index f3c2c904..65e4afbc 100644
--- a/include/afb/afb-daemon-v2.h
+++ b/include/afb/afb-daemon-v2.h
@@ -19,6 +19,9 @@
 
 #include "afb-daemon-itf-x1.h"
 
+/** @addtogroup AFB_DAEMON
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -214,3 +217,5 @@ static inline int afb_daemon_new_api_v2(
 	return -!(afb_get_daemon_v2().itf->new_api(afb_get_daemon_v2().closure, api, info, noconcurrency, preinit, closure));
 }
 
+/** @} */
+
diff --git a/include/afb/afb-event-x1-itf.h b/include/afb/afb-event-x1-itf.h
index afd033b8..b2c582e4 100644
--- a/include/afb/afb-event-x1-itf.h
+++ b/include/afb/afb-event-x1-itf.h
@@ -19,6 +19,9 @@
 
 #include "afb-event-x2-itf.h"
 
+/** @addtogroup AFB_EVENT
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -30,3 +33,4 @@ struct afb_event_x1
 	struct afb_event_x2 *closure;		/**< the closure argument for functions of 'itf' */
 };
 
+/** @} */
diff --git a/include/afb/afb-event-x1.h b/include/afb/afb-event-x1.h
index 1fc7696f..039a14fd 100644
--- a/include/afb/afb-event-x1.h
+++ b/include/afb/afb-event-x1.h
@@ -19,6 +19,9 @@
 
 #include "afb-event-x1-itf.h"
 
+/** @addtogroup AFB_EVENT
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -109,3 +112,4 @@ static inline void afb_event_x1_addref(struct afb_event_x1 event)
 	event.itf->addref(event.closure);
 }
 
+/** @} */
diff --git a/include/afb/afb-event-x2-itf.h b/include/afb/afb-event-x2-itf.h
index ecc42c79..b2a01c7b 100644
--- a/include/afb/afb-event-x2-itf.h
+++ b/include/afb/afb-event-x2-itf.h
@@ -20,6 +20,9 @@
 struct afb_event_x2;
 struct afb_event_x2_itf;
 
+/** @addtogroup AFB_EVENT
+ *  @{ */
+
 /**
  * Interface for handling event_x2.
  *
@@ -55,3 +58,4 @@ struct afb_event_x2
 	const struct afb_event_x2_itf *itf;	/**< the interface functions to use */
 };
 
+/** @} */
diff --git a/include/afb/afb-event-x2.h b/include/afb/afb-event-x2.h
index f0a27877..9732cad1 100644
--- a/include/afb/afb-event-x2.h
+++ b/include/afb/afb-event-x2.h
@@ -19,6 +19,9 @@
 
 #include "afb-event-x2-itf.h"
 
+/** @defgroup AFB_EVENT
+ *  @{ */
+
 /**
  * Checks whether the 'event' is valid or not.
  *
@@ -111,3 +114,4 @@ static inline struct afb_event_x2 *afb_event_x2_addref(
 	return event->itf->addref(event);
 }
 
+/** @} */
diff --git a/include/afb/afb-req-v1.h b/include/afb/afb-req-v1.h
index 40fb3b85..a6e202bd 100644
--- a/include/afb/afb-req-v1.h
+++ b/include/afb/afb-req-v1.h
@@ -20,6 +20,9 @@
 #include <stdlib.h>
 #include "afb-req-x1.h"
 
+/** @addtogroup AFB_REQ
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -54,3 +57,5 @@ static inline struct afb_req_x1 afb_req_unstore_x1_v1(struct afb_req_x1 *req)
 	return result;
 }
 
+
+/** @} */
diff --git a/include/afb/afb-req-v2.h b/include/afb/afb-req-v2.h
index f7901908..75ef841d 100644
--- a/include/afb/afb-req-v2.h
+++ b/include/afb/afb-req-v2.h
@@ -19,6 +19,9 @@
 
 #include "afb-req-x1.h"
 
+/** @addtogroup AFB_REQ
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -32,3 +35,5 @@ static inline struct afb_stored_req *afb_req_x1_store_v2(struct afb_req_x1 req)
 	return req.itf->legacy_store_req(req.closure);
 }
 
+
+/** @} */
diff --git a/include/afb/afb-req-x1-itf.h b/include/afb/afb-req-x1-itf.h
index dce936d1..7d82ad03 100644
--- a/include/afb/afb-req-x1-itf.h
+++ b/include/afb/afb-req-x1-itf.h
@@ -19,6 +19,9 @@
 
 #include "afb-req-x2-itf.h"
 
+/** @addtogroup AFB_REQ
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -30,3 +33,5 @@ struct afb_req_x1
 	struct afb_req_x2 *closure;		/**< the closure argument for functions of 'itf' */
 };
 
+
+/** @} */
diff --git a/include/afb/afb-req-x1.h b/include/afb/afb-req-x1.h
index cea17d0c..d9fa1bea 100644
--- a/include/afb/afb-req-x1.h
+++ b/include/afb/afb-req-x1.h
@@ -20,6 +20,9 @@
 #include "afb-req-x1-itf.h"
 #include "afb-event-x1.h"
 
+/** @addtogroup AFB_REQ
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -451,3 +454,5 @@ static inline struct json_object *afb_req_x1_get_client_info(struct afb_req_x1 r
 }
 
 
+
+/** @} */
diff --git a/include/afb/afb-req-x2-itf.h b/include/afb/afb-req-x2-itf.h
index 9de7a214..c76329d0 100644
--- a/include/afb/afb-req-x2-itf.h
+++ b/include/afb/afb-req-x2-itf.h
@@ -29,6 +29,9 @@ struct afb_event_x2;
 struct afb_api_x3;
 struct afb_stored_req;
 
+/** @addtogroup AFB_REQ
+ *  @{ */
+
 /**
  * structure for the request
  */
@@ -62,15 +65,16 @@ struct afb_req_x2
 };
 
 /**
- * subcall modes
+ * subcall flags
  *
  * When making subcalls, it is now possible to explicitely set the subcall
- * mode to a combination of the following mode using binary OR.
+ * mode to a combination of the following flags using binary OR.
  *
- * In particular, the following combination of modes are to be known:
+ * In particular, the following combination of flags are to be known:
  *
  *  - for **subcall** having a similar behaviour to the subcalls of bindings
  *    version 1 and 2: afb_req_x2_subcall_pass_events|afb_req_x2_subcall_on_behalf
+ * 
  *  - for **subcall** having the behaviour of the **call**:
  *    afb_req_x2_subcall_catch_events|afb_req_x2_subcall_api_session
  *
@@ -304,3 +308,5 @@ struct afb_req_x2_itf
 			char **info);
 };
 
+
+/** @} */
diff --git a/include/afb/afb-req-x2.h b/include/afb/afb-req-x2.h
index 70ffab80..bd4bc767 100644
--- a/include/afb/afb-req-x2.h
+++ b/include/afb/afb-req-x2.h
@@ -20,6 +20,9 @@
 #include "afb-req-x2-itf.h"
 #include "afb-api-x3.h"
 
+/** @defgroup AFB_REQ
+ *  @{ */
+
 /**
  * Checks whether the request 'req' is valid or not.
  *
@@ -560,6 +563,46 @@ int afb_req_x2_subcall_sync_legacy(
 }
 
 /**
+ * Send associated to 'req' a message described by 'fmt' and its 'args'
+ * to the journal for the verbosity 'level'.
+ *
+ * 'file', 'line' and 'func' are indicators of position of the code in source files
+ * (see macros __FILE__, __LINE__ and __func__).
+ *
+ * 'level' is defined by syslog standard:
+ *      EMERGENCY         0        System is unusable
+ *      ALERT             1        Action must be taken immediately
+ *      CRITICAL          2        Critical conditions
+ *      ERROR             3        Error conditions
+ *      WARNING           4        Warning conditions
+ *      NOTICE            5        Normal but significant condition
+ *      INFO              6        Informational
+ *      DEBUG             7        Debug-level messages
+ *
+ * @param req the request
+ * @param level the level of the message
+ * @param file the source filename that emits the message or NULL
+ * @param line the line number in the source filename that emits the message
+ * @param func the name of the function that emits the message or NULL
+ * @param fmt the message format as for printf
+ * @param args the arguments to the format 'fmt'
+ *
+ * @see printf
+ * @see afb_req_x2_verbose
+ */
+static inline
+void afb_req_x2_vverbose(
+			struct afb_req_x2 *req,
+			int level, const char *file,
+			int line,
+			const char * func,
+			const char *fmt,
+			va_list args)
+{
+	req->itf->vverbose(req, level, file, line, func, fmt, args);
+}
+
+/**
  * Send associated to 'req' a message described by 'fmt' and following parameters
  * to the journal for the verbosity 'level'.
  *
@@ -582,9 +625,10 @@ int afb_req_x2_subcall_sync_legacy(
  * @param line the line number in the source filename that emits the message
  * @param func the name of the function that emits the message or NULL
  * @param fmt the message format as for printf
- * @param ... the arguments of the printf
+ * @param ... the arguments of the format 'fmt'
  *
  * @see printf
+ * @see afb_req_x2_vverbose
  */
 __attribute__((format(printf, 6, 7)))
 static inline
@@ -598,7 +642,7 @@ void afb_req_x2_verbose(
 {
 	va_list args;
 	va_start(args, fmt);
-	req->itf->vverbose(req, level, file, line, func, fmt, args);
+	afb_req_x2_verbose(req, level, file, line, func, fmt, args);
 	va_end(args);
 }
 
@@ -756,3 +800,6 @@ int afb_req_x2_subcall_sync(
 {
 	return req->itf->subcallsync(req, api, verb, args, flags, object, error, info);
 }
+
+
+/** @} */
diff --git a/include/afb/afb-service-itf-x1.h b/include/afb/afb-service-itf-x1.h
index fcdd08e1..9e36fd0d 100644
--- a/include/afb/afb-service-itf-x1.h
+++ b/include/afb/afb-service-itf-x1.h
@@ -19,6 +19,9 @@
 
 struct afb_api_x3;
 
+/** @defgroup AFB_SERVICE
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -49,3 +52,4 @@ struct afb_service_x1
 	struct afb_api_x3 *closure;
 };
 
+/** @} */
diff --git a/include/afb/afb-service-v1.h b/include/afb/afb-service-v1.h
index a3265af8..e4a4eee1 100644
--- a/include/afb/afb-service-v1.h
+++ b/include/afb/afb-service-v1.h
@@ -19,6 +19,9 @@
 
 #include "afb-service-itf-x1.h"
 
+/** @addtogroup AFB_SERVICE
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -84,3 +87,4 @@ static inline int afb_service_call_sync_v1(
 	return service.itf->call_sync(service.closure, api, verb, args, result);
 }
 
+/** @} */
diff --git a/include/afb/afb-service-v2.h b/include/afb/afb-service-v2.h
index da59786d..1601a660 100644
--- a/include/afb/afb-service-v2.h
+++ b/include/afb/afb-service-v2.h
@@ -19,6 +19,9 @@
 
 #include "afb-service-itf-x1.h"
 
+/** @addtogroup AFB_SERVICE
+ *  @{ */
+
 /**
  * @deprecated use bindings version 3
  *
@@ -80,3 +83,4 @@ static inline int afb_service_call_sync_v2(
 	return afb_get_service_v2().itf->call_sync(afb_get_service_v2().closure, api, verb, args, result);
 }
 
+/** @} */
diff --git a/include/afb/afb-verbosity.h b/include/afb/afb-verbosity.h
index dd34f841..288205bd 100644
--- a/include/afb/afb-verbosity.h
+++ b/include/afb/afb-verbosity.h
@@ -17,11 +17,14 @@
 
 #pragma once
 
-#define AFB_VERBOSITY_LEVEL_ERROR	0
-#define AFB_VERBOSITY_LEVEL_WARNING	1
-#define AFB_VERBOSITY_LEVEL_NOTICE	2
-#define AFB_VERBOSITY_LEVEL_INFO	3
-#define AFB_VERBOSITY_LEVEL_DEBUG	4
+/** @defgroup AFB_LOGGING
+ *  @{ */
+
+#define AFB_VERBOSITY_LEVEL_ERROR	0 /**< @deprecated in favor of @ref AFB_SYSLOG_LEVEL_ERROR */
+#define AFB_VERBOSITY_LEVEL_WARNING	1 /**< @deprecated in favor of @ref AFB_SYSLOG_LEVEL_WARNING */
+#define AFB_VERBOSITY_LEVEL_NOTICE	2 /**< @deprecated in favor of @ref AFB_SYSLOG_LEVEL_NOTICE */
+#define AFB_VERBOSITY_LEVEL_INFO	3 /**< @deprecated in favor of @ref AFB_SYSLOG_LEVEL_INFO */
+#define AFB_VERBOSITY_LEVEL_DEBUG	4 /**< @deprecated in favor of @ref AFB_SYSLOG_LEVEL_DEBUG */
 
 #define AFB_SYSLOG_LEVEL_EMERGENCY	0
 #define AFB_SYSLOG_LEVEL_ALERT		1
@@ -32,13 +35,13 @@
 #define AFB_SYSLOG_LEVEL_INFO		6
 #define AFB_SYSLOG_LEVEL_DEBUG		7
 
-#define AFB_VERBOSITY_LEVEL_WANT(verbosity,level)	((verbosity) >= (level))
+#define AFB_VERBOSITY_LEVEL_WANT(verbosity,level)	((verbosity) >= (level)) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT */
 
-#define AFB_VERBOSITY_LEVEL_WANT_ERROR(x)	AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_ERROR)
-#define AFB_VERBOSITY_LEVEL_WANT_WARNING(x)	AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_WARNING)
-#define AFB_VERBOSITY_LEVEL_WANT_NOTICE(x)	AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_NOTICE)
-#define AFB_VERBOSITY_LEVEL_WANT_INFO(x)	AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_INFO)
-#define AFB_VERBOSITY_LEVEL_WANT_DEBUG(x)	AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_DEBUG)
+#define AFB_VERBOSITY_LEVEL_WANT_ERROR(x)	AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_ERROR) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT_ERROR */
+#define AFB_VERBOSITY_LEVEL_WANT_WARNING(x)	AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_WARNING) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT_WARNING */
+#define AFB_VERBOSITY_LEVEL_WANT_NOTICE(x)	AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_NOTICE) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT_NOTICE */
+#define AFB_VERBOSITY_LEVEL_WANT_INFO(x)	AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_INFO) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT_INFO */
+#define AFB_VERBOSITY_LEVEL_WANT_DEBUG(x)	AFB_VERBOSITY_LEVEL_WANT(x,AFB_VERBOSITY_LEVEL_DEBUG) /**< @deprecated in favor of @ref AFB_SYSLOG_MASK_WANT_DEBUG */
 
 #define AFB_SYSLOG_MASK_WANT(verbomask,level)	((verbomask) & (1 << (level)))
 
@@ -54,6 +57,16 @@
 #define AFB_SYSLOG_LEVEL_FROM_VERBOSITY(x)	((x) + (AFB_SYSLOG_LEVEL_ERROR - AFB_VERBOSITY_LEVEL_ERROR))
 #define AFB_SYSLOG_LEVEL_TO_VERBOSITY(x)	((x) + (AFB_VERBOSITY_LEVEL_ERROR - AFB_SYSLOG_LEVEL_ERROR))
 
+/**
+ * Transform a mask of verbosity to its significant level of verbosity.
+ * 
+ * @param verbomask the mask
+ * 
+ * @return the upper level that is not null, truncated to AFB_SYSLOG_LEVEL_DEBUG
+ * 
+ * @example _afb_verbomask_to_upper_level_(5) -> 2
+ * @example _afb_verbomask_to_upper_level_(16) -> 4
+ */
 static inline int _afb_verbomask_to_upper_level_(int verbomask)
 {
 	int result = 0;
@@ -62,3 +75,4 @@ static inline int _afb_verbomask_to_upper_level_(int verbomask)
 	return result;
 }
 
+/** @} */
\ No newline at end of file