Add description

Change-Id: I48162088e865aa4ade9e7ca09c0ea01e43addea1
Signed-off-by: Kazumasa Mitsunari <knimitz@witz-inc.co.jp>

2 files changed, 185 insertions, 23 deletions

diff --git a/src/applist.cpp b/src/applist.cpp
index 365c485..4e0dc11 100644
--- a/src/applist.cpp
+++ b/src/applist.cpp
@@ -28,6 +28,14 @@ namespace wm
 const static int kReserveClientSize = 100;
 const static int kReserveReqSize    = 10;
 
+/**
+ * AppList Constructor.
+ *
+ * Reserve the container size to avoid re-allocating memory.
+ *
+ * @note Size should be changed according to the system.
+ *       If the number of applications becomes over the size, re-allocating memory will happen.
+ */
 AppList::AppList()
     : req_list(),
       app2client(),
@@ -39,14 +47,24 @@ AppList::AppList()
 
 AppList::~AppList() {}
 
-void AppList::addClient(const string &appid, const string &role)
-{
-    std::lock_guard<std::mutex> lock(mtx);
-    shared_ptr<WMClient> client = std::make_shared<WMClient>(appid, role);
-    this->app2client[appid] = client;
-    this->clientDump();
-}
+// =================== Client Date container API ===================
 
