Add documentation to cynara-creds-commons.h

Signed-off-by: Radoslaw Bartosiak <r.bartosiak@samsung.com>
Change-Id: I717b1cc988c5fc6780d42774c75a4596a522c3e2

diff --git a/src/include/cynara-creds-commons.h b/src/include/cynara-creds-commons.h
index 7e46126..1bb3ffc 100644 (file)
--- a/src/include/cynara-creds-commons.h
+++ b/src/include/cynara-creds-commons.h
@@ -40,8 +40,67 @@ enum cynara_user_creds {
 extern "C" {
 #endif
 
+/**
+ * \par Description:
+ * Gets the system default method value for client feature used in cynara-creds.
+ *
+ * \par Purpose:
+ * Functions cynara_creds_dbus_get_client() and cynara_creds_socket_get_client() take a method
+ * parameter, which determines a kind of process feature (i.e PID, SMACK label) returned by them.
+ * The described function provides implementation for obtaining a system default value
+ * for this parameter.
+ *
+ * \par Typical use case:
+ * The function might be called before cynara_creds_dbus_get_client() and cynara_creds_socket_get_client(),
+ * when functions shall be invoked with system default value of method parameter.
+ *
+ * \par Method of function operation:
+ * Now the function is mocked up. It sets method to CLIENT_METHOD_SMACK and returns CYNARA_API_SUCCESS.
+ * In the future the function will probably read the value from /etc/cynara/cynara_client_creds file.
+ *
+ * \par Sync (or) Async:
+ * This is a synchronous API.
+ *
+ * \par Thread safety:
+ * This function is thread-safe.
+ *
+ * \param[out] method Placeholder for system default client feature
+ *                     (like CLIENT_METHOD_SMACK, CLIENT_METHOD_PID)
+ *
+ * \return CYNARA_API_SUCCESS on success, negative error code on error
+ */
 int cynara_creds_get_default_client_method(enum cynara_client_creds *method);
 
+/**
+ * \par Description:
+ * Gets the system default method value for user feature used in cynara-creds.
+ *
+ * \par Purpose:
+ * Functions cynara_creds_dbus_get_user() and cynara_creds_socket_get_user() take a method
+ * parameter, which determines a kind of process feature (i.e UID, GID) returned by them.
+ * The described function provides implementation for obtaining a system default value
+ * for this parameter.
+ *
+ * \par Typical use case:
+ * The function might be called before cynara_creds_dbus_get_user() and cynara_creds_socket_get_user(),
+ * when functions shall be invoked with system default value of method parameter.
+ *
+ * \par Method of function operation:
+ *
+ * The function reads the value from /etc/cynara/cynara_user_creds file.
+ * Now the function is mocked up. It sets method to USER_METHOD_UID and returns CYNARA_API_SUCCESS.
+ * In the future the function will probably read the value from /etc/cynara/cynara_user_creds file.
+ *
+ * \par Sync (or) Async:
+ * This is a synchronous API.
+ *
+ * \par Thread safety:
+ * This function is thread-safe.
+ *
+ * \param[out] method Placeholder for system default user feature (like USER_METHOD_UID, USER_METHOD_GID)
+ *
+ * \return CYNARA_API_SUCCESS on success, negative error code on error
+ */
 int cynara_creds_get_default_user_method(enum cynara_user_creds *method);
 
 #ifdef __cplusplus