Improve some documentation and ChangeLog entry
diff --git a/ChangeLog b/ChangeLog
index a4f3ae5..d4e754b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -23,10 +23,14 @@
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 4663481..73b5dce 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 891fba6..3aa5cd6 100644
--- a/tests/suites/helpers.function
+++ b/tests/suites/helpers.function
@@ -199,7 +199,7 @@
* 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.
