From ed459e6995a5d3bebfd17c01f24eb5c7f6f814e1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?=
 <manuel.pegourie-gonnard@arm.com>
Date: Wed, 12 Dec 2018 10:20:33 +0100
Subject: [PATCH] Fix content and style of constraints documentation

- Be specific about the constraints: be a readable/writable buffer of length
  X, be an initialized context, be a context initialized and bound to a key...
- Always use full sentences with all the required pronouns.
---
 include/mbedtls/aes.h | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index 97c009802..11edc0fab 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -121,14 +121,16 @@ typedef struct mbedtls_aes_xts_context
  *                 It must be the first API called before using
  *                 the context.
  *
- * \param ctx      The AES context to initialize. Must not be \c NULL.
+ * \param ctx      The AES context to initialize. This must not be \c NULL.
  */
 void mbedtls_aes_init( mbedtls_aes_context *ctx );
 
 /**
  * \brief          This function releases and clears the specified AES context.
  *
- * \param ctx      The AES context to clear. If \c NULL, no action is taken.
+ * \param ctx      The AES context to clear.
+ *                 If this is \c NULL, this function does nothing.
+ *                 Otherwise, the context must have been at least initialized.
  */
 void mbedtls_aes_free( mbedtls_aes_context *ctx );
 
@@ -139,14 +141,16 @@ void mbedtls_aes_free( mbedtls_aes_context *ctx );
  *                 It must be the first API called before using
  *                 the context.
  *
- * \param ctx      The AES XTS context to initialize. Must not be \c NULL.
+ * \param ctx      The AES XTS context to initialize. This must not be \c NULL.
  */
 void mbedtls_aes_xts_init( mbedtls_aes_xts_context *ctx );
 
 /**
  * \brief          This function releases and clears the specified AES XTS context.
  *
- * \param ctx      The AES XTS context to clear. If \c NULL, no action is taken.
+ * \param ctx      The AES XTS context to clear.
+ *                 If this is \c NULL, this function does nothing.
+ *                 Otherwise, the context must have been at least initialized.
  */
 void mbedtls_aes_xts_free( mbedtls_aes_xts_context *ctx );
 #endif /* MBEDTLS_CIPHER_MODE_XTS */
@@ -154,9 +158,10 @@ void mbedtls_aes_xts_free( mbedtls_aes_xts_context *ctx );
 /**
  * \brief          This function sets the encryption key.
  *
- * \param ctx      The AES context to which the key should be bound. Must not
- *                 be \c NULL.
- * \param key      The encryption key. Must not be \c NULL.
+ * \param ctx      The AES context to which the key should be bound.
+ *                 It must be initialized.
+ * \param key      The encryption key.
+ *                 This must be a readable buffer of size \p keybits bits.
  * \param keybits  The size of data passed in bits. Valid options are:
  *                 <ul><li>128 bits</li>
  *                 <li>192 bits</li>
@@ -171,9 +176,10 @@ int mbedtls_aes_setkey_enc( mbedtls_aes_context *ctx, const unsigned char *key,
 /**
  * \brief          This function sets the decryption key.
  *
- * \param ctx      The AES context to which the key should be bound. Must not
- *                 be \c NULL.
- * \param key      The decryption key. Must not be \c NULL.
+ * \param ctx      The AES context to which the key should be bound.
+ *                 It must be initialized.
+ * \param key      The decryption key.
+ *                 This must be a readable buffer of size \p keybits bits.
  * \param keybits  The size of data passed. Valid options are:
  *                 <ul><li>128 bits</li>
  *                 <li>192 bits</li>