From 8fe33a340b8979a73fa84f201c15519a9b5d0266 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Sun, 14 Nov 2010 21:20:43 -0500 Subject: Document libdimension with Doxygen. --- libdimension/dimension/error.h | 79 +++++++++++++++++++++++++++++++++--------- 1 file changed, 63 insertions(+), 16 deletions(-) (limited to 'libdimension/dimension/error.h') diff --git a/libdimension/dimension/error.h b/libdimension/dimension/error.h index a0b3857..8482266 100644 --- a/libdimension/dimension/error.h +++ b/libdimension/dimension/error.h @@ -18,22 +18,29 @@ * . * *************************************************************************/ -/* - * Error handling. Errors are reported at a given severity by the dmnsn_error() - * macro at a given severity, which prints a warning if it is below the set - * resilience, or prints an error and exits if it's at or above the set - * resilience. +/** + * @file + * Error reporting interface. Errors are reported at a given severity by the + * dmnsn_error() macro at a given severity, which prints a warning if it is + * below the set resilience, or prints an error and exits if it's at or above + * the set resilience. */ #ifndef DIMENSION_ERROR_H #define DIMENSION_ERROR_H -typedef enum { - DMNSN_SEVERITY_LOW, /* Only die on low resilience */ - DMNSN_SEVERITY_MEDIUM, /* Die on low or medium resilience */ - DMNSN_SEVERITY_HIGH /* Always die */ +/** Error severity codes */ +typedef enum dmnsn_severity { + DMNSN_SEVERITY_LOW, /**< Only die on low resilience */ + DMNSN_SEVERITY_MEDIUM, /**< Die on low or medium resilience */ + DMNSN_SEVERITY_HIGH /**< Always die */ } dmnsn_severity; +/** + * @internal + * @def DMNSN_FUNC + * @brief Expands to the name of the current function + */ #ifdef __GNUC__ #define DMNSN_FUNC __PRETTY_FUNCTION__ #elif __STDC_VERSION__ >= 199901L @@ -42,13 +49,24 @@ typedef enum { #define DMNSN_FUNC "" #endif -/* Use this macro to report an error */ +/** + * Report an error. + * @param[in] severity A @ref dmnsn_severity representing the severity of the + * error. DMNSN_SEVERITY_HIGH will always terminate the + * running thread. + * @param[in] str A string to print explaining the error. + */ #define dmnsn_error(severity, str) \ dmnsn_report_error((dmnsn_severity)(severity), \ DMNSN_FUNC, __FILE__, __LINE__, \ str) -/* Make an assertion */ +/** + * @def dmnsn_assert + * Make an assertion. + * @param[in] expr The expression to assert. + * @param[in] str A string to print if the assertion fails. + */ #ifdef NDEBUG #define dmnsn_assert(expr, str) ((void)0) #else @@ -60,21 +78,50 @@ typedef enum { } while (0) #endif -/* Called by dmnsn_error() - don't call directly */ +/** + * @internal + * Called by dmnsn_error(); don't call directly. + * @param[in] severity The severity of the error. + * @param[in] func The name of the function where the error originated. + * @param[in] file The file where the error originated. + * @param[in] line The line number where the error originated. + * @param[in] str A string describing the error. + */ void dmnsn_report_error(dmnsn_severity severity, const char *func, const char *file, unsigned int line, const char *str); -/* Get and set the library resilience, thread-safely */ +/** + * Get the library resilience, thread-safely. + * @return The error severity considered fatal. + */ dmnsn_severity dmnsn_get_resilience(void); + +/** + * Set the library resilience, thread-safely. + * @param[in] resilience The new minimum severity that will cause a fatal + * error. + */ void dmnsn_set_resilience(dmnsn_severity resilience); -/* Fatal error callback type */ +/** + * Fatal error callback type. This function should never return. + */ typedef void dmnsn_fatal_error_fn(void); -/* Get and set libdimension fatal error handling strategy - the default is - exit(EXIT_FAILURE) */ +/** + * Get the libdimension fatal error handler, thread-safely. The default fatal + * error handler terminates the current thread, or the entire program if the + * current thread is the main thread. + * @return The current fatal error handler. + */ dmnsn_fatal_error_fn *dmnsn_get_fatal_error_fn(void); + +/** + * Set the libdimension fatal error handler, thread-safely. + * @param[in] fatal The new fatal error handler. This function must never + * return. + */ void dmnsn_set_fatal_error_fn(dmnsn_fatal_error_fn *fatal); #endif /* DIMENSION_ERROR_H */ -- cgit v1.2.3