Added/updated description in PolicyManager and UsageStatistics classes for policy external

2 files changed, 115 insertions, 53 deletions

diff --git a/src/components/include/policy/policy_external/policy/policy_manager.h b/src/components/include/policy/policy_external/policy/policy_manager.h
index 335e9e9425..adf195e3a9 100644
--- a/src/components/include/policy/policy_external/policy/policy_manager.h
+++ b/src/components/include/policy/policy_external/policy/policy_manager.h
@@ -59,12 +59,17 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   enum NotificationMode { kSilentMode, kNotifyApplicationMode };
   virtual ~PolicyManager() {}
 
+  /**
+   * @brief set_listener set new policy listener instance
+   * @param listener new policy listener
+   */
   virtual void set_listener(PolicyListener* listener) = 0;
 
   /**
-   * Inits Policy Table
-   * @param file_name Path to preloaded PT file
-   * @return true if successfully
+   * @brief Inits Policy Table
+   * @param file_name path to preloaded PT file
+   * @param settings pointer to policy init settings
+   * @return true if init is successful
    */
   virtual bool InitPT(const std::string& file_name,
                       const PolicySettings* settings) = 0;
@@ -75,26 +80,30 @@ class PolicyManager : public usage_statistics::StatisticsManager {
    * sent in snapshot and received Policy Table.
    * @param file name of file with update policy table
    * @param pt_content PTU as binary string
-   * @return bool Success of operation
+   * @return true if successfully
    */
   virtual bool LoadPT(const std::string& file,
                       const BinaryMessage& pt_content) = 0;
 
   /**
-   * Resets Policy Table
+   * @brief Resets Policy Table
    * @param file_name Path to preloaded PT file
    * @return true if successfully
    */
   virtual bool ResetPT(const std::string& file_name) = 0;
 
+  /**
+   * @brief Gets last URL for sending PTS to from PT itself
+   * @param service_type Service specifies user of URL
+   * @return last URL or empty string if endpoint entry is empty
+   */
   virtual std::string GetUpdateUrl(int service_type) = 0;
 
   /**
- * @brief Gets all URLs for sending PTS to from PT itself.
- * @param service_type Service specifies user of URL
- * @return vector of urls
- */
-
+   * @brief Gets all URLs for sending PTS to from PT itself.
+   * @param service_type Service specifies user of URL
+   * @return vector of urls
+   */
   virtual void GetUpdateUrls(const uint32_t service_type,
                              EndpointUrls& out_end_points) = 0;
   virtual void GetUpdateUrls(const std::string& service_type,
@@ -102,7 +111,6 @@ class PolicyManager : public usage_statistics::StatisticsManager {
 
   /**
    * @brief GetLockScreenIcon allows to obtain lock screen icon url;
-   *
    * @return url which point to the resourse where lock screen icon could be
    *obtained.
    */
@@ -120,6 +128,7 @@ class PolicyManager : public usage_statistics::StatisticsManager {
    * @param app_id Id of application provided during registration
    * @param hmi_level Current HMI Level of application
    * @param rpc Name of RPC
+   * @param rpc_params List of RPC params
    * @param CheckPermissionResult containing flag if HMI Level is allowed
    * and list of allowed params.
    */
@@ -142,41 +151,43 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   virtual std::string GetPolicyTableStatus() const = 0;
 
   /**
-   * Checks is PT exceeded kilometers
+   * @brief Checks is PT exceeded kilometers
    * @param kilometers current kilometers at odometer
    * @return true if exceeded
    */
   virtual void KmsChanged(int kilometers) = 0;
 
   /**
-   * Increments counter of ignition cycles
+   * @brief Increments counter of ignition cycles
    */
   virtual void IncrementIgnitionCycles() = 0;
 
   /**
    * @brief Exchange by hmi or mobile request
+   * @return Current status of policy table
    */
   virtual std::string ForcePTExchange() = 0;
 
   /**
-   * @brief ExchangeByUserRequest
+   * @brief Exchange by user request
+   * @return Current status of policy table
    */
   virtual std::string ForcePTExchangeAtUserRequest() = 0;
 
   /**
-   * Resets retry sequence
+   * @brief Resets retry sequence
    */
   virtual void ResetRetrySequence() = 0;
 
   /**
-   * Gets timeout to wait before next retry updating PT
+   * @brief Gets timeout to wait before next retry updating PT
    * If timeout is less or equal to zero then the retry sequence is not need.
    * @return timeout in seconds
    */
   virtual int NextRetryTimeout() = 0;
 
   /**
-   * Gets timeout to wait until receive response
+   * @brief Gets timeout to wait until receive response
    * @return timeout in seconds
    */
   virtual uint32_t TimeoutExchangeMSec() = 0;
@@ -189,7 +200,7 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   virtual const std::vector<int> RetrySequenceDelaysSeconds() = 0;
 
   /**
-   * Handler of exceeding timeout of exchanging policy table
+   * @brief Handler of exceeding timeout of exchanging policy table
    */
   virtual void OnExceededTimeout() = 0;
 
@@ -228,21 +239,24 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   /**
    * @brief Update Application Policies as reaction
    * on User allowing/disallowing device this app is running on.
+   * @param app_id Unique application id
+   * @param is_device_allowed true if user allowing device otherwise false
+   * @return true if operation was successful
    */
   virtual bool ReactOnUserDevConsentForApp(const std::string& app_id,
                                            const bool is_device_allowed) = 0;
 
   /**
-   * Sets counter value that passed for receiving PT UPdate.
+   * @brief Sets counter value that passed for receiving PT UPdate.
    */
   virtual void PTUpdatedAt(Counters counter, int value) = 0;
 
   /**
    * @brief Retrieves data from app_policies about app on its registration:
-   * @param app_id - id of registered app
-   * @param app_types Section on HMI where app can appear (Navigation, Phone
-   * etc)
+   * @param application_id - id of registered app
    * @param nicknames Synonyms for application
+   * @param app_hmi_types Section on HMI where app can appear (Navigation, Phone
+   * etc)
    */
   virtual bool GetInitialAppData(const std::string& application_id,
                                  StringArray* nicknames = NULL,
@@ -271,6 +285,7 @@ class PolicyManager : public usage_statistics::StatisticsManager {
    * The permissions is not const reference because it may contains
    * valid data as well as invalid. So we will remove all invalid data
    * from this structure.
+   * @param mode notification mode
    */
   virtual void SetUserConsentForApp(const PermissionConsent& permissions,
                                     const NotificationMode mode) = 0;
@@ -298,6 +313,7 @@ class PolicyManager : public usage_statistics::StatisticsManager {
    * @brief Get user friendly messages for given RPC messages and language
    * @param message_codes RPC message codes
    * @param language Language
+   * @param active_hmi_language Currently active language
    * @return Array of structs with appropriate message parameters
    */
   virtual std::vector<UserFriendlyMessage> GetUserFriendlyMessages(
@@ -306,7 +322,7 @@ class PolicyManager : public usage_statistics::StatisticsManager {
       const std::string& active_hmi_language) = 0;
 
   /**
-   * Checks if the application is revoked
+   * @brief Checks if the application is revoked
    * @param app_id application id
    * @return true if application is revoked
    */
@@ -333,11 +349,15 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   virtual AppPermissions GetAppPermissionsChanges(
       const std::string& policy_app_id) = 0;
 
+  /**
+   * @brief Removes specific application permissions changes
+   * @param app_id Unique application id
+   */
   virtual void RemovePendingPermissionChanges(const std::string& app_id) = 0;
 
   /**
    * @brief Return device id, which hosts specific application
-   * @param Application id, which is required to update device id
+   * @param policy_app_id Application id, which is required to update device id
    */
   virtual std::string& GetCurrentDeviceId(
       const std::string& policy_app_id) const = 0;
@@ -360,13 +380,13 @@ class PolicyManager : public usage_statistics::StatisticsManager {
 
   /**
    * @brief Send OnPermissionsUpdated for choosen application
-   * @param application_id
+   * @param application_id Unique application id
    */
   virtual void SendNotificationOnPermissionsUpdated(
       const std::string& application_id) = 0;
 
   /**
-   * Marks device as upaired
+   * @brief Marks device as upaired
    * @param device_id id device
    */
   virtual void MarkUnpairedDevice(const std::string& device_id) = 0;
@@ -374,7 +394,8 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   /**
    * @brief Adds, application to the db or update existed one
    * run PTU if policy update is necessary for application.
-   * @param Application id assigned by Ford to the application
+   * @param application_id Unique application id
+   * @param hmi_types application HMI types
    * @return function that will notify update manager about new application
    */
   virtual StatusNotifier AddApplication(
@@ -383,18 +404,21 @@ class PolicyManager : public usage_statistics::StatisticsManager {
 
   /**
    * @brief Removes unpaired device records and related records from DB
-   * @param device_ids List of device_id, which should be removed
    * @return true, if succedeed, otherwise - false
    */
   virtual bool CleanupUnpairedDevices() = 0;
 
   /**
    * @brief Check if app can keep context.
+   * @param app_id Unique application id
+   * @return true if app can keep context, otherwise - false
    */
   virtual bool CanAppKeepContext(const std::string& app_id) const = 0;
 
   /**
    * @brief Check if app can steal focus.
+   * @param app_id Unique application id
+   * @return true if app can steal focus, otherwise - false
    */
   virtual bool CanAppStealFocus(const std::string& app_id) const = 0;
 
@@ -406,9 +430,9 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   virtual void OnSystemReady() = 0;
 
   /**
-   * @brief GetNotificationNumber
-   * @param priority
-   * @return
+   * @brief Get number of notification by priority
+   * @param priority Specified priority
+   * @return notification number
    */
   virtual uint32_t GetNotificationsNumber(
       const std::string& priority) const = 0;
@@ -427,7 +451,7 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   virtual bool IsPredataPolicy(const std::string& policy_app_id) const = 0;
 
   /**
-   * Returns heart beat timeout
+   * @brief Returns heart beat timeout
    * @param app_id application id
    * @return if timeout was set then value in milliseconds greater zero
    * otherwise heart beat for specific application isn't set
@@ -435,7 +459,8 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   virtual uint32_t HeartBeatTimeout(const std::string& app_id) const = 0;
 
   /**
-   * @brief SaveUpdateStatusRequired alows to save update status.
+   * @brief SaveUpdateStatusRequired allows to save update status.
+   * @param is_update_needed true if update needed
    */
   virtual void SaveUpdateStatusRequired(bool is_update_needed) = 0;
 
@@ -446,14 +471,14 @@ class PolicyManager : public usage_statistics::StatisticsManager {
 
   /**
    * @brief Handler on applications search completed
+   * @param trigger_ptu contains true if PTU should be triggered
    */
   virtual void OnAppsSearchCompleted(const bool trigger_ptu) = 0;
 
   /**
    * @brief OnAppRegisteredOnMobile allows to handle event when application were
    * succesfully registered on mobile device.
-   * It will send OnAppPermissionSend notification and will try to start PTU.
-   *
+   * It will send OnAppPermissionSend notification and will try to start PTU. *
    * @param application_id registered application.
    */
   virtual void OnAppRegisteredOnMobile(const std::string& application_id) = 0;
@@ -461,13 +486,14 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   /**
    * @brief Gets request types for application
    * @param policy_app_id Unique application id
-   * @return request_types Request types of application
+   * @return request types of application
    */
   virtual const std::vector<std::string> GetAppRequestTypes(
       const std::string policy_app_id) const = 0;
 
   /**
    * @brief Get information about vehicle
+   * @return vehicle information
    */
   virtual const VehicleInfo GetVehicleInfo() const = 0;
 
@@ -480,7 +506,6 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   /**
    * @brief RetrieveCertificate Allows to obtain certificate in order
    * to start secure connection.
-   *
    * @return The certificate in PKCS#7 format.
    */
   virtual std::string RetrieveCertificate() const = 0;
@@ -488,7 +513,6 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   /**
    * @brief HasCertificate check whether policy table has certificate
    * int module_config section.
-   *
    * @return true in case certificate exists, false otherwise
    */
   virtual bool HasCertificate() const = 0;
@@ -499,6 +523,10 @@ class PolicyManager : public usage_statistics::StatisticsManager {
    */
   virtual void SetDecryptedCertificate(const std::string& certificate) = 0;
 
+  /**
+   * @brief Getter for policy settings
+   * @return policy settings instance
+   */
   virtual const PolicySettings& get_settings() const = 0;
 
   /**
@@ -510,10 +538,15 @@ class PolicyManager : public usage_statistics::StatisticsManager {
   virtual AppIdURL GetNextUpdateUrl(const EndpointUrls& urls) = 0;
 
 #ifdef SDL_REMOTE_CONTROL
+  /**
+   * @brief Assigns new HMI types for specified application
+   * @param application_id Unique application id
+   * @param hmi_types new HMI types list
+   */
   virtual void SetDefaultHmiTypes(const std::string& application_id,
                                   const std::vector<int>& hmi_types) = 0;
   /**
-   * Gets HMI types
+   * @brief Gets HMI types
    * @param application_id ID application
    * @param app_types list to save HMI types
    * @return true if policy has specific policy for this application
@@ -522,15 +555,15 @@ class PolicyManager : public usage_statistics::StatisticsManager {
                            std::vector<int>* app_types) = 0;
 
   /**
-   * Checks if module for application is present in policy table
+   * @brief Checks if module for application is present in policy table
    * @param app_id id of application
    * @param module type
    * @return true if module is present, otherwise - false
    */
   virtual bool CheckModule(const PTString& app_id, const PTString& module) = 0;
 
-  /*
-   * Send OnPermissionsChange notification to mobile app
+  /**
+   * @brief Send OnPermissionsChange notification to mobile app
    * when it's permissions are changed.
    * @param device_id Device on which app is running
    * @param application_id ID of app whose permissions are changed
@@ -539,14 +572,18 @@ class PolicyManager : public usage_statistics::StatisticsManager {
                                          const std::string& application_id) = 0;
 
   /**
-    * Gets all allowed module types
-    * @param app_id unique identifier of application
-    * @param list of allowed module types
+    * @brief Gets all allowed module types
+    * @param policy_app_id unique identifier of application
+    * @param modules list of allowed module types
     * @return true if application has allowed modules
     */
   virtual bool GetModuleTypes(const std::string& policy_app_id,
                               std::vector<std::string>* modules) const = 0;
 
+  /**
+   * @brief Setter for access_remote instance
+   * @param access_remote pointer to new access_remote instance
+   */
   virtual void set_access_remote(
       utils::SharedPtr<AccessRemote> access_remote) = 0;
 #endif  // SDL_REMOTE_CONTROL
@@ -564,11 +601,11 @@ class PolicyManager : public usage_statistics::StatisticsManager {
                                     const EndpointUrls& urls) const = 0;
 
   /**
-  * @brief Checks, if SDL needs to update it's policy table "external consent
-  * status" section
-  * @param status ExternalConsent status
-  * @return true if there's such a need, otherwise - false
-  */
+   * @brief  Checks, if SDL needs to update it's policy table section
+             "external_consent_status"
+   * @param  ExternalConsent status
+   * @return true if such check is needed, false - if not.
+   */
   virtual bool IsNeedToUpdateExternalConsentStatus(
       const ExternalConsentStatus& status) const = 0;
 
@@ -582,19 +619,19 @@ class PolicyManager : public usage_statistics::StatisticsManager {
 
   /**
    * @brief Gets customer connectivity settings status
-   * @return external consent status
+   * @return ExternalConsent status
    */
   virtual ExternalConsentStatus GetExternalConsentStatus() = 0;
 
  protected:
   /**
-   * Checks is PT exceeded IgnitionCycles
+   * @brief Checks is PT exceeded IgnitionCycles
    * @return true if exceeded
    */
   virtual bool ExceededIgnitionCycles() = 0;
 
   /**
-   * Checks is PT exceeded days
+   * @brief Checks is PT exceeded days
    * @return true if exceeded
    */
   virtual bool ExceededDays() = 0;
diff --git a/src/components/include/policy/policy_external/policy/usage_statistics/statistics_manager.h b/src/components/include/policy/policy_external/policy/usage_statistics/statistics_manager.h
index dac553b547..7186400ff4 100644
--- a/src/components/include/policy/policy_external/policy/usage_statistics/statistics_manager.h
+++ b/src/components/include/policy/policy_external/policy/usage_statistics/statistics_manager.h
@@ -71,11 +71,36 @@ enum AppCounterId {
 class StatisticsManager {
  public:
   virtual ~StatisticsManager() {}
+
+  /**
+   * @brief Increments global counter
+   * @param type counter type
+   */
   virtual void Increment(GlobalCounterId type) = 0;
+
+  /**
+   * @brief Increments specified application counter
+   * @param app_id Unique ID of application
+   * @param type application counter type
+   */
   virtual void Increment(const std::string& app_id, AppCounterId type) = 0;
+
+  /**
+   * @brief Sets specified application info value
+   * @param app_id Unique ID of application
+   * @param type application info type
+   * @param value new value for counter
+   */
   virtual void Set(const std::string& app_id,
                    AppInfoId type,
                    const std::string& value) = 0;
+
+  /**
+   * @brief Add seconds for specified application stopwatch
+   * @param app_id Unique ID of application
+   * @param type application stopwatch type
+   * @param timespan_seconds seconds to add
+   */
   virtual void Add(const std::string& app_id,
                    AppStopwatchId type,
                    int32_t timespan_seconds) = 0;