From 0f8d87a7d11fdf3d5e180891ff104732142003bc Mon Sep 17 00:00:00 2001 From: Lukasz Pawelczyk Date: Fri, 10 Jun 2016 13:42:52 +0200 Subject: [PATCH] Fix doxygen comments This fixes all of the doxygen comment tags (/**) and a plethora of other errors and inconsistencies. Mostly missing argument names for \param. This is not a comprehensive doxygen comments review, but it does fix all the doxygen errors and warnings and makes it possible to generate somewhat correct doxygen documentation. Change-Id: Ib030dab7a5c116a8a6a9ccb3665dd79163a7b632 --- src/include/app-manager.h | 81 ++++++++++++++++++++++---------------------- src/include/app-runtime.h | 34 +++++++++---------- src/include/app-sharing.h | 36 ++++++++++---------- src/include/label-monitor.h | 1 + src/include/policy-manager.h | 23 +++++++++---- src/include/user-manager.h | 47 ++++++++++++------------- 6 files changed, 117 insertions(+), 105 deletions(-) diff --git a/src/include/app-manager.h b/src/include/app-manager.h index 0fc7085..0efb77a 100644 --- a/src/include/app-manager.h +++ b/src/include/app-manager.h @@ -26,104 +26,105 @@ extern "C" { #endif -/* +/** * This function is responsible for initialize app_inst_req data structure * It uses dynamic allocation inside and user responsibility is to call * app_inst_req_free() for freeing allocated resources * - * \param[in] Address of pointer for handle app_inst_req structure + * \param[in] pp_req Address of pointer for handle app_inst_req structure * \return API return code or error code */ int security_manager_app_inst_req_new(app_inst_req **pp_req); -/* +/** * This function is used to free resources allocated by calling app_inst_req_new() - * \param[in] Pointer handling allocated app_inst_req structure + * + * \param[in] p_req Pointer handling allocated app_inst_req structure */ void security_manager_app_inst_req_free(app_inst_req *p_req); -/* +/** * This function is used to set up target Tizen API version for app in app_inst_req structure * - * \param[in] Pointer handling app_inst_req structure - * \param[in] Target Tizen version + * \param[in] p_req Pointer handling app_inst_req structure + * \param[in] tizen_ver Target Tizen version * \return API return code or error code */ int security_manager_app_inst_req_set_target_version(app_inst_req *p_req, const char *tizen_ver); -/* +/** * This function is used to set up application identifier in app_inst_req structure * - * \param[in] Pointer handling app_inst_req structure - * \param[in] Application identifier + * \param[in] p_req Pointer handling app_inst_req structure + * \param[in] app_id Application identifier * \return API return code or error code */ int security_manager_app_inst_req_set_app_id(app_inst_req *p_req, const char *app_id); -/* +/** * This function is used to set up package identifier in app_inst_req structure * - * \param[in] Pointer handling app_inst_req structure - * \param[in] Package identifier + * \param[in] p_req Pointer handling app_inst_req structure + * \param[in] pkg_id Package identifier * \return API return code or error code */ int security_manager_app_inst_req_set_pkg_id(app_inst_req *p_req, const char *pkg_id); -/* +/** * This function is used to add privilege to app_inst_req structure, * it can be called multiple times * - * \param[in] Pointer handling app_inst_req structure - * \param[in] Application privilager + * \param[in] p_req Pointer handling app_inst_req structure + * \param[in] privilege Application privilager * \return API return code or error code */ int security_manager_app_inst_req_add_privilege(app_inst_req *p_req, const char *privilege); -/* +/** * This function is used to add application path to app_inst_req structure, * it can be called multiple times * - * \param[in] Pointer handling app_inst_req structure - * \param[in] Application path - * \param[in] Application path type + * \param[in] p_req Pointer handling app_inst_req structure + * \param[in] path Application path + * \param[in] path_type Application path type * \return API return code or error code */ int security_manager_app_inst_req_add_path(app_inst_req *p_req, const char *path, const int path_type); -/* +/** * This function is used to set up user identifier in app_inst_req structure. * This field simplifies support for online and offline modes. * - * \param[in] Pointer handling app_inst_req structure - * \param[in] User identifier (UID) + * \param[in] p_req Pointer handling app_inst_req structure + * \param[in] uid User identifier (UID) * \return API return code or error code */ int security_manager_app_inst_req_set_uid(app_inst_req *p_req, const uid_t uid); -/* +/** * This function is used to set up author identifier in app_inst_req structure. * This field is required for trusted paths only (SECURITY_MANAGER_PATH_TRUSTED_RW). * - * \param[in] Pointer handling app_inst_req structure - * \param[in] Author's identifier + * \param[in] p_req Pointer handling app_inst_req structure + * \param[in] author_id Author's identifier * \return API return code or error code */ int security_manager_app_inst_req_set_author_id(app_inst_req *p_req, const char *author_id); -/* +/** * This function is used to set up installation type (global, local, preloaded). * If type is not set and if installation is performed by global user, type is set to * 'SM_APP_INSTALL_GLOBAL'. Otherwise installation type is set to 'SM_APP_INSTALL_LOCAL'. * - * \param[in] Pointer handling app_inst_req structure - * \param[in] Installation type + * \param[in] p_req Pointer handling app_inst_req structure + * \param[in] type Installation type * \return API return code or error code * */ int security_manager_app_inst_req_set_install_type(app_inst_req *p_req, const enum app_install_type type); -/* +/** * This function is used to install application based on * using filled up app_inst_req data structure * @@ -132,7 +133,7 @@ int security_manager_app_inst_req_set_install_type(app_inst_req *p_req, const en * - http://tizen.org/privilege/notexist (global installation) * - http://tizen.org/privilege/internal/usermanagement (local installation for other users) * - * \param[in] Pointer handling app_inst_req structure + * \param[in] p_req Pointer handling app_inst_req structure * \return API return code or error code: it would be * - SECURITY_MANAGER_SUCCESS on success, * - SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED when user does not @@ -141,7 +142,7 @@ int security_manager_app_inst_req_set_install_type(app_inst_req *p_req, const en */ int security_manager_app_install(const app_inst_req *p_req); -/* +/** * This function is used to uninstall application based on * using filled up app_inst_req data structure * @@ -150,12 +151,12 @@ int security_manager_app_install(const app_inst_req *p_req); * - http://tizen.org/privilege/notexist (global uninstallation) * - http://tizen.org/privilege/internal/usermanagement (local uninstallation for other users) * - * \param[in] Pointer handling app_inst_req structure + * \param[in] p_req Pointer handling app_inst_req structure * \return API return code or error code */ int security_manager_app_uninstall(const app_inst_req *p_req); -/* +/** * This function is responsible for initialize path_req data structure. It uses * dynamic allocation inside and user responsibility is to call * security_manager_path_req_free() for freeing allocated resources. @@ -165,14 +166,14 @@ int security_manager_app_uninstall(const app_inst_req *p_req); */ int security_manager_path_req_new(path_req **pp_req); -/* +/** * This function is used to free resources allocated by calling * security_manager_path_req_new(). * \param[in] p_req Pointer handling allocated path_req structure */ void security_manager_path_req_free(path_req *p_req); -/* +/** * This function is used to set up package identifier in path_req structure. * * \param[in] p_req Pointer handling path_req structure @@ -181,7 +182,7 @@ void security_manager_path_req_free(path_req *p_req); */ int security_manager_path_req_set_pkg_id(path_req *p_req, const char *pkg_id); -/* +/** * This function is used to set up installation type (global, local, preloaded). * If type is not set and if installation is performed by global user, type is set to * 'SM_APP_INSTALL_GLOBAL'. Otherwise installation type is set to 'SM_APP_INSTALL_LOCAL'. @@ -192,7 +193,7 @@ int security_manager_path_req_set_pkg_id(path_req *p_req, const char *pkg_id); */ int security_manager_path_req_set_install_type(path_req *p_req, const enum app_install_type type); -/* +/** * This function is used to add a package path to path_req structure. It can be * called multiple times. * @@ -203,7 +204,7 @@ int security_manager_path_req_set_install_type(path_req *p_req, const enum app_i */ int security_manager_path_req_add_path(path_req *p_req, const char *path, const int path_type); -/* +/** * This function is used to set up user identifier in path_req structure. * This field simplifies support for online and offline modes. * @@ -213,7 +214,7 @@ int security_manager_path_req_add_path(path_req *p_req, const char *path, const */ int security_manager_path_req_set_uid(path_req *p_req, const uid_t uid); -/* +/** * This function is used to register a set of paths for given package using * filled up path_req data structure. * diff --git a/src/include/app-runtime.h b/src/include/app-runtime.h index 6e8e949..8ace21c 100644 --- a/src/include/app-runtime.h +++ b/src/include/app-runtime.h @@ -31,8 +31,8 @@ extern "C" { * * On successful call pkg_id should be freed by the caller using free() function * - * \param[out] Pointer to package identifier string - * \param[in] Application identifier + * \param[out] pkg_id Pointer to package identifier string + * \param[in] app_id Application identifier * \return API return code or error code */ int security_manager_get_app_pkgid(char **pkg_id, const char *app_id); @@ -41,7 +41,7 @@ int security_manager_get_app_pkgid(char **pkg_id, const char *app_id); * Compute smack label for given application id and set it for * currently running process * - * \param[in] Application identifier + * \param[in] app_id Application identifier * \return API return code or error code */ int security_manager_set_process_label_from_appid(const char *app_id); @@ -57,7 +57,7 @@ int security_manager_set_process_label_from_appid(const char *app_id); * adding application process to all permitted groups that are assigned to such * privileges. * - * \param[in] Application identifier + * \param[in] app_id Application identifier * \return API return code or error code */ int security_manager_set_process_groups_from_appid(const char *app_id); @@ -84,7 +84,7 @@ int security_manager_drop_process_privileges(void); * - security_manager_set_process_groups_from_appid * - security_manager_drop_process_privileges * - * \param[in] Application identifier + * \param[in] app_id Application identifier * \return API return code or error code */ int security_manager_prepare_app(const char *app_id); @@ -120,9 +120,9 @@ void security_manager_groups_free(char **groups, size_t groups_count); * When socket descriptor is incorrect or not related to any package, this function will * return SECURITY_MANAGER_ERROR_NO_SUCH_OBJECT. * - * \param[in] Socket descriptor of wanted application - * \param[out] package id of the application - * \param[out] application id of the application + * \param[in] sockfd Socket descriptor of wanted application + * \param[out] pkg_id Package id of the application + * \param[out] app_id Application id of the application * \return API return code or error code */ int security_manager_identify_app_from_socket(int sockfd, char **pkg_id, char **app_id); @@ -140,9 +140,9 @@ int security_manager_identify_app_from_socket(int sockfd, char **pkg_id, char ** * \note Caller must be able to access and read file /proc/PID/atrr/current where PID is the given * process identifier. * - * \param[in] process identifier of wanted application - * \param[out] package id of the application - * \param[out] application id of the application + * \param[in] pid Process identifier of wanted application + * \param[out] pkg_id Package id of the application + * \param[out] app_id Application id of the application * \return API return code or error code */ int security_manager_identify_app_from_pid(pid_t pid, char **pkg_id, char **app_id); @@ -154,15 +154,15 @@ int security_manager_identify_app_from_pid(pid_t pid, char **pkg_id, char **app_ * process running. In such case the application label cannot be determined from * the process and the query for privilege must be based on app_id. * - * The check result is placed in \ref result: + * The check result is placed in \b result: * - 0: access denied * - 1: access granted * - * @param[in] app_id application identifier - * @param[in] privilege name - * @param[in] uid user identifier - * @param[out] result placeholder for result - * @return API return code or error code + * \param[in] app_id Application identifier + * \param[in] privilege Privilege name + * \param[in] uid User identifier + * \param[out] result Placeholder for result + * \return API return code or error code */ int security_manager_app_has_privilege(const char *app_id, const char *privilege, uid_t uid, int *result); diff --git a/src/include/app-sharing.h b/src/include/app-sharing.h index ad510e7..4bc61d4 100644 --- a/src/include/app-sharing.h +++ b/src/include/app-sharing.h @@ -26,29 +26,29 @@ extern "C" { #endif -/* +/** * This function is responsible for initialize private_sharing_req data structure * It uses dynamic allocation inside and user responsibility is to call * private_sharing_req_free() for freeing allocated resources * - * \param[out] Address of pointer for handle private_sharing_req structure + * \param[out] pp_req Address of pointer for handle private_sharing_req structure * \return API return code or error code */ int security_manager_private_sharing_req_new(private_sharing_req **pp_req); -/* +/** * This function is used to free resources allocated by calling private_sharing_req_new() * - * \param[in] Pointer handling allocated app_inst_req structure + * \param[in] p_req Pointer handling allocated app_inst_req structure */ void security_manager_private_sharing_req_free(private_sharing_req *p_req); -/* +/** * This function is used to set up package identifier of paths owner application * in private_sharing_req structure * - * \param[in] Pointer handling private_sharing_req structure - * \param[in] Application identifier + * \param[in] p_req Pointer handling private_sharing_req structure + * \param[in] app_id Application identifier * \return API return code or error code: it would be * - SECURITY_MANAGER_SUCCESS on success, * - SECURITY_MANAGER_ERROR_REQ_NOT_COMPLETE when either owner app_id, target app_id @@ -58,37 +58,37 @@ void security_manager_private_sharing_req_free(private_sharing_req *p_req); int security_manager_private_sharing_req_set_owner_appid(private_sharing_req *p_req, const char *app_id); -/* +/** * This function is used to set up package identifier of sharing target application * in private_sharing_req structure * - * \param[in] Pointer handling private_sharing_req structure - * \param[in] Application identifier + * \param[in] p_req Pointer handling private_sharing_req structure + * \param[in] app_id Application identifier * \return API return code or error code */ int security_manager_private_sharing_req_set_target_appid(private_sharing_req *p_req, const char *app_id); -/* +/** * This function is used to add path list to be shared in private_sharing_req structure * - * \param[in] Pointer handling private_sharing_req structure - * \param[in] Path list - * \param[in] Path count + * \param[in] p_req Pointer handling private_sharing_req structure + * \param[in] pp_paths Path list + * \param[in] path_count Path count * \return API return code or error code */ int security_manager_private_sharing_req_add_paths(private_sharing_req *p_req, const char **pp_paths, size_t path_count); -/* +/** * This function is used to apply private sharing based on given private_sharing_req. * One path can be shared with multiple applications at the same time. * * Required privileges: * - http://tizen.org/privilege/notexist * - * \param[in] Pointer handling private_sharing_req structure + * \param[in] p_req Pointer handling private_sharing_req structure * \return API return code or error code: it would be * - SECURITY_MANAGER_SUCCESS on success, * - SECURITY_MANAGER_ERROR_INPUT_PARAM when either owner app_id, target app_id or paths are not set, @@ -96,13 +96,13 @@ int security_manager_private_sharing_req_add_paths(private_sharing_req *p_req, */ int security_manager_private_sharing_apply(const private_sharing_req *p_req); -/* +/** * This function is used to drop private sharing based on given private_sharing_req. * * Required privileges: * - http://tizen.org/privilege/notexist * - * \param[in] Pointer handling private_sharing_req structure + * \param[in] p_req Pointer handling private_sharing_req structure * \return API return code or error code: it would be * - SECURITY_MANAGER_SUCCESS on success, * - SECURITY_MANAGER_ERROR_REQ_NOT_COMPLETE when either owner app_id, target app_id diff --git a/src/include/label-monitor.h b/src/include/label-monitor.h index 2637eab..71ac426 100644 --- a/src/include/label-monitor.h +++ b/src/include/label-monitor.h @@ -73,6 +73,7 @@ typedef struct app_labels_monitor app_labels_monitor; * security_manager_app_labels_monitor_finish(monitor); * * \endcode + * \endparblock */ int security_manager_app_labels_monitor_init(app_labels_monitor **monitor); diff --git a/src/include/policy-manager.h b/src/include/policy-manager.h index 98a0587..972e476 100644 --- a/src/include/policy-manager.h +++ b/src/include/policy-manager.h @@ -262,6 +262,8 @@ const char *security_manager_policy_entry_get_max_level(policy_entry *p_entry); * deny access from app MyApp2 to privilege http://tizen.org/privilege/systemsettings, * deny access from app MyApp3 to privilege http://tizen.org/privilege/notificationmanager) * + * \parblock + * \code{.c} * policy_update_req *policy_update_request; * policy_entry *entry1; * policy_entry *entry2; @@ -296,15 +298,19 @@ const char *security_manager_policy_entry_get_max_level(policy_entry *p_entry); * security_manager_policy_entry_free(entry2); * security_manager_policy_entry_free(entry3); * security_manager_policy_update_free(policy_update_request); + * \endcode + * \endparblock * * - to update policy by administrator for some user: * (Deny access of user of uid 2001 from any app to privilege http://tizen.org/privilege/vibrator, * (allow access of user of uid 2002 using app "App1" to privilege http://tizen.org/privilege/email.admin) * + * \parblock + * \code{.c} * policy_update_req *policy_update_request; * * security_manager_policy_update_req_new(&policy_update_request); - + * * policy_entry *entry1; * policy_entry *entry2; * char *adminswife = "2001"; @@ -333,6 +339,8 @@ const char *security_manager_policy_entry_get_max_level(policy_entry *p_entry); * security_manager_policy_entry_free(entry1); * security_manager_policy_entry_free(entry2); * security_manager_policy_update_free(policy_update_request); + * \endcode + * \endparblock * */ int security_manager_policy_update_send(policy_update_req *p_req); @@ -414,9 +422,9 @@ void security_manager_policy_entries_free(policy_entry *p_entries, const size_t * Caller needs to free memory allocated for the list using * security_manager_policy_levels_free(). * - * @param levels pointer to array of strings. - * @param levels_count number of strings in levels array. - * @return API return code or error code. + * \param levels Pointer to array of strings + * \param levels_count Number of strings in levels array + * \return API return code or error code. */ int security_manager_policy_levels_get(char ***levels, size_t *levels_count); @@ -424,9 +432,10 @@ int security_manager_policy_levels_get(char ***levels, size_t *levels_count); * This function free memory allocated by security_manager_policy_levels_get() * function. * - * @param levels array of strings returned by - * security_manager_policy_levels_get() function. - * @return API return code or error code. + * \param levels Array of strings returned by + * security_manager_policy_levels_get() function. + * \param levels_count Number of strings in levels array + * \return API return code or error code. */ void security_manager_policy_levels_free(char **levels, size_t levels_count); diff --git a/src/include/user-manager.h b/src/include/user-manager.h index 69dc38e..d1851fd 100644 --- a/src/include/user-manager.h +++ b/src/include/user-manager.h @@ -26,43 +26,43 @@ extern "C" { #endif -/* +/** * This function is responsible for initialization of user_req data structure. * It uses dynamic allocation inside and user responsibility is to call * security_manager_user_req_free() for freeing allocated resources. * - * @param[in] Address of pointer for handle user_req structure - * @return API return code or error code + * \param[in] pp_req Address of pointer for handle user_req structure + * \return API return code or error code */ int security_manager_user_req_new(user_req **pp_req); -/* +/** * This function is used to free resources allocated by * security_manager_user_req_new() * - * @param[in] Pointer handling allocated user_req structure + * \param[in] p_req Pointer handling allocated user_req structure */ void security_manager_user_req_free(user_req *p_req); -/* +/** * This function is used to set up user identifier in user_req structure. * - * @param p_req Structure containing user data filled during this function call - * @param uid User identifier to be set - * @return API return code or error code + * \param p_req Structure containing user data filled during this function call + * \param uid User identifier to be set + * \return API return code or error code */ int security_manager_user_req_set_uid(user_req *p_req, uid_t uid); -/* +/** * This function is used to set up user type in user_req structure. * - * @param p_req Structure containing user data filled during this function call - * @param utype User type to be set - * @return API return code or error code + * \param p_req Structure containing user data filled during this function call + * \param utype User type to be set + * \return API return code or error code */ int security_manager_user_req_set_user_type(user_req *p_req, security_manager_user_type utype); -/* +/** * This function should be called to inform security-manager about adding new user. * This function succeeds only when is called by privileged user. * Otherwise it just returns SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED and does nothing. @@ -72,14 +72,15 @@ int security_manager_user_req_set_user_type(user_req *p_req, security_manager_us * * It adds all required privileges to a newly created user. * User data are passed through pointer 'p_req'. - * @param p_req Structure containing user data filled before calling this - * uid and user type needs to be filled in p_req structure, - * otherwise SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned. - * @return API return code or error code. + * + * \param p_req Structure containing user data filled before calling this + * uid and user type needs to be filled in p_req structure, + * otherwise SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned. + * \return API return code or error code. */ int security_manager_user_add(const user_req *p_req); -/* +/** * This function should be called to inform security-manager about removing a user. * This function succeeds only when is called by privileged user. * Otherwise it just returns SECURITY_MANAGER_ERROR_AUTHENTICATION_FAILED and does nothing. @@ -90,10 +91,10 @@ int security_manager_user_add(const user_req *p_req); * It removes all privileges granted to a user that has been granted previously by * security_manager_user_add. * - * @param p_req Structure containing user data filled before calling this. - * uid of user needs to be filled in p_req structure, - * otherwise SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned. - * @return API return code or error code + * \param p_req Structure containing user data filled before calling this. + * uid of user needs to be filled in p_req structure, + * otherwise SECURITY_MANAGER_ERROR_INPUT_PARAM will be returned. + * \return API return code or error code */ int security_manager_user_delete(const user_req *p_req); -- 2.7.4