power: Add detailed description to power lock API usage

device_power_request_lock() follows below rule

1. If the same application requests the same power lock more than twice before it is released or expired,
   the timeout will be updated to the latest requested time.

2. If different applications request the same power lock type,
   the power state timeout will be set to the maximum of the requested timeouts.

Above rule and scenario explanations are added.

Change-Id: Ieb4467ab2cfd93a1efac9f3730e4a91b836600e7
Signed-off-by: Yunhee Seo <yuni.seo@samsung.com>

diff --git a/include/power.h b/include/power.h
index 53c46e2bb857c6ef5d7fe845b0c06fd2d3cb981f..aa53c801bbe17c7e0ad7b6aace8099ff8f583b64 100644 (file)
--- a/include/power.h
+++ b/include/power.h
@@ -59,6 +59,22 @@ typedef enum {
 /**
  * @brief Locks the given specific power lock type for a specified time.
  * @details After the given @a timeout_ms (in milliseconds), unlock the given lock state automatically.
+ * Scenario 1. If the same application requests the same power lock more than twice before it is released or expired, \n
+ * the timeout will be updated to the latest requested time. \n
+ * For example:
+ *     The first request has a timeout of 5000ms. \n
+ *     The second request has a timeout of 1000ms. \n
+ *     If the second request is made before the first request is released or expired, \n
+ *     the timeout will be updated to the latest requested time, which is 1000ms.
+ *
+ * Scenario 2. If different applications request the same power lock type, \n
+ * the power state timeout will be set to the maximum of the requested timeouts. \n
+ * For example:
+ *     Application A requests POWER_LOCK_CPU with a timeout of 5000ms. \n
+ *     Application B requests the same POWER_LOCK_CPU with a timeout of 1000ms. \n
+ *     Unless Application A releases the POWER_LOCK_CPU lock, \n
+ *     the timeout for POWER_LOCK_CPU will remain at the maximum requested time, which is 5000ms.
+ *
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/display