diff --git a/include/mbedtls/aes.h b/include/mbedtls/aes.h
index b5560cc81..6044a51aa 100644
--- a/include/mbedtls/aes.h
+++ b/include/mbedtls/aes.h
@@ -287,9 +287,7 @@ int mbedtls_internal_aes_decrypt( mbedtls_aes_context *ctx,
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief           Internal AES block encryption function
- *                  (Only exposed to allow overriding it,
- *                  see MBEDTLS_AES_ENCRYPT_ALT)
+ * \brief           Old AES block encryption function without return value.
  *
  * \deprecated      Superseded by mbedtls_aes_encrypt_ext() in 2.5.0
  *
@@ -306,9 +304,7 @@ MBEDTLS_DEPRECATED static inline void mbedtls_aes_encrypt(
 }
 
 /**
- * \brief           Internal AES block decryption function
- *                  (Only exposed to allow overriding it,
- *                  see MBEDTLS_AES_DECRYPT_ALT)
+ * \brief           Old AES block decryption function without return value.
  *
  * \deprecated      Superseded by mbedtls_aes_decrypt_ext() in 2.5.0
  *
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index c4b8995c1..2a2209a35 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -273,9 +273,15 @@
  * of mbedtls_sha1_context, so your implementation of mbedtls_sha1_process must be compatible
  * with this definition.
  *
- * Note: if you use the AES_xxx_ALT macros, then is is recommended to also set
- * MBEDTLS_AES_ROM_TABLES in order to help the linker garbage-collect the AES
- * tables.
+ * \note Because of a signature change, the core AES encryption and decryption routines are
+ *       currently named mbedtls_aes_internal_encrypt and mbedtls_aes_internal_decrypt,
+ *       respectively. When setting up alternative implementations, these functions should
+ *       be overriden, but the wrapper functions mbedtls_aes_decrypt and mbedtls_aes_encrypt
+ *       have to stay untouched.
+ *
+ * \note If you use the AES_xxx_ALT macros, then is is recommended to also set
+ *       MBEDTLS_AES_ROM_TABLES in order to help the linker garbage-collect the AES
+ *       tables.
  *
  * Uncomment a macro to enable alternate implementation of the corresponding
  * function.