From cd2b29cd12673de3f02f0dbda1e0ac0e21fad1b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Wed, 12 Dec 2018 10:23:57 +0100 Subject: [PATCH] Improve wording in documentation and ChangeLog --- ChangeLog | 4 ++-- include/mbedtls/config.h | 15 ++++++++------- tests/suites/helpers.function | 4 ++-- 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/ChangeLog b/ChangeLog index 9d51378d1..a4f3ae54e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -24,8 +24,8 @@ Security Features * Add new config.h flag MBEDTLS_CHECK_PARAMS that enables validation of - more of the parameters by public API functions (see its documentation for - details). Disabled by default - requires users to provide an + 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. New deprecations diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index a4ab9cb79..4663481b2 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -259,11 +259,11 @@ /** * \def MBEDTLS_CHECK_PARAMS * - * This configuration controls whether the library validates more of the - * parameters passed to it. + * This configuration option controls whether the library validates more of + * the parameters passed to it. * - * When this flag is not defined, the library only attempts to validate input - * parameter if: (1) they may come from the outside world (such as the + * When this flag is not defined, the library only attempts to validate an + * input parameter if: (1) they may come from the outside world (such as the * network, the filesystem, etc.) or (2) not validating them could result in * internal memory errors such as overflowing a buffer controlled by the * library. On the other hand, it doesn't attempt to validate parameters whose @@ -273,7 +273,7 @@ * parameters that are fully controlled by the application, and should always * be valid if the application code is fully correct and trusted. * - * For example, when a function accepts a input a pointer to a buffer than may + * For example, when a function accepts as input a pointer to a buffer that may * contain untrusted data, and its documentation mentions that this pointer * must not be NULL: * - the pointer is checked to be non-NULL only if this option is enabled @@ -291,7 +291,7 @@ * your application (see platform_util.h for its prototype) as the library * 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 enough flexible to suit your needs. + * below if the above mechanism is not flexible enough to suit your needs. * * Uncomment to enable validation of application-controlled parameters. */ @@ -3052,7 +3052,8 @@ * function mbedtls_param_failed()) and it is your responsibility * to make sure this macro expands to something suitable (in * particular, that all the necessary declarations are visible - * from within the library). + * from within the library - you can ensure that by providing + * them in this file next to the macro definition). * * \param cond The expression that should evaluate to true, but doesn't. */ diff --git a/tests/suites/helpers.function b/tests/suites/helpers.function index 9aecbb1bb..c77231df9 100644 --- a/tests/suites/helpers.function +++ b/tests/suites/helpers.function @@ -185,10 +185,10 @@ typedef enum * expected failure. If MBEDTLS_CHECK_PARAMS is not enabled, no test * can be made. * - * This macro is intended to test that function that return void + * This macro is intended to test that functions returning void * accept all of the parameter values they're supposed to accept - eg * that they don't call MBEDTLS_PARAM_FAILED() when a parameter - * that's allowed to be NULL happends to be NULL. + * that's allowed to be NULL happens to be NULL. * * Note: for functions that return something other that void, * checking that they accept all the parameters they're supposed to