Improve docs for Weaver HAL.
Test: None, only changed docs
Change-Id: Icd0c20986b1ec885a400960f7fad262b7a2e869b
diff --git a/weaver/1.0/IWeaver.hal b/weaver/1.0/IWeaver.hal
index 2362c29..e572123 100644
--- a/weaver/1.0/IWeaver.hal
+++ b/weaver/1.0/IWeaver.hal
@@ -16,7 +16,7 @@
package android.hardware.weaver@1.0;
/**
- * Weaver provides secure storage of secret values that can only be read if the
+ * Weaver provides secure storage of secret values that may only be read if the
* corresponding key has been presented.
*
* The storage must be secure as the device's user authentication and encryption
@@ -58,20 +58,21 @@
* The value is only returned if the provided key matches the key stored in
* the slot. The value is never returned if the wrong key is provided.
*
- * Throttling is used to limit the frequency of failed read attempts. The
- * value is only returned when throttling is not active, even if the correct
- * key is provided. If called when throttling is active, the time until the
- * next attempt can be made is returned.
+ * Throttling must be used to limit the frequency of failed read attempts.
+ * The value is only returned when throttling is not active, even if the
+ * correct key is provided. If called when throttling is active, the time
+ * until the next attempt can be made is returned.
*
* @param slotId of the slot to read from.
* @param key that is stored in the slot.
* @return status is OK if the value was successfully read, INCORRECT_KEY if
- * the key does not match the key in the slot or THROTTLE if
- * throttling is active.
+ * the key does not match the key in the slot, THROTTLE if
+ * throttling is active or FAILED if the read was unsuccessful for
+ * another reason.
* @return readResponse contains the value read and the timeout to wait
- * before making the next request. The value is undefined if the
- * status is not OK and the timeout is undefined if the status is
- * FAILED.
+ * before making the next request. If the status is OK, value is set
+ * to the value in the slot and timeout is 0. Otherwise, value is
+ * empty and timeout is set accordingly.
*/
read(uint32_t slotId, vec<uint8_t> key)
generates (WeaverReadStatus status,