Fix client libraries API documentation

Change-Id: I68064d554eb95241ba296267aca52bdf9e7119c9

diff --git a/src/include/cynara-client-async.h b/src/include/cynara-client-async.h
index 0fa37d8..b394485 100644 (file)
--- a/src/include/cynara-client-async.h
+++ b/src/include/cynara-client-async.h
@@ -86,15 +86,15 @@ typedef enum {
  *    (CYNARA_CALL_CAUSE_FINISH)
  * 4) when connection to cynara service was broken and cannot be established again
  *    - probably cynara is unoperational (CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE)
- * Api functions called during this callback with CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE
+ * API functions called during this callback with CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE
  * or CYNARA_CALL_CAUSE_FINISH cause will return CYNARA_API_OPERATION_NOT_ALLOWED.
  * cynara_async_finish() will be ignored if called from within this callback.
  *
  * \param[in] check_id Number identifying check request. Number is generated in
- *            cynara_async_create_request() or cynara_async_create_simple_request and returned to
- *            user. It can be used to match response with sent request.
+ *            cynara_async_create_request() or cynara_async_create_simple_request()
+ *            and returned to user. It can be used to match response with sent request.
  *            Number is valid since cynara_async_create_request() call or
- *            cynara_async_create_simple_request call till callback call.
+ *            cynara_async_create_simple_request() call till callback call.
  *            After that the number can be reused by cynara to run new request.
  * \param[in] cause Cause of triggering this callback.
  * \param[in] response Response for created request. Should be ignored if cause is not
@@ -116,7 +116,7 @@ typedef void (*cynara_response_callback) (cynara_check_id check_id, cynara_async
  * Status change is triggered when check_request or cancel needs to be send to
  * cynara service or sending data has finished and there is nothing more to send to cynara
  * service.
- * Note, that provided file descriptor is used internally by libcynara
+ * Note, that provided file descriptor is used internally by libcynara-client-async
  * so user should not use it in other way than waiting on it in event loop.
  * In particular user should not write to, read from or close this fd.
  * CYNARA_API_OPERATION_NOT_ALLOWED will be returned for every api function called in this callback.
@@ -464,9 +464,9 @@ int cynara_async_create_request(cynara_async *p_cynara, const char *client,
  * \par Method of function operation:
  * This function is very similar to cynara_async_create_request() with the difference, that in case
  * of answer not being one of CYNARA_API_PERMISSION_DENIED or CYNARA_API_PERMISSION_ALLOWED,
- * no external application will be consulted. Instead, CYNARA_API_ACCESS_NOT_RESOLVED is returned,
- * meaning, that only creating full request through cynara_async_create_request API would yield
- * eventual answer.
+ * no external application will be consulted. Instead, CYNARA_API_ACCESS_NOT_RESOLVED is returned
+ * by a callback, meaning, that only creating full request through cynara_async_create_request() API
+ * would yield eventual answer.
  * If access permission cannot be acquired without usage of external agents, callback can be
  * called with CYNARA_CALL_CAUSE_ANSWER and response value being CYNARA_API_ACCESS_NOT_RESOLVED.
  *

diff --git a/src/include/cynara-client.h b/src/include/cynara-client.h
index 89a8e7b..cb16854 100644 (file)
--- a/src/include/cynara-client.h
+++ b/src/include/cynara-client.h
@@ -41,12 +41,12 @@ typedef struct cynara_configuration cynara_configuration;
  * API calls.
  *
  * \par Purpose:
- * For configuration parameter to be used in cynara initialization function, this API must be
+ * For configuration parameter to be used in cynara_initialize() function, this API must be
  * called before any other cynara configuration API function.
  * It will create cynara_configuration structure, an optional parameter of cynara initialization.
  *
  * \par Typical use case:
- * Once before setting parameters of cynara async configuration and passing to
+ * Once before setting parameters of cynara configuration and passing to
  * cynara_initialize().
  *
  * \par Method of function operation:
@@ -106,8 +106,8 @@ void cynara_configuration_destroy(cynara_configuration *p_conf);
  * This API is used to change default number of cached responses returned from cynara.
  *
  * \par Typical use case:
- * Once before setting parameters of cynara async configuration and passing to
- * cynara_initialize().
+ * Once after cynara_configuration is created with cynara_configuration_create()
+ * and before passing configuration to cynara_initialize().
  *
  * \par Method of function operation:
  * This API initializes cache with given capacity.
@@ -143,7 +143,7 @@ int cynara_configuration_set_cache_size(cynara_configuration *p_conf, size_t cac
  * Once before a service can call cynara_check.
  *
  * \par Method of function operation:
- * This API initializes inner library structures [TODO describe more details] and in case of success
+ * This API initializes inner library structures and in case of success
  * creates and returns cynara structure.
  *
  * \par Sync (or) Async:
@@ -154,7 +154,7 @@ int cynara_configuration_set_cache_size(cynara_configuration *p_conf, size_t cac
  * application from different threads, they must be put into mutex protected critical section.
  *
  * \par Important notes:
- * Structure cynara created by cynara_initialize call should be released with cynara_finish.
+ * Structure cynara created by cynara_initialize() call should be released with cynara_finish().
  *
  * \param[out] pp_cynara Place holder for created cynara structure.
  * \param[in] p_conf Configuration for cynara-client library. NULL for default parameters.
@@ -166,17 +166,16 @@ int cynara_initialize(cynara **pp_cynara, const cynara_configuration *p_conf);
 
 /**
  * \par Description:
- * Release cynara-client library and destroy structure created with cynara_initialize.
+ * Release cynara-client library and destroy structure created with cynara_initialize().
  *
  * \par Purpose:
  * This API should be used to clean up after usage of cynara-client library.
  *
  * \par Typical use case:
- * Once after last call to cynara_check.
+ * Once after last call to cynara_check().
  *
  * \par Method of function operation:
- * This API initializes releases inner library structures [TODO describe more details]
- * and destroys cynara structure.
+ * This API releases inner library structures and destroys cynara structure.
  *
  * \par Sync (or) Async:
  * This is a Synchronous API.
@@ -186,7 +185,7 @@ int cynara_initialize(cynara **pp_cynara, const cynara_configuration *p_conf);
  * application from different threads, they must be put into mutex protected critical section.
  *
  * \par Important notes:
- * No other call to libcynara-client should be made after call to cynara_finish.
+ * No other call to libcynara-client should be made after call to cynara_finish().
  *
  * \param[in] p_cynara Cynara structure.
  *
@@ -223,7 +222,7 @@ int cynara_finish(cynara *p_cynara);
  *
  * \par Important notes:
  * An external application may be launched to allow user interaction in granting or denying access.
- * Call to cynara_check needs cynara structure to be created first with call to cynara_initialize.
+ * Call to cynara_check needs cynara structure to be created first with call to cynara_initialize().
  *
  * \param[in] p_cynara Cynara structure.
  * \param[in] client Application or process identifier.
@@ -270,8 +269,8 @@ int cynara_check(cynara *p_cynara, const char *client, const char *client_sessio
  * If the answer cannot be resolved in one of CYNARA_API_PERMISSION_DENIED or
  * CYNARA_API_PERMISSION_ALLOWED without communicating with external application the API will return
  * CYNARA_API_ACCESS_NOT_RESOLVED.
- * Call to cynara_simple_check needs cynara structure to be created first with call to
- * cynara_initialize.
+ * Call to cynara_simple_check() needs cynara structure to be created first with call to
+ * cynara_initialize().
  *
  * \param[in] p_cynara Cynara structure.
  * \param[in] client Application or process identifier.