+/**
+ * Add Client to the list
+ *
+ * Add Client to the list.
+ * The Client means application which has role, layer, surface
+ * This function should be called once for the app.
+ * Caller should take care not to be called more than once.
+ *
+ * @param     string[in]   Application id. This will be the key to withdraw the information.
+ * @param     unsigned[in] Layer ID in which the application is
+ * @param     unsigned[in] surface ID which the application has
+ * @param     string[in]   Role which means what behavior the application will do.
+ * @return    None
+ * @attention This function should be called once for the app
+ *            Caller should take care not to be called more than once.
+ */
 void AppList::addClient(const std::string &appid, unsigned layer, unsigned surface, const std::string &role)
 {
     std::lock_guard<std::mutex> lock(mtx);
@@ -55,6 +73,11 @@ void AppList::addClient(const std::string &appid, unsigned layer, unsigned surfa
     this->clientDump();
 }
 
+/**
+ * Remove WMClient from the list
+ *
+ * @param string[in] Application id. This will be the key to withdraw the information.
+ */
 void AppList::removeClient(const string &appid)
 {
     std::lock_guard<std::mutex> lock(mtx);
@@ -62,6 +85,12 @@ void AppList::removeClient(const string &appid)
     HMI_INFO("wm", "Remove client %s", appid.c_str());
 }
 
+/**
+ * Check this class stores the appid.
+ *
+ * @param     string[in] Application id. This will be the key to withdraw the information.
+ * @return    true if the class has the requested key(appid)
+ */
 bool AppList::contains(const string &appid) const
 {
     auto result = this->app2client.find(appid);
@@ -84,26 +113,64 @@ void AppList::removeSurface(unsigned surface_id){
 }
 
 /**
- * @brief  get WMClient object. Before call this function, must call "contains"
+ * Get WMClient object.
+ *
+ * After get the WMClient object, caller can call the client method.
+ * Before call this function, caller must call "contains"
  * to check the key is contained, otherwise, you have to take care of std::out_of_range.
- * @param string[in] application id(key)
- * @return WMClient object
+ *
+ * @param     string[in] application id(key)
+ * @return    WMClient object
+ * @attention Must call cantains to check appid is stored before this function.
  */
 shared_ptr<WMClient> AppList::lookUpClient(const string &appid)
 {
     return this->app2client.at(appid);
 }
 
+/**
+ * Count Client.
+ *
+ * Returns the number of client stored in the list.
+ *
+ * @param     string[in] application id(key)
+ * @return    WMClient object
+ * @attention Must call cantains to check appid is stored before this function.
+ */
 int AppList::countClient() const
 {
     return this->app2client.size();
 }
 
+// =================== Request Date container API ===================
+
+/**
+ * Get current request number
+ *
+ * Request number is the numeric ID to designate the request.
+ * But returned request number from this function doesn't mean the request exists.
+ * This number is used as key to withdraw the WMRequest object.
+ *
+ * @param  None
+ * @return current request number.
+ * @note   request number is more than 0.
+ */
 unsigned AppList::currentRequestNumber() const
 {
     return this->current_req;
 }
 
+/**
+ * Get request number
+ *
+ * Request number is the numeric ID to designate the request.
+ * But returned request number from this function doesn't mean the request exists.
+ * This number is used as key to withdraw the WMRequest object.
+ *
+ * @param     None
+ * @return    request number.
+ * @attention If returned value is 0, no request exists.
+ */
 unsigned AppList::getRequestNumber(const string &appid) const
 {
     for (const auto &x : this->req_list)
@@ -117,6 +184,18 @@ unsigned AppList::getRequestNumber(const string &appid) const
     return 0;
 }
 
+/**
+ * Add Request
+ *
+ * Request number is the numeric ID to designate the request.
+ * But returned request number from this function doesn't mean the request exists.
+ * This number is used as key to withdraw the WMRequest object.
+ *
+ * @param     WMRequest[in] WMRequest object caller creates
+ * @return    Request number
+ * @attention If the request number is different with curent request number,
+ *            it means the previous request is not finished.
+ */
 unsigned AppList::addAllocateRequest(WMRequest req)
 {
     std::lock_guard<std::mutex> lock(mtx);
@@ -133,6 +212,19 @@ unsigned AppList::addAllocateRequest(WMRequest req)
     return req.req_num;
 }
 
+/**
+ * Get trigger which the application requests
+ *
+ * WMTrigger contains which application requests what role and where to put(area) and task.
+ * This is used for input event to Window Policy Manager(state machine).
+ *
+ * @param     unsigned[in] request number
+ * @param     bool[in,out] Check request number of the parameter is valid.
+ * @return    WMTrigger which associates with the request number
+ * @attention If the request number is not valid, parameter "found" is false
+ *            and return value will be meaningless value.
+ *            Caller can check the request parameter is valid.
+ */
 struct WMTrigger AppList::getRequest(unsigned req_num, bool *found)
 {
     *found = false;
@@ -148,6 +240,20 @@ struct WMTrigger AppList::getRequest(unsigned req_num, bool *found)
     return WMTrigger{"", "", "", Task::TASK_INVALID};
 }
 
+/**
+ * Get actions which the application requests
+ *
+ * WMAciton contains the information of state transition.
+ * In other words, it contains actions of Window Manager,
+ * which role should be put to the area.
+ *
+ * @param     unsigned[in] request number
+ * @param     bool[in,out] Check request number of the parameter is valid.
+ * @return    WMTrigger which associates with the request number
+ * @attention If the request number is not valid, parameter "found" is false
+ *            and return value will be no reference pointer.
+ *            Caller must check the request parameter is valid.
+ */
 const vector<struct WMAction> &AppList::getActions(unsigned req_num, bool* found)
 {
     *found = false;
@@ -162,6 +268,18 @@ const vector<struct WMAction> &AppList::getActions(unsigned req_num, bool* found
     HMI_SEQ_ERROR(req_num, "Couldn't get action with the request : %d", req_num);
 }
 
+/**
+ * Set actions to the request.
+ *
+ * Add actions to the request.
+ * This function can be called many times, and actions increase.
+ * This function is used for decision of actions of Window Manager
+ * according to the result of Window Policy Manager.
+ *
+ * @param     unsigned[in] request number
+ * @param     WMAction[in] Action of Window Manager.
+ * @return    WMError If request number is not valid, FAIL will be returned.
+ */
 WMError AppList::setAction(unsigned req_num, const struct WMAction &action)
 {
     std::lock_guard<std::mutex> lock(mtx);
@@ -181,15 +299,32 @@ WMError AppList::setAction(unsigned req_num, const struct WMAction &action)
 
 /**
  * Note:
- * This function set action with parameters.
- * if visible is true, it means app should be visible, so enddraw_finished parameter should be false.
- * otherwise (visible is false) app should be invisible. Then enddraw_finished param is set to true.
- * This function doesn't support actions for focus yet.
+ * @note This function set action with parameters.
+ *       If visible is true, it means app should be visible, so enddraw_finished parameter should be false.
+ *       otherwise (visible is false) app should be invisible. Then enddraw_finished param is set to true.
+ *       This function doesn't support actions for focus yet.
+ */
+/**
+ * Set actions to the request.
+ *
+ * This function is overload function.
+ * The feature is same as other one.
+ *
+ * @param     unsigned[in] request number
+ * @param     string[in]   application id
+ * @param     string[in]   role
+ * @param     string[in]   area
+ * @param     bool[in]     the role should be visible or not.
+ * @return    WMError If request number is not valid, FAIL will be returned.
+ * @attention This function set action with parameters, then caller doesn't need to create WMAction object.
+ *            If visible is true, it means app should be visible, so enddraw_finished parameter will be false.
+ *            otherwise (visible is false) app should be invisible. Then enddraw_finished param is set to true.
+ *            This function doesn't support actions for focus yet.
  */
 WMError AppList::setAction(unsigned req_num, const string &appid, const string &role, const string &area, bool visible)
 {
     std::lock_guard<std::mutex> lock(mtx);
-    WMError result = WMError::NOT_REGISTERED;
+    WMError result = WMError::FAIL;
     for (auto &x : req_list)
     {
         if (req_num != x.req_num)
@@ -207,9 +342,17 @@ WMError AppList::setAction(unsigned req_num, const string &appid, const string &
 }
 
 /**
+ * Set end_draw_finished param is true
+ *
  * This function checks
- *   * req_num is equal to current request number
- *   * appid and role are equeal to the appid and role stored in action list(sync_draw_req)
+ *   - req_num is equal to current request number
+ *   - appid and role are equeal to the appid and role stored in action list
+ * If it is valid, set the action is finished.
+ *
+ * @param  unsigned[in] request number
+ * @param  string[in]   application id
+ * @param  string[in]   role
+ * @return If the parameters are not valid in action list, returns false
  */
 bool AppList::setEndDrawFinished(unsigned req_num, const string &appid, const string &role)
 {
@@ -238,8 +381,9 @@ bool AppList::setEndDrawFinished(unsigned req_num, const string &appid, const st
 }
 
 /**
- * @brief  check all actions of the requested sequence is finished
- * @param  unsigned request_number
+ * Check all actions of the requested sequence is finished
+ *
+ * @param  unsigned[in] request_number
  * @return true if all action is set.
  */
 bool AppList::endDrawFullfilled(unsigned req_num)
@@ -267,6 +411,13 @@ bool AppList::endDrawFullfilled(unsigned req_num)
     return result;
 }
 
+/**
+ * Finish the request, then remove it.
+ *
+ * @param  unsigned[in] request_number
+ * @return None
+ * @note   Please call next after this function to receive or process next request.
+ */
 void AppList::removeRequest(unsigned req_num)
 {
     std::lock_guard<std::mutex> lock(mtx);
@@ -276,6 +427,12 @@ void AppList::removeRequest(unsigned req_num)
                                    }));
 }
 
+/**
+ * Move the current request to next
+ *
+ * @param  None
+ * @return None
+ */
 void AppList::next()
 {
     std::lock_guard<std::mutex> lock(mtx);
@@ -286,6 +443,12 @@ void AppList::next()
     }
 }
 
+/**
+ * Check the request exists is in request list
+ *
+ * @param  None
+ * @return true if WMRequest exists in the request list
+ */
 bool AppList::haveRequest() const
 {
     return !this->req_list.empty();
diff --git a/src/applist.hpp b/src/applist.hpp
index c0cc298..59f37ba 100644
--- a/src/applist.hpp
+++ b/src/applist.hpp
@@ -39,7 +39,9 @@ class AppList
     AppList(const AppList &obj) = delete;
 
     // Client Database Interface
-    void addClient(const std::string &appid, const std::string &role);
+    /* TODO: consider, which is better WMClient as parameter?
+       If the WMClient should be more flexible, I think this param should be WMClient class
+    */
     void addClient(const std::string &appid, unsigned layer, unsigned surface, const std::string &role);
     void removeClient(const std::string &appid);
     bool contains(const std::string &appid) const;
@@ -51,9 +53,6 @@ class AppList
     unsigned currentRequestNumber() const;
     unsigned getRequestNumber(const std::string &appid) const;
     unsigned addAllocateRequest(WMRequest req);
-    /* TODO: consider, which is better WMClient or std::string appid?
-    if appid is key to manage resources, it is better to select std::string
-    otherwise WMClient is better, IMO */
     WMError setAction(unsigned req_num, const struct WMAction &action);
     WMError setAction(unsigned req_num, const std::string &appid, const std::string &role, const std::string &area, bool visible = true);
     bool setEndDrawFinished(unsigned req_num, const std::string &appid, const std::string &role);