From e7306d30a93b0cd00ab26f1ccbf5ef706eea7a72 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?=
 <manuel.pegourie-gonnard@arm.com>
Date: Thu, 13 Dec 2018 09:45:49 +0100
Subject: [PATCH] Improve some documentation and ChangeLog entry

---
 ChangeLog                     | 12 ++++++++----
 include/mbedtls/config.h      |  9 +++++++++
 tests/suites/helpers.function |  2 +-
 3 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index a4f3ae54e..d4e754b71 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -23,10 +23,14 @@ Security
      modules.
 
 Features
-   * Add new config.h flag MBEDTLS_CHECK_PARAMS that enables validation of
-     more of the parameters by public API functions (see its documentation in
-     config.h for details). Disabled by default - requires users to provide an
-     implementation of the callback function or macro.
+   * Add a new config.h option of MBEDTLS_CHECK_PARAMS that enables additional
+     validation of parameters in the library's public interface. This does not
+     change the API of existing functions, but additional clarity has been
+     added to the defined documentation interface to make clearer what the
+     interface is designed to accept. See the corresponding API documentation
+     for each function to see what parameter values are defined as invalid.
+     This feature is disabled by default. See its API documentation in
+     config.h for additional steps you have to take when enabling it.
 
 New deprecations
    * Deprecate mbedtls_ctr_drbg_update and mbedtls_hmac_drbg_update
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 4663481b2..73b5dce13 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -292,6 +292,9 @@
  *   calls that function, but does not provide a default definition for it,
  * - or provide a different definition of the macro MBEDTLS_PARAM_FAILED()
  *   below if the above mechanism is not flexible enough to suit your needs.
+ *   Note that you may define it to expand to nothing if you're happy to be
+ *   notified about invalid parameters only in non-void functions, and have
+ *   void function just silently return early on invalid parameters.
  *
  * Uncomment to enable validation of application-controlled parameters.
  */
@@ -3055,6 +3058,12 @@
  *              from within the library - you can ensure that by providing
  *              them in this file next to the macro definition).
  *
+ *              Note that you may define this macro to expand to nothing, in
+ *              which case you don't have to worry about declarations or
+ *              definitions. However, you will then be notified about invalid
+ *              parameters only in non-void functions, and void function will
+ *              just silently return early on invalid parameters.
+ *
  * \param cond  The expression that should evaluate to true, but doesn't.
  */
 //#define MBEDTLS_PARAM_FAILED( cond )               assert( cond )
diff --git a/tests/suites/helpers.function b/tests/suites/helpers.function
index 891fba6ee..3aa5cd6d0 100644
--- a/tests/suites/helpers.function
+++ b/tests/suites/helpers.function
@@ -199,7 +199,7 @@ typedef enum
  *          Note: this macro is available even when #MBEDTLS_CHECK_PARAMS is
  *          disabled, as it makes sense to check that the functions accept all
  *          legal values even if this option is disabled - only in that case,
- *          the test if more about whether the function segfaults than about
+ *          the test is more about whether the function segfaults than about
  *          whether it invokes MBEDTLS_PARAM_FAILED().
  *
  * \param   TEST                The test expression to be tested.