Update documentation for psa_close_key
Adjust the wording to permit multiple handles to a single key - closing
a handle does not necessarily release volatile memory associated with
the key, that only occurs when the last handle is closed.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index e067cbd..8aa11ce 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -400,15 +400,19 @@
/** Close a key handle.
*
- * If the handle designates a volatile key, destroy the key material and
- * free all associated resources, just like psa_destroy_key().
+ * If the handle designates a volatile key, this will destroy the key material
+ * and free all associated resources, just like psa_destroy_key().
*
- * If the handle designates a persistent key, free all resources associated
- * with the key in volatile memory. The key in persistent storage is
- * not affected and can be opened again later with psa_open_key().
+ * If this is the last open handle to a persistent key, then closing the handle
+ * will free all resources associated with the key in volatile memory. The key
+ * data in persistent storage is not affected and can be opened again later
+ * with a call to psa_open_key().
*
- * If the key is currently in use in a multipart operation,
- * the multipart operation is aborted.
+ * Closing the key handle makes the handle invalid, and the key handle
+ * must not be used again by the application..
+ *
+ * If the key is currently in use in a multipart operation, then closing the
+ * last handle to the key will abort the multipart operation.
*
* \param handle The key handle to close.
*
