Fix doxygen documentation for CAPI

Change-Id: I65e4d19deab4f4e04710770050e1db6f65ce0f5c

diff --git a/src/capi/doc/privacy_privilege_manager_doc.h b/src/capi/doc/privacy_privilege_manager_doc.h
index c8c8229..db0d340 100644 (file)
--- a/src/capi/doc/privacy_privilege_manager_doc.h
+++ b/src/capi/doc/privacy_privilege_manager_doc.h
@@ -20,16 +20,16 @@
 
 /**
  * @ingroup CAPI_SECURITY_FRAMEWORK
- * @defgroup CAPI_PRIVACY_PRIVILEGE_MANAGER_MODULE
+ * @defgroup CAPI_PRIVACY_PRIVILEGE_MANAGER_MODULE Privacy Privilege Manager
  * @brief The Privacy Privilege Manager API provides functions for retrieving and
- * determining application's permissions to privacy privilege.
+ * determining application's permissions for privacy privileges.
  * @section CAPI_PRIVACY_PRIVILEGE_MANAGER_MODULE_HEADER Required Header
  *   \#include <privacy_privilege_manager.h>
  *
  * @section CAPI_PRIVACY_PRIVILEGE_MANAGER_MODULE_OVERVIEW Overview
- * This module allows to check if an application has permission to use a given privilege.
- * Moreover, it allows to determine a permission by displaying a UI dialog box (popup)
- * and requesting users's response.
+ * This library allows an application to check if it has permission to use a given
+ * privilege. Furthermore, it allows an application to determine permission by
+ * displaying a UI dialogue box (pop-up) and requesting a user response.
  */
 
 #endif /* __PRIVACY_PRIVILEGE_MANAGER_DOC_H__ */

