From 5b4e077b6fccd7a7729c15cd63d5a68bb3af6985 Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Tue, 27 Apr 2021 12:47:43 -0400 Subject: [PATCH] Fix #963, improve documentation of UtAssert API calls The UtAssert API documentation was very terse and some references are obsolete/incorrect. This converts to doxygen form and corrects the stale/incorrect references. In particular - UtMemSet does not exist, but the standard C memset call should be used to fill a memory region with a constant value. --- ut_assert/inc/utassert.h | 173 +++++++++++++++++++++++++++++++-------- ut_assert/inc/uttools.h | 102 +++++++++++++++++++---- 2 files changed, 228 insertions(+), 47 deletions(-) diff --git a/ut_assert/inc/utassert.h b/ut_assert/inc/utassert.h index e583ef859..6f303fa83 100644 --- a/ut_assert/inc/utassert.h +++ b/ut_assert/inc/utassert.h @@ -83,61 +83,98 @@ typedef struct * Macro Definitions */ -/* A simplified UtAssert that uses the expression itself as the description */ +/** + * \brief A simplified UtAssert that uses the expression itself as the description + */ #define UtAssert_Simple(Expression) UtAssert(Expression, #Expression, __FILE__, __LINE__) -/* Evaluates a expression as either true or false. true means the test passed, false means the test failed. */ +/** + * \brief Evaluates a expression as either true or false. + * + * true means the test passed, false means the test failed. + */ #define UtAssert_True(Expression, ...) UtAssertEx(Expression, UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Evaluates a expression as either true or false. true means the test passed, false means the test failed. */ +/** + * \copydoc UtAssert_True + */ #define UtAssert_Bool(Expression, ...) UtAssertEx(Expression, UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Asserts a test failure */ +/** + * \brief Asserts a test failure + */ #define UtAssert_Failed(...) UtAssertEx(false, UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Assert a test Not Applicable */ +/** + * \brief Assert a test Not Applicable + */ #define UtAssert_NA(...) UtAssertEx(false, UTASSERT_CASETYPE_NA, __FILE__, __LINE__, __VA_ARGS__) -/* Compares two integers and determines if they are equal within a specified absolute tolerance. */ +/** + * \brief Compares two integers and determines if they are equal within a specified absolute tolerance. + */ #define UtAssert_IntegerCmpAbs(x, y, Tolerance, ...) \ UtAssertEx((abs((x) - (y)) <= (Tolerance)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Compares two floating point numbers and determines if they are equal within a specified absolute tolerance. */ +/** + * \brief Compares two floating point numbers and determines if they are equal within a specified absolute tolerance. + */ #define UtAssert_DoubleCmpAbs(x, y, Tolerance, ...) \ UtAssertEx((fabs((x) - (y)) <= (Tolerance)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Compares two floating point numbers and determines if they are equal within a specified relative tolerance. */ +/** + * \brief Compares two floating point numbers and determines if they are equal within a specified relative tolerance. + */ #define UtAssert_DoubleCmpRel(x, y, Ratio, ...) \ UtAssertEx((fabs((x) - (y)) / (x) <= (Ratio)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Compares two strings and determines if they are equal. */ +/** + * \brief Compares two strings and determines if they are equal. + */ #define UtAssert_StrCmp(String1, String2, ...) \ UtAssertEx((strcmp(String1, String2) == 0), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Compares at most Length characters of two strings and determines if they are equal. */ +/** + * \brief Compares at most Length characters of two strings and determines if they are equal. + */ #define UtAssert_StrnCmp(String1, String2, Length, ...) \ UtAssertEx((strncmp(String1, String2, Length) == 0), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Compares two regions of memory and determines if they are equal. */ +/** + * \brief Compares two regions of memory and determines if they are equal. + */ #define UtAssert_MemCmp(Memory1, Memory2, Length, ...) \ UtAssertEx((memcmp(Memory1, Memory2, Length) == 0), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Compares a region of memory to a static pattern and determines if they are equal. Note: Use UtMemSet to - * fill a region of memory with a static pattern. */ +/** + * \brief Compares a region of memory to a static pattern and determines if they are equal. + * + * \note Use standard memset() to fill a region of memory with a static pattern. + */ #define UtAssert_MemCmpValue(Memory, Value, Length, ...) \ UtAssertEx((UtMemCmpValue(Memory, Value, Length)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Compares a region of memory to a byte count pattern and determines if they are equal. Note: Use UtMemFill to - * fill a region of memory with a byte count pattern. */ +/** + * \brief Compares a region of memory to a byte count pattern and determines if they are equal. + * + * \note Use UtMemFill() to fill a region of memory with a byte count pattern. + * \sa UtMemFill + */ #define UtAssert_MemCmpCount(Memory, Length, ...) \ UtAssertEx((UtMemCmpCount(Memory, Length)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* Compares a region of memory with the contents of a binary file and determines if they are equal. Note: Use - * UtMem2BinFile to copy a region of memory to a binary file. */ +/** + * \brief Compares a region of memory with the contents of a binary file and determines if they are equal. + * + * \note Use UtMem2BinFile() to copy a region of memory to a binary file. + * \sa UtMem2BinFile + */ #define UtAssert_Mem2BinFileCmp(Memory, Filename, ...) \ UtAssertEx((UtMem2BinFileCmp(Memory, Filename)), UtAssert_GetContext(), __FILE__, __LINE__, __VA_ARGS__) -/* A wrapper around UtAssertEx that allows the user to specify the failure type and a more descriptive message */ +/** + * \brief A wrapper around UtAssertEx that allows the user to specify the failure type and a more descriptive message + */ #define UtAssert_Type(Type, Expression, ...) \ UtAssertEx(Expression, UTASSERT_CASETYPE_##Type, __FILE__, __LINE__, __VA_ARGS__) @@ -233,43 +270,113 @@ typedef struct * Exported Functions */ -/* Returns the number of asserts that have passed. */ +/** + * \brief Returns the number of asserts that have passed. + * + * \returns Number of tests that have passed + */ uint32 UtAssert_GetPassCount(void); -/* Returns the number of asserts that have failed. */ +/** + * \brief Returns the number of asserts that have failed. + * + * \returns Number of tests that have failed + */ uint32 UtAssert_GetFailCount(void); -/* Returns the full status of UtAssert counters */ +/** + * \brief Returns the full status of UtAssert counters + * + * \returns Pointer to structure with all the current test counter values + */ const UtAssert_TestCounter_t *UtAssert_GetCounters(void); -/* Begins a test Segment */ +/** + * \brief Begins a test Segment + * + * \param SegmentName the name of the test segment, for logging/output classification + */ void UtAssert_BeginTest(const char *SegmentName); -/* Completes a test Segment */ +/** + * \brief Completes a test Segment + * + * Segment name and counters will be printed to the console + */ void UtAssert_EndTest(void); -/* Sets the context of the current test, which is the default message type for UtAssert calls */ +/** + * \brief Sets the context of the current test, which is the default message type for UtAssert calls + * + * General assert statements for which do not directly specify a case type will inherit this case type + * if an assert fails. The framework automatically sets this to #UTASSERT_CASETYPE_TSF during setup + * and #UTASSERT_CASETYPE_TTF during teardown. + * + * \sa UtAssert_GetContext + * + * \param Context the case type to use for general assert failures + */ void UtAssert_SetContext(UtAssert_CaseType_t Context); -/* Sets the context of the current test, which is the default message type for UtAssert calls */ +/** + * \brief Sets the context of the current test, which is the default message type for UtAssert calls + * + * \sa UtAssert_SetContext + * + * \returns Case type that was set previously via UtAssert_SetContext + */ UtAssert_CaseType_t UtAssert_GetContext(void); -/* Sets the context of the current test, which is the default message type for UtAssert calls */ +/** + * \brief Gets the segment name of the current test + * + * This is the name that was previously set via UtAssert_BeginTest() + * + * \note the appliction should not store this pointer, it may become + * invalid after the next call to UtAssert_EndTest() + * + * \returns pointer to current segment name + */ const char *UtAssert_GetSegmentName(void); -/* Base assert function. All asserts must call this function. */ +/** + * \brief Base assert function + * + * This basic function is provided for backward compatibility with older + * versions of Ut Assert. It generates an assert case using the current + * default context. + * + * Users should preferentially use one of the more type-specific assert macros, + * if available. + * + * \param Expression a boolean value which evaluates "true" if the test passes + * \param Description a free form string describing the test case + * \param File The source file name in which the test case appears + * \param Line The source line number in which the test case appears + */ bool UtAssert(bool Expression, const char *Description, const char *File, uint32 Line); -/* - * Assert function with CaseType (supports MIR, TSF, NA in addition to FAIL). - * Also supports printf-style message strings to allow more dynamic content in the messages +/** + * \brief Assert function with specific CaseType (supports MIR, TSF, NA in addition to FAIL). + * + * This assert routine allows more consise description of the test case, as it supports + * printf-style message strings to allow dynamic content in the messages. + * + * \param Expression a boolean value which evaluates "true" if the test passes + * \param CaseType the case type to report if expression is "false" (TSF, TTF, FAIL, DEBUG, etc) + * \param File The source file name in which the test case appears + * \param Line The source line number in which the test case appears + * \param MessageFormat a free form printf-style format string describing the test case */ bool UtAssertEx(bool Expression, UtAssert_CaseType_t CaseType, const char *File, uint32 Line, const char *MessageFormat, ...) OS_PRINTF(5, 6); -/* - * Aborts the entire test - * (for failures which going on is meaningless or impossible) +/** + * \brief Aborts the entire test + * + * This may be used for fundamental failures, after which going on becomes meaningless or impossible. + * + * \param Message a free form string describing the failure */ void UtAssert_Abort(const char *Message); diff --git a/ut_assert/inc/uttools.h b/ut_assert/inc/uttools.h index e69429388..2a76b010d 100644 --- a/ut_assert/inc/uttools.h +++ b/ut_assert/inc/uttools.h @@ -38,36 +38,110 @@ * Exported Functions */ -/* Copies a region of memory to a binary file. This file can be reloaded by calling UtBinFile2Mem or it can be - * used to verify test results by calling UtMem2BinFileCmp. */ +/** + * \brief Copies a region of memory to a binary file. + * + * This file can be reloaded by calling UtBinFile2Mem or it can be + * used to verify test results by calling UtMem2BinFileCmp. + * + * \sa UtBinFile2Mem, UtMem2BinFileCmp + * + * \param Memory pointer to memory region + * \param Filename file name to use + * \param Length size of memory region + * + * \returns true if copy was successful + */ bool UtMem2BinFile(const void *Memory, const char *Filename, uint32 Length); -/* Copies a binary file to a region of memory. */ +/** + * \brief Copies a binary file to a region of memory. + * + * \param Memory pointer to memory region + * \param Filename file name to use + * \param Length size of memory region + * + * \returns true if copy was successful + */ bool UtBinFile2Mem(void *Memory, const char *Filename, uint32 Length); -/* Copies a region of memory to a hex file */ +/** + * \brief Copies a region of memory to a hex file + * + * \param Memory pointer to memory region + * \param Filename file name to use + * \param Length size of memory region + * + * \returns true if copy was successful + */ bool UtMem2HexFile(const void *Memory, const char *Filename, uint32 Length); -/* Fills a region of memory with a byte count pattern. */ +/** + * \brief Fills a region of memory with a byte count pattern. + * + * \param Memory pointer to memory region + * \param Length size of memory region + */ void UtMemFill(void *Memory, uint32 Length); -/* Just like the standard sprintf except it returns a pointer to the result string. The result string - * cannot be larger than 256 bytes. */ +/** + * \brief Just like the standard sprintf except it returns a pointer to the result string. + * + * The result string cannot be larger than 256 bytes, and will be truncated if the output + * would exceed that length + * + * \param Spec Printf-style format string + * + * \returns pointer to result string + */ char *UtSprintf(const char *Spec, ...); -/* Calls UtPrintf to print a range of memory as hex bytes. */ +/** + * \brief print a range of memory as hex bytes. + * + * \param Memory pointer to memory region + * \param Length size of memory region + */ void UtPrintx(const void *Memory, uint32 Length); -/* Compares a region of memory to a static pattern and determines if they are equal. Note: Use UtMemSet to - * fill a region of memory with a static pattern. */ +/** + * \brief Compares a region of memory to a static pattern and determines if they are equal. + * + * \note Use standard memset() to fill a region of memory with a static value. + * + * \param Memory pointer to memory region + * \param Value static fill value to check for + * \param Length size of memory region + * + * \returns true if check was successful + */ bool UtMemCmpValue(const void *Memory, uint8 Value, uint32 Length); -/* Compares a region of memory to a byte count pattern and determines if they are equal. Note: Use UtMemFill to - * fill a region of memory with a byte count pattern. */ +/** + * \brief Compares a region of memory to a byte count pattern and determines if they are equal. + * + * \note Use UtMemFill() to fill a region of memory with a byte count pattern. + * + * \param Memory pointer to memory region + * \param Length size of memory region + * + * \returns true if check was successful + */ bool UtMemCmpCount(const void *Memory, uint32 Length); -/* Compares a region of memory with the contents of a binary file and determines if they are equal. Note: Use - * UtMem2BinFile to copy a region of memory to a binary file. */ +/** + * \brief Compares a region of memory with the contents of a binary file and determines if they are equal. + * + * \note Use UtMem2BinFile to copy a region of memory to a binary file. + * + * The size of the file determines the size of the memory region to check. The memory region must be + * at least the size of the file. + * + * \param Memory pointer to memory region + * \param Filename file name to use + * + * \returns true if check was successful + */ bool UtMem2BinFileCmp(const void *Memory, const char *Filename); /* Macros to implement simple printf-like functions for unit testing */