Improve docs for Weaver HAL.

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

     * 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,