Improve and fix documentation for error code combination
Improve documentation by:
- Fixing off by one errors in binary representations of error codes.
- Clarifying combinations of zero.
- Linking references to variables/macros via doxygen.
Signed-off-by: Chris Jones <christopher.jones@arm.com>
diff --git a/include/mbedtls/error.h b/include/mbedtls/error.h
index 39874b9..6242289 100644
--- a/include/mbedtls/error.h
+++ b/include/mbedtls/error.h
@@ -133,10 +133,14 @@
* \brief Combines a high-level and low-level error code together.
*
* This function can be called directly however it is usually
- * called via the mbedtls_error_add macro.
+ * called via the #MBEDTLS_ERROR_ADD macro.
*
- * \note When invasive testing is enabled via MBEDTLS_TEST_HOOKS also try to
- * call mbedtls_test_hook_error_add.
+ * While a value of zero is not a negative error code, it is still an
+ * error code (that denotes success) and can be combined with both a
+ * negative error code or another value of zero.
+ *
+ * \note When invasive testing is enabled via #MBEDTLS_TEST_HOOKS, also try to
+ * call \link mbedtls_test_hook_error_add \endlink.
*
* \param high high-level error code. See error.h for more details.
* \param low low-level error code. See error.h for more details.
diff --git a/tests/src/helpers.c b/tests/src/helpers.c
index 9c1198e..b546611 100644
--- a/tests/src/helpers.c
+++ b/tests/src/helpers.c
@@ -292,7 +292,7 @@
* examples given in comments have been made positive for ease of
* understanding. The structure of an error code is such:
*
- * shhhhhhhllllllll
+ * shhhhhhhhlllllll
*
* s = sign bit.
* h = high level error code (includes high and module error codes).
@@ -308,7 +308,7 @@
mbedtls_test_fail( "'high' error code is greater than 15 bits",
line, file );
}
- else if ( ( high & 0x7F ) != 0 ) // high & 0000000011111111
+ else if ( ( high & 0x7F ) != 0 ) // high & 0000000001111111
{
mbedtls_test_fail( "'high' contains a low-level error code",
line, file );