diff --git a/src/capi/include/privacy_privilege_manager.h b/src/capi/include/privacy_privilege_manager.h
index 780a76a..a433a18 100644 (file)
--- a/src/capi/include/privacy_privilege_manager.h
+++ b/src/capi/include/privacy_privilege_manager.h
@@ -26,93 +26,72 @@ extern "C" {
 /**
  * @addtogroup CAPI_PRIVACY_PRIVILEGE_MANAGER_MODULE
  * @{
- * @brief
- * This is a Privacy Privilege Manager API of the Security framework.
- * @}
  */
 
 /**
- * @addtogroup CAPI_PRIVACY_PRIVILEGE_MANAGER_MODULE
- * @since_tizen 4.0
- * @{
- */
-
-/**
- * @brief    Enumerations of error code for Privacy Privilege Manager.
+ * @brief Enumeration of error codes for Privacy Privilege Manager.
  * @since_tizen 4.0
  */
 typedef enum
 {
-    /** Successful */
+    /**< Successful */
     PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE                 = TIZEN_ERROR_NONE,
-    /** I/O error */
+    /**< I/O error */
     PRIVACY_PRIVILEGE_MANAGER_ERROR_IO_ERROR             = TIZEN_ERROR_IO_ERROR,
-    /** Invalid parameter */
+    /**< Invalid parameter */
     PRIVACY_PRIVILEGE_MANAGER_ERROR_INVALID_PARAMETER    = TIZEN_ERROR_INVALID_PARAMETER,
-    /** Out of memory */
+    /**< Out of memory */
     PRIVACY_PRIVILEGE_MANAGER_ERROR_OUT_OF_MEMORY        = TIZEN_ERROR_OUT_OF_MEMORY,
-    /** Unknown error */
+    /**< Unknown error */
     PRIVACY_PRIVILEGE_MANAGER_ERROR_UNKNOWN              = TIZEN_ERROR_UNKNOWN,
 } ppm_error_e;
 
 /**
- * @brief    Enumerations of the result for privilege check function
+ * @brief Enumeration of privilege check results.
  * @since_tizen 4.0
  */
 typedef enum {
-    /** An application has a privilege. */
+    /**< An application has a privilege. */
     PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ALLOW,
-    /** An application doesn't have a privilege. */
+    /**< An application doesn't have a privilege. */
     PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_DENY,
-    /** A user should be asked whether grant a privilege to an application or not. */
+    /**< A user has to be asked whether grant a privilege to an application or not. */
     PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK,
 } ppm_check_result_e;
 
 /**
- * @brief    Enumerations of the user's decision result (popup).
+ * @brief Enumeration of user decision results for the pop-up resonse callback.
  * @since_tizen 4.0
  */
 typedef enum {
-    /** A user granted a privilege to an application for an indefinite period of time. */
+    /**< A user granted a privilege to an application for an indefinite period of time. */
     PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER,
-    /** A user did not grant a privilege to an application for an indefinite period of time. */
+    /**< A user did not grant a privilege to an application for an indefinite period of time. */
     PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER,
-    /** A user did not grant a privilege to an application once. */
+    /**< A user did not grant a privilege to an application once. */
     PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_ONCE,
 } ppm_popup_result_e;
 
 /**
- * @brief    Enumerations of the status code for popup response callback.
+ * @brief Enumeration of status codes for the pop-up response callback.
  * @since_tizen 4.0
  */
 typedef enum {
-    /** Callback was called with a valid answer. */
+    /**< Callback was called with a valid answer. */
     PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER,
-    /** Callback was called because of an error. */
+    /**< Callback was called because of an error. */
     PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ERROR,
 } ppm_call_cause_e;
 
 /**
- * @}
-*/
-
-
-/**
- * @addtogroup CAPI_PRIVACY_PRIVILEGE_MANAGER_MODULE
- * @{
- */
-
-/**
- * @brief This callback function is called when a client receives a response
- * upon calling ppm_popup_request().
+ * @brief Called when an application receives a response upon calling ppm_popup_request().
  *
  * @since_tizen 4.0
  *
  * @param[in]   cause       A value representing the reason why this callback
  *                          has been called.
- * @param[in]   result      It is a result of response to request created by
- *                          ppm_popup_request(). This should be interpreted as a
- *                          valid value only if cause is equal to
+ * @param[in]   result      A result of a response triggered by calling ppm_popup_request().
+ *                          This is a valid value only if the @a cause parameter is equal to
  *                          **PRIVACY_PRIVILEGE_MANAGER_CALL_CAUSE_ANSWER**.
  * @param[in]   user_data   User specific data, this parameter is passed
  *                          to ppm_popup_request().
@@ -124,14 +103,13 @@ typedef void (*ppm_popup_response_cb) (ppm_call_cause_e cause,
                                        void *user_data);
 
 /**
- * @brief This function is called to check if an application, which calls this API,
- * has permission to a given privilege.
- * @privlevel public
+ * @brief Checks if an application, which calls this API, has permission for a
+ * given privilege.
  *
- * @since 4.0
+ * @since_tizen 4.0
  *
- * @param[in]   privilege   Privilege that is to be checked.
- * @param[out]  result      The result of a privilege check.
+ * @param[in]   privilege   A privilege that is to be checked.
+ * @param[out]  result      A result of the privilege check.
  *
  * @return 0 on success, otherwise a negative error value
  * @retval #PRIVACY_PRIVILEGE_MANAGER_ERROR_NONE               Successful
@@ -143,37 +121,34 @@ typedef void (*ppm_popup_response_cb) (ppm_call_cause_e cause,
 int ppm_check_privilege(const char *privilege, ppm_check_result_e *result);
 
 /**
- * @brief This function is called to determine if an application needs to
- * request a user's response to determine a permission to a given privilege.
- *
- * @since 4.0
+ * @brief Requests a user's response to determine permission for a given privilege.
  *
- * @privlevel public
- * @details
- * When this function is called, the underlying service may show an appropriate
- * UI dialog box (popup) with a question. After user's decision, the service may
- * modify the privacy policy when it is a definitive decision. After that, the
- * service sends the response back to the application. The possible response
- * values are as follows:
- * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER, or
- * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER, or
+ * @details When this function is called, an underlying service may show an appropriate
+ * UI dialogue box (pop-up) with a question about granting the application access
+ * to a given privilege. Once a user makes a decision, the service may modify
+ * the privacy policy (when it is a definitive decision). After that, the service
+ * sends the response back to the application. The possible response values are as follows:
+ * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER or
+ * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER or
  * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_ONCE.
- * The application is informed about user's decision by invoking previously registered
- * ppm_popup_response_callback. When the policy for a given privilege is already
- * resolved, no popup will be shown and the service will return immediately with
- * an appropriate response:
+ * The application is informed about the user's decision by invoking previously
+ * registered ppm_popup_response_callback. When a privacy policy for the given privilege
+ * has already been resolved, no pop-up will be shown and the service will return
+ * a response immediately with an appropriate value:
  * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_ALLOW_FOREVER or
  * PRIVACY_PRIVILEGE_MANAGER_POPUP_RESULT_DENY_FOREVER.
  *
- * @remarks
- * If the result of calling ppm_check_privilege() is
- * **PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK**, the application should call
- * this function to determine whether a user allows an application to use
- * a particular privilege or not.
+ * @since_tizen 4.0
+ *
+ * @remarks Before calling this function, call ppm_check_privilege() to check
+ * permission for a given privilege. If a result of calling ppm_check_privilege() is
+ * **PRIVACY_PRIVILEGE_MANAGER_CHECK_RESULT_ASK**, an application should call
+ * this function to determine whether a user allows the application to use
+ * the privilege or not.
  *
  * @param[in]   privilege   A privilege for which a popup must be shown.
  * @param[in]   callback    A callback function which will be invoked
- *                          when the API receives user's response.
+ *                          when the API receives a pop-up response.
  * @param[in]   user_data   User specific data which will be passed to
  *                          the registered callback.
  *