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: Ic0f7a435496913caeee6ae64fee3dc3223e545b0
Signed-off-by: Yunhee Seo <yuni.seo@samsung.com>

diff --git a/include/power.h b/include/power.h
index f049bf95834b5d326ea6b996413ff3c9cb34fccf..7549aa76b3d8333f6a6c1e20577d58b726b22ea4 100644 (file)
--- a/include/power.h
+++ b/include/power.h
@@ -59,6 +59,22 @@ typedef enum {
 /**
  * @brief Locks the given lock state 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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  * @privlevel public
  * @privilege %http://tizen.org/privilege/display