From f1b7694768048f653179ece50234c08204927bf6 Mon Sep 17 00:00:00 2001
From: Gilles Peskine <Gilles.Peskine@arm.com>
Date: Thu, 16 May 2019 16:10:59 +0200
Subject: [PATCH] Minor documentation improvements

---
 include/psa/crypto.h | 27 ++++++++++++++++-----------
 1 file changed, 16 insertions(+), 11 deletions(-)

diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index 0d0de2e0a..e43a301a0 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -208,14 +208,15 @@ typedef struct psa_key_attributes_s psa_key_attributes_t;
 
 /** Declare a key as persistent and set its key identifier.
  *
- * If the attribute structure declares the key as volatile (which is
- * the default content of an attribute structure), this function sets
+ * If the attribute structure currently declares the key as volatile (which
+ * is the default content of an attribute structure), this function sets
  * the lifetime attribute to #PSA_KEY_LIFETIME_PERSISTENT.
  *
- * This function does not access storage, it merely fills the attribute
- * structure with given value. The persistent key will be written to
- * storage when the attribute structure is passed to a key creation
- * function such as psa_import_key(), psa_generate_random_key(),
+ * This function does not access storage, it merely stores the given
+ * value in the structure.
+ * The persistent key will be written to storage when the attribute
+ * structure is passed to a key creation function such as
+ * psa_import_key(), psa_generate_random_key(),
  * psa_generate_derived_key() or psa_copy_key().
  *
  * This function may be declared as `static` (i.e. without external
@@ -231,12 +232,16 @@ static void psa_set_key_id(psa_key_attributes_t *attributes,
 /** Set the location of a persistent key.
  *
  * To make a key persistent, you must give it a persistent key identifier
- * with psa_set_key_id().
+ * with psa_set_key_id(). By default, a key that has a persistent identifier
+ * is stored in the default storage area identifier by
+ * #PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage
+ * area, or to explicitly declare the key as volatile.
  *
- * This function does not access storage, it merely fills the attribute
- * structure with given value. The persistent key will be written to
- * storage when the attribute structure is passed to a key creation
- * function such as psa_import_key(), psa_generate_random_key(),
+ * This function does not access storage, it merely stores the given
+ * value in the structure.
+ * The persistent key will be written to storage when the attribute
+ * structure is passed to a key creation function such as
+ * psa_import_key(), psa_generate_random_key(),
  * psa_generate_derived_key() or psa_copy_key().
  *
  * This function may be declared as `static` (i.e. without external