Merge pull request #33391 from madmiraal/cleanup-error_macros

Clean up error_macros.h

1 files changed, 356 insertions, 236 deletions

diff --git a/core/error_macros.h b/core/error_macros.h
index 8ba6618942..80ceede043 100644
--- a/core/error_macros.h
+++ b/core/error_macros.h
@@ -32,21 +32,8 @@
 #define ERROR_MACROS_H
 
 #include "core/typedefs.h"
-/**
- * Error macros. Unlike exceptions and asserts, these macros try to maintain consistency and stability
- * inside the code. It is recommended to always return processable data, so in case of an error,
- * the engine can keep working well.
- * In most cases, bugs and/or invalid data are not fatal and should never allow a perfectly running application
- * to fail or crash.
- */
-
-/**
- * Pointer to the error macro printing function. Reassign to any function to have errors printed
- */
-
-/** Function used by the error macros */
 
-// function, file, line, error, explanation
+class String;
 
 enum ErrorHandlerType {
 	ERR_HANDLER_ERROR,
@@ -55,7 +42,8 @@ enum ErrorHandlerType {
 	ERR_HANDLER_SHADER,
 };
 
-class String;
+// Pointer to the error handler printing function. Reassign to any function to have errors printed.
+// Parameters: userdata, function, file, line, error, explanation, type.
 typedef void (*ErrorHandlerFunc)(void *, const char *, const char *, int p_line, const char *, const char *, ErrorHandlerType p_type);
 
 struct ErrorHandlerList {
@@ -75,6 +63,7 @@ struct ErrorHandlerList {
 void add_error_handler(ErrorHandlerList *p_handler);
 void remove_error_handler(ErrorHandlerList *p_handler);
 
+// Functions used by the error macros.
 void _err_print_error(const char *p_function, const char *p_file, int p_line, const char *p_error, ErrorHandlerType p_type = ERR_HANDLER_ERROR);
 void _err_print_error(const char *p_function, const char *p_file, int p_line, const String &p_error, ErrorHandlerType p_type = ERR_HANDLER_ERROR);
 void _err_print_error(const char *p_function, const char *p_file, int p_line, const char *p_error, const char *p_message, ErrorHandlerType p_type = ERR_HANDLER_ERROR);
@@ -84,15 +73,6 @@ void _err_print_error(const char *p_function, const char *p_file, int p_line, co
 void _err_print_index_error(const char *p_function, const char *p_file, int p_line, int64_t p_index, int64_t p_size, const char *p_index_str, const char *p_size_str, const char *p_message = "", bool fatal = false);
 void _err_print_index_error(const char *p_function, const char *p_file, int p_line, int64_t p_index, int64_t p_size, const char *p_index_str, const char *p_size_str, const String &p_message, bool fatal = false);
 
-#ifndef _STR
-#define _STR(m_x) #m_x
-#define _MKSTR(m_x) _STR(m_x)
-#endif
-
-#define _FNL __FILE__ ":"
-
-/** An index has failed if m_index<0 or m_index >=m_size, the function exits */
-
 #ifdef __GNUC__
 //#define FUNCTION_STR __PRETTY_FUNCTION__ - too annoying
 #define FUNCTION_STR __FUNCTION__
@@ -100,15 +80,16 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 #define FUNCTION_STR __FUNCTION__
 #endif
 
-// Don't use this directly; instead, use any of the CRASH_* macros
 #ifdef _MSC_VER
-#define GENERATE_TRAP                       \
-	__debugbreak();                         \
-	/* Avoid warning about control paths */ \
-	for (;;) {                              \
-	}
+/**
+ * Don't use GENERATE_TRAP() directly, should only be used be the macros below.
+ */
+#define GENERATE_TRAP() __debugbreak()
 #else
-#define GENERATE_TRAP __builtin_trap();
+/**
+ * Don't use GENERATE_TRAP() directly, should only be used be the macros below.
+ */
+#define GENERATE_TRAP() __builtin_trap()
 #endif
 
 // Used to strip debug messages in release mode
@@ -118,12 +99,30 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 #define DEBUG_STR(m_msg) ""
 #endif
 
-// (*): See https://stackoverflow.com/questions/257418/do-while-0-what-is-it-good-for
+/**
+ * Error macros.
+ * WARNING: These macros work in the opposite way to assert().
+ *
+ * Unlike exceptions and asserts, these macros try to maintain consistency and stability.
+ * In most cases, bugs and/or invalid data are not fatal. They should never allow a perfectly
+ * running application to fail or crash.
+ * Always try to return processable data, so the engine can keep running well.
+ * Use the _MSG versions to print a meaningful message to help with debugging.
+ *
+ * Note: See https://stackoverflow.com/questions/257418/do-while-0-what-is-it-good-for
+ */
+
+// Index out of bounds error macros.
+// These macros should be used instead of `ERR_FAIL_COND` for bounds checking.
+
+// Integer index out of bounds error macros.
 
 /**
- * If `m_index` is less than 0 or greater than or equal to `m_size`, prints a generic
- * error message and returns from the function. This macro should be preferred to
- * `ERR_FAIL_COND` for bounds checking.
+ * Try using `ERR_FAIL_INDEX_MSG`.
+ * Only use this macro if there is no sensible error message.
+ *
+ * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0.
+ * If not, the current function returns.
  */
 #define ERR_FAIL_INDEX(m_index, m_size)                                                                             \
 	do {                                                                                                            \
@@ -131,12 +130,11 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \
 			return;                                                                                                 \
 		}                                                                                                           \
-	} while (0); // (*)
+	} while (0)
 
 /**
- * If `m_index` is less than 0 or greater than or equal to `m_size`, prints a custom
- * error message and returns from the function. This macro should be preferred to
- * `ERR_FAIL_COND_MSG` for bounds checking.
+ * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0.
+ * If not, prints `m_msg` and the current function returns.
  */
 #define ERR_FAIL_INDEX_MSG(m_index, m_size, m_msg)                                                                                    \
 	do {                                                                                                                              \
@@ -144,12 +142,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \
 			return;                                                                                                                   \
 		}                                                                                                                             \
-	} while (0); // (*)
+	} while (0)
 
 /**
- * If `m_index` is less than 0 or greater than or equal to `m_size`,
- * prints a generic error message and returns the value specified in `m_retval`.
- * This macro should be preferred to `ERR_FAIL_COND_V` for bounds checking.
+ * Try using `ERR_FAIL_INDEX_V_MSG`.
+ * Only use this macro if there is no sensible error message.
+ *
+ * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0.
+ * If not, the current function returns `m_retval`.
  */
 #define ERR_FAIL_INDEX_V(m_index, m_size, m_retval)                                                                 \
 	do {                                                                                                            \
@@ -157,12 +157,11 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \
 			return m_retval;                                                                                        \
 		}                                                                                                           \
-	} while (0); // (*)
+	} while (0)
 
 /**
- * If `m_index` is less than 0 or greater than or equal to `m_size`,
- * prints a custom error message and returns the value specified in `m_retval`.
- * This macro should be preferred to `ERR_FAIL_COND_V_MSG` for bounds checking.
+ * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0.
+ * If not, prints `m_msg` and the current function returns `m_retval`.
  */
 #define ERR_FAIL_INDEX_V_MSG(m_index, m_size, m_retval, m_msg)                                                                        \
 	do {                                                                                                                              \
@@ -170,12 +169,74 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \
 			return m_retval;                                                                                                          \
 		}                                                                                                                             \
-	} while (0); // (*)
+	} while (0)
+
+/**
+ * Try using `ERR_FAIL_INDEX_MSG` or `ERR_FAIL_INDEX_V_MSG`.
+ * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable, and
+ * there is no sensible error message.
+ *
+ * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0.
+ * If not, the application crashes.
+ */
+#define CRASH_BAD_INDEX(m_index, m_size)                                                                                      \
+	do {                                                                                                                      \
+		if (unlikely((m_index) < 0 || (m_index) >= (m_size))) {                                                               \
+			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), "", true); \
+			GENERATE_TRAP();                                                                                                  \
+		}                                                                                                                     \
+	} while (0)
+
+/**
+ * Try using `ERR_FAIL_INDEX_MSG` or `ERR_FAIL_INDEX_V_MSG`.
+ * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable.
+ *
+ * Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0.
+ * If not, prints `m_msg` and the application crashes.
+ */
+#define CRASH_BAD_INDEX_MSG(m_index, m_size, m_msg)                                                                                         \
+	do {                                                                                                                                    \
+		if (unlikely((m_index) < 0 || (m_index) >= (m_size))) {                                                                             \
+			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg), true); \
+			GENERATE_TRAP();                                                                                                                \
+		}                                                                                                                                   \
+	} while (0)
+
+// Unsigned integer index out of bounds error macros.
+
+/**
+ * Try using `ERR_FAIL_UNSIGNED_INDEX_MSG`.
+ * Only use this macro if there is no sensible error message.
+ *
+ * Ensures an unsigned integer index `m_index` is less than `m_size`.
+ * If not, the current function returns.
+ */
+#define ERR_FAIL_UNSIGNED_INDEX(m_index, m_size)                                                                    \
+	do {                                                                                                            \
+		if (unlikely((m_index) >= (m_size))) {                                                                      \
+			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \
+			return;                                                                                                 \
+		}                                                                                                           \
+	} while (0)
+
+/**
+ * Ensures an unsigned integer index `m_index` is less than `m_size`.
+ * If not, prints `m_msg` and the current function returns.
+ */
+#define ERR_FAIL_UNSIGNED_INDEX_MSG(m_index, m_size, m_msg)                                                                           \
+	do {                                                                                                                              \
+		if (unlikely((m_index) >= (m_size))) {                                                                                        \
+			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \
+			return;                                                                                                                   \
+		}                                                                                                                             \
+	} while (0)
 
 /**
- * If `m_index` is greater than or equal to `m_size`,
- * prints a generic error message and returns the value specified in `m_retval`.
- * This macro should be preferred to `ERR_FAIL_COND_V` for unsigned bounds checking.
+ * Try using `ERR_FAIL_UNSIGNED_INDEX_V_MSG`.
+ * Only use this macro if there is no sensible error message.
+ *
+ * Ensures an unsigned integer index `m_index` is less than `m_size`.
+ * If not, the current function returns `m_retval`.
  */
 #define ERR_FAIL_UNSIGNED_INDEX_V(m_index, m_size, m_retval)                                                        \
 	do {                                                                                                            \
@@ -183,12 +244,11 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size)); \
 			return m_retval;                                                                                        \
 		}                                                                                                           \
-	} while (0); // (*)
+	} while (0)
 
 /**
- * If `m_index` is greater than or equal to `m_size`,
- * prints a custom error message and returns the value specified in `m_retval`.
- * This macro should be preferred to `ERR_FAIL_COND_V_MSG` for unsigned bounds checking.
+ * Ensures an unsigned integer index `m_index` is less than `m_size`.
+ * If not, prints `m_msg` and the current function returns `m_retval`.
  */
 #define ERR_FAIL_UNSIGNED_INDEX_V_MSG(m_index, m_size, m_retval, m_msg)                                                               \
 	do {                                                                                                                              \
@@ -196,333 +256,393 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg)); \
 			return m_retval;                                                                                                          \
 		}                                                                                                                             \
-	} while (0); // (*)
+	} while (0)
 
 /**
- * If `m_index` is less than 0 or greater than or equal to `m_size`,
- * crashes the engine immediately with a generic error message.
- * Only use this if there's no sensible fallback (i.e. the error is unrecoverable).
- * This macro should be preferred to `CRASH_COND` for bounds checking.
+ * Try using `ERR_FAIL_UNSIGNED_INDEX_MSG` or `ERR_FAIL_UNSIGNED_INDEX_V_MSG`.
+ * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable, and
+ * there is no sensible error message.
+ *
+ * Ensures an unsigned integer index `m_index` is less than `m_size`.
+ * If not, the application crashes.
  */
-#define CRASH_BAD_INDEX(m_index, m_size)                                                                                      \
+#define CRASH_BAD_UNSIGNED_INDEX(m_index, m_size)                                                                             \
 	do {                                                                                                                      \
-		if (unlikely((m_index) < 0 || (m_index) >= (m_size))) {                                                               \
+		if (unlikely((m_index) >= (m_size))) {                                                                                \
 			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), "", true); \
-			GENERATE_TRAP                                                                                                     \
+			GENERATE_TRAP();                                                                                                  \
 		}                                                                                                                     \
-	} while (0); // (*)
+	} while (0)
 
 /**
- * If `m_index` is less than 0 or greater than or equal to `m_size`,
- * crashes the engine immediately with a custom error message.
- * Only use this if there's no sensible fallback (i.e. the error is unrecoverable).
- * This macro should be preferred to `CRASH_COND` for bounds checking.
+ * Try using `ERR_FAIL_UNSIGNED_INDEX_MSG` or `ERR_FAIL_UNSIGNED_INDEX_V_MSG`.
+ * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable.
+ *
+ * Ensures an unsigned integer index `m_index` is less than `m_size`.
+ * If not, prints `m_msg` and the application crashes.
  */
-#define CRASH_BAD_INDEX_MSG(m_index, m_size, m_msg)                                                                              \
-	do {                                                                                                                         \
-		if (unlikely((m_index) < 0 || (m_index) >= (m_size))) {                                                                  \
-			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), m_msg, true); \
-			GENERATE_TRAP                                                                                                        \
-		}                                                                                                                        \
-	} while (0); // (*)
+#define CRASH_BAD_UNSIGNED_INDEX_MSG(m_index, m_size, m_msg)                                                                                \
+	do {                                                                                                                                    \
+		if (unlikely((m_index) >= (m_size))) {                                                                                              \
+			_err_print_index_error(FUNCTION_STR, __FILE__, __LINE__, m_index, m_size, _STR(m_index), _STR(m_size), DEBUG_STR(m_msg), true); \
+			GENERATE_TRAP();                                                                                                                \
+		}                                                                                                                                   \
+	} while (0)
+
+// Null reference error macros.
 
 /**
- * If `m_param` is `null`, prints a generic error message and returns from the function.
+ * Try using `ERR_FAIL_NULL_MSG`.
+ * Only use this macro if there is no sensible error message.
+ *
+ * Ensures a pointer `m_param` is not null.
+ * If it is null, the current function returns.
  */
 #define ERR_FAIL_NULL(m_param)                                                                              \
-	{                                                                                                       \
+	do {                                                                                                    \
 		if (unlikely(!m_param)) {                                                                           \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null."); \
 			return;                                                                                         \
 		}                                                                                                   \
-	}
+	} while (0)
 
 /**
- * If `m_param` is `null`, prints a custom error message and returns from the function.
+ * Ensures a pointer `m_param` is not null.
+ * If it is null, prints `m_msg` and the current function returns.
  */
 #define ERR_FAIL_NULL_MSG(m_param, m_msg)                                                                                     \
-	{                                                                                                                         \
+	do {                                                                                                                      \
 		if (unlikely(!m_param)) {                                                                                             \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null.", DEBUG_STR(m_msg)); \
 			return;                                                                                                           \
 		}                                                                                                                     \
-	}
+	} while (0)
 
 /**
- * If `m_param` is `null`, prints a generic error message and returns the value specified in `m_retval`.
+ * Try using `ERR_FAIL_NULL_V_MSG`.
+ * Only use this macro if there is no sensible error message.
+ *
+ * Ensures a pointer `m_param` is not null.
+ * If it is null, the current function returns `m_retval`.
  */
 #define ERR_FAIL_NULL_V(m_param, m_retval)                                                                  \
-	{                                                                                                       \
+	do {                                                                                                    \
 		if (unlikely(!m_param)) {                                                                           \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null."); \
 			return m_retval;                                                                                \
 		}                                                                                                   \
-	}
+	} while (0)
 
 /**
- * If `m_param` is `null`, prints a custom error message and returns the value specified in `m_retval`.
+ * Ensures a pointer `m_param` is not null.
+ * If it is null, prints `m_msg` and the current function returns `m_retval`.
  */
 #define ERR_FAIL_NULL_V_MSG(m_param, m_retval, m_msg)                                                                         \
-	{                                                                                                                         \
+	do {                                                                                                                      \
 		if (unlikely(!m_param)) {                                                                                             \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Parameter \"" _STR(m_param) "\" is null.", DEBUG_STR(m_msg)); \
 			return m_retval;                                                                                                  \
 		}                                                                                                                     \
-	}
+	} while (0)
 
 /**
- * If `m_cond` evaluates to `true`, prints a generic error message and returns from the function.
+ * Try using `ERR_FAIL_COND_MSG`.
+ * Only use this macro if there is no sensible error message.
+ * If checking for null use ERR_FAIL_NULL_MSG instead.
+ * If checking index bounds use ERR_FAIL_INDEX_MSG instead.
+ *
+ * Ensures `m_cond` is false.
+ * If `m_cond` is true, the current function returns.
  */
 #define ERR_FAIL_COND(m_cond)                                                                              \
-	{                                                                                                      \
+	do {                                                                                                   \
 		if (unlikely(m_cond)) {                                                                            \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true."); \
 			return;                                                                                        \
 		}                                                                                                  \
-	}
+	} while (0)
 
 /**
- * If `m_cond` evaluates to `true`, prints a custom error message and returns from the function.
+ * Ensures `m_cond` is false.
+ * If `m_cond` is true, prints `m_msg` and the current function returns.
+ *
+ * If checking for null use ERR_FAIL_NULL_MSG instead.
+ * If checking index bounds use ERR_FAIL_INDEX_MSG instead.
  */
 #define ERR_FAIL_COND_MSG(m_cond, m_msg)                                                                                     \
-	{                                                                                                                        \
+	do {                                                                                                                     \
 		if (unlikely(m_cond)) {                                                                                              \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true.", DEBUG_STR(m_msg)); \
 			return;                                                                                                          \
 		}                                                                                                                    \
-	}
+	} while (0)
 
 /**
- * If `m_cond` evaluates to `true`, crashes the engine immediately with a generic error message.
- * Only use this if there's no sensible fallback (i.e. the error is unrecoverable).
- */
-#define CRASH_COND(m_cond)                                                                                        \
-	{                                                                                                             \
-		if (unlikely(m_cond)) {                                                                                   \
-			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Condition \"" _STR(m_cond) "\" is true."); \
-			GENERATE_TRAP                                                                                         \
-		}                                                                                                         \
-	}
-
-/**
- * If `m_cond` evaluates to `true`, crashes the engine immediately with a custom error message.
- * Only use this if there's no sensible fallback (i.e. the error is unrecoverable).
- */
-#define CRASH_COND_MSG(m_cond, m_msg)                                                                                               \
-	{                                                                                                                               \
-		if (unlikely(m_cond)) {                                                                                                     \
-			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Condition \"" _STR(m_cond) "\" is true.", DEBUG_STR(m_msg)); \
-			GENERATE_TRAP                                                                                                           \
-		}                                                                                                                           \
-	}
-
-/**
- * If `m_cond` evaluates to `true`, prints a generic error message and returns the value specified in `m_retval`.
+ * Try using `ERR_FAIL_COND_V_MSG`.
+ * Only use this macro if there is no sensible error message.
+ * If checking for null use ERR_FAIL_NULL_V_MSG instead.
+ * If checking index bounds use ERR_FAIL_INDEX_V_MSG instead.
+ *
+ * Ensures `m_cond` is false.
+ * If `m_cond` is true, the current function returns `m_retval`.
  */
 #define ERR_FAIL_COND_V(m_cond, m_retval)                                                                                            \
-	{                                                                                                                                \
+	do {                                                                                                                             \
 		if (unlikely(m_cond)) {                                                                                                      \
-			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Returned: " _STR(m_retval)); \
+			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. returned: " _STR(m_retval)); \
 			return m_retval;                                                                                                         \
 		}                                                                                                                            \
-	}
+	} while (0)
 
 /**
- * If `m_cond` evaluates to `true`, prints a custom error message and returns the value specified in `m_retval`.
+ * Ensures `m_cond` is false.
+ * If `m_cond` is true, prints `m_msg` and the current function returns `m_retval`.
+ *
+ * If checking for null use ERR_FAIL_NULL_V_MSG instead.
+ * If checking index bounds use ERR_FAIL_INDEX_V_MSG instead.
  */
 #define ERR_FAIL_COND_V_MSG(m_cond, m_retval, m_msg)                                                                                                   \
-	{                                                                                                                                                  \
+	do {                                                                                                                                               \
 		if (unlikely(m_cond)) {                                                                                                                        \
-			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Returned: " _STR(m_retval), DEBUG_STR(m_msg)); \
+			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. returned: " _STR(m_retval), DEBUG_STR(m_msg)); \
 			return m_retval;                                                                                                                           \
 		}                                                                                                                                              \
-	}
+	} while (0)
 
 /**
- * If `m_cond` evaluates to `true`, prints a custom error message and continues the loop the macro is located in.
+ * Try using `ERR_CONTINUE_MSG`.
+ * Only use this macro if there is no sensible error message.
+ *
+ * Ensures `m_cond` is false.
+ * If `m_cond` is true, the current loop continues.
  */
 #define ERR_CONTINUE(m_cond)                                                                                           \
-	{                                                                                                                  \
+	do {                                                                                                               \
 		if (unlikely(m_cond)) {                                                                                        \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Continuing."); \
 			continue;                                                                                                  \
 		}                                                                                                              \
-	}
+	} while (0)
 
 /**
- * If `m_cond` evaluates to `true`, prints a custom error message and continues the loop the macro is located in.
+ * Ensures `m_cond` is false.
+ * If `m_cond` is true, prints `m_msg` and the current loop continues.
  */
 #define ERR_CONTINUE_MSG(m_cond, m_msg)                                                                                                  \
-	{                                                                                                                                    \
+	do {                                                                                                                                 \
 		if (unlikely(m_cond)) {                                                                                                          \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Continuing.", DEBUG_STR(m_msg)); \
 			continue;                                                                                                                    \
 		}                                                                                                                                \
-	}
+	} while (0)
 
 /**
- * If `m_cond` evaluates to `true`, prints a generic error message and breaks from the loop the macro is located in.
+ * Try using `ERR_BREAK_MSG`.
+ * Only use this macro if there is no sensible error message.
+ *
+ * Ensures `m_cond` is false.
+ * If `m_cond` is true, the current loop breaks.
  */
 #define ERR_BREAK(m_cond)                                                                                            \
-	{                                                                                                                \
+	do {                                                                                                             \
 		if (unlikely(m_cond)) {                                                                                      \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Breaking."); \
 			break;                                                                                                   \
 		}                                                                                                            \
-	}
+	} while (0)
 
 /**
- * If `m_cond` evaluates to `true`, prints a custom error message and breaks from the loop the macro is located in.
+ * Ensures `m_cond` is false.
+ * If `m_cond` is true, prints `m_msg` and the current loop breaks.
  */
 #define ERR_BREAK_MSG(m_cond, m_msg)                                                                                                   \
-	{                                                                                                                                  \
+	do {                                                                                                                               \
 		if (unlikely(m_cond)) {                                                                                                        \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Condition \"" _STR(m_cond) "\" is true. Breaking.", DEBUG_STR(m_msg)); \
 			break;                                                                                                                     \
 		}                                                                                                                              \
-	}
+	} while (0)
 
 /**
- * Prints a generic error message and returns from the function.
+ * Try using `ERR_FAIL_COND_MSG` or `ERR_FAIL_COND_V_MSG`.
+ * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable, and
+ * there is no sensible error message.
+ *
+ * Ensures `m_cond` is false.
+ * If `m_cond` is true, the application crashes.
  */
-#define ERR_FAIL()                                                            \
-	{                                                                         \
-		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method failed."); \
-		return;                                                               \
-	}
+#define CRASH_COND(m_cond)                                                                                        \
+	do {                                                                                                          \
+		if (unlikely(m_cond)) {                                                                                   \
+			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Condition \"" _STR(m_cond) "\" is true."); \
+			GENERATE_TRAP();                                                                                      \
+		}                                                                                                         \
+	} while (0)
 
 /**
- * Prints a custom error message and returns from the function.
+ * Try using `ERR_FAIL_COND_MSG` or `ERR_FAIL_COND_V_MSG`.
+ * Only use this macro if there is no sensible fallback i.e. the error is unrecoverable.
+ *
+ * Ensures `m_cond` is false.
+ * If `m_cond` is true, prints `m_msg` and the application crashes.
  */
-#define ERR_FAIL_MSG(m_msg)                                                                     \
-	{                                                                                           \
-		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method failed.", DEBUG_STR(m_msg)); \
-		return;                                                                                 \
-	}
+#define CRASH_COND_MSG(m_cond, m_msg)                                                                                               \
+	do {                                                                                                                            \
+		if (unlikely(m_cond)) {                                                                                                     \
+			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Condition \"" _STR(m_cond) "\" is true.", DEBUG_STR(m_msg)); \
+			GENERATE_TRAP();                                                                                                        \
+		}                                                                                                                           \
+	} while (0)
 
-/**
- * Prints a generic error message and returns the value specified in `m_retval`.
- */
-#define ERR_FAIL_V(m_retval)                                                                              \
-	{                                                                                                     \
-		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method failed. Returning: " __STR(m_retval)); \
-		return m_retval;                                                                                  \
-	}
+// Generic error macros.
 
 /**
- * Prints a custom error message and returns the value specified in `m_retval`.
+ * Try using `ERR_FAIL_COND_MSG` or `ERR_FAIL_MSG`.
+ * Only use this macro if more complex error detection or recovery is required, and
+ * there is no sensible error message.
+ *
+ * The current function returns.
  */
-#define ERR_FAIL_V_MSG(m_retval, m_msg)                                                                                     \
-	{                                                                                                                       \
-		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method failed. Returning: " __STR(m_retval), DEBUG_STR(m_msg)); \
-		return m_retval;                                                                                                    \
-	}
+#define ERR_FAIL()                                                                     \
+	do {                                                                               \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed."); \
+		return;                                                                        \
+	} while (0)
 
 /**
- * Crashes the engine immediately with a generic error message.
- * Only use this if there's no sensible fallback (i.e. the error is unrecoverable).
+ * Try using `ERR_FAIL_COND_MSG`.
+ * Only use this macro if more complex error detection or recovery is required.
+ *
+ * Prints `m_msg`, and the current function returns.
  */
-#define CRASH_NOW()                                                                  \
-	{                                                                                \
-		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method failed."); \
-		GENERATE_TRAP                                                                \
-	}
+#define ERR_FAIL_MSG(m_msg)                                                                              \
+	do {                                                                                                 \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed.", DEBUG_STR(m_msg)); \
+		return;                                                                                          \
+	} while (0)
 
 /**
- * Crashes the engine immediately with a custom error message.
- * Only use this if there's no sensible fallback (i.e. the error is unrecoverable).
+ * Try using `ERR_FAIL_COND_V_MSG` or `ERR_FAIL_V_MSG`.
+ * Only use this macro if more complex error detection or recovery is required, and
+ * there is no sensible error message.
+ *
+ * The current function returns `m_retval`.
  */
-#define CRASH_NOW_MSG(m_msg)                                                                           \
-	{                                                                                                  \
-		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method failed.", DEBUG_STR(m_msg)); \
-		GENERATE_TRAP                                                                                  \
-	}
+#define ERR_FAIL_V(m_retval)                                                                                      \
+	do {                                                                                                          \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed, returning: " __STR(m_value)); \
+		return m_retval;                                                                                          \
+	} while (0)
 
 /**
- * Prints an error message without returning.
+ * Try using `ERR_FAIL_COND_V_MSG`.
+ * Only use this macro if more complex error detection or recovery is required.
+ *
+ * Prints `m_msg`, and the current function returns `m_retval`.
  */
-#define ERR_PRINT(m_string)                                           \
-	{                                                                 \
-		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string); \
-	}
+#define ERR_FAIL_V_MSG(m_retval, m_msg)                                                                                             \
+	do {                                                                                                                            \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed, returning: " __STR(m_value), DEBUG_STR(m_msg)); \
+		return m_retval;                                                                                                            \
+	} while (0)
 
 /**
- * Prints an error message without returning.
- * FIXME: Remove this macro and replace all uses with `ERR_PRINT` as it's identical.
+ * Try using `ERR_FAIL_COND_MSG`, `ERR_FAIL_COND_V_MSG`, `ERR_CONTINUE_MSG` or ERR_BREAK_MSG.
+ * Only use this macro at the start of a function that has not been implemented yet, or
+ * if more complex error detection or recovery is required.
+ *
+ * Prints `m_msg`.
  */
-#define ERR_PRINTS(m_string)                                          \
-	{                                                                 \
-		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string); \
-	}
+#define ERR_PRINT(m_msg)                                                      \
+	do {                                                                      \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \
+	} while (0)
 
 /**
- * Prints an error message without returning, but only do so once in the application lifecycle.
- * This can be used to avoid spamming the console with error messages.
+ * Prints `m_msg` once during the application lifetime.
  */
-#define ERR_PRINT_ONCE(m_string)                                          \
-	{                                                                     \
-		static bool first_print = true;                                   \
-		if (first_print) {                                                \
-			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string); \
-			first_print = false;                                          \
-		}                                                                 \
-	}
+#define ERR_PRINT_ONCE(m_msg)                                                     \
+	do {                                                                          \
+		static bool first_print = true;                                           \
+		if (first_print) {                                                        \
+			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \
+			first_print = false;                                                  \
+		}                                                                         \
+	} while (0)
 
-/**
- * Prints a warning message without returning. To warn about deprecated usage,
- * use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead.
- */
-#define WARN_PRINT(m_string)                                                               \
-	{                                                                                      \
-		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string, ERR_HANDLER_WARNING); \
-	}
+// Print warning message macros.
 
 /**
- * Prints a warning message without returning.
- * FIXME: Remove this macro and replace all uses with `WARN_PRINT` as it's identical.
+ * Prints `m_msg`.
+ *
+ * If warning about deprecated usage, use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead.
  */
-#define WARN_PRINTS(m_string)                                                              \
-	{                                                                                      \
-		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string, ERR_HANDLER_WARNING); \
-	}
+#define WARN_PRINT(m_msg)                                                                          \
+	do {                                                                                           \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \
+	} while (0)
 
 /**
- * Prints a warning message without returning, but only do so once in the application lifecycle.
- * This can be used to avoid spamming the console with warning messages.
+ * Prints `m_msg` once during the application lifetime.
+ *
+ * If warning about deprecated usage, use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead.
  */
-#define WARN_PRINT_ONCE(m_string)                                                              \
-	{                                                                                          \
-		static bool first_print = true;                                                        \
-		if (first_print) {                                                                     \
-			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, m_string, ERR_HANDLER_WARNING); \
-			first_print = false;                                                               \
-		}                                                                                      \
-	}
+#define WARN_PRINT_ONCE(m_msg)                                                                         \
+	do {                                                                                               \
+		static bool first_print = true;                                                                \
+		if (first_print) {                                                                             \
+			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \
+			first_print = false;                                                                       \
+		}                                                                                              \
+	} while (0)
+
+// Print deprecated warning message macros.
 
 /**
- * Prints a generic deprecation warning message without returning.
- * This should be preferred to `WARN_PRINT` for deprecation warnings.
+ * Warns that the current function is deprecated.
  */
 #define WARN_DEPRECATED                                                                                                                                    \
-	{                                                                                                                                                      \
+	do {                                                                                                                                                   \
 		static volatile bool warning_shown = false;                                                                                                        \
 		if (!warning_shown) {                                                                                                                              \
 			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "This method has been deprecated and will be removed in the future.", ERR_HANDLER_WARNING); \
 			warning_shown = true;                                                                                                                          \
 		}                                                                                                                                                  \
-	}
+	} while (0)
 
 /**
- * Prints a custom deprecation warning message without returning.
- * This should be preferred to `WARN_PRINT` for deprecation warnings.
+ * Warns that the current function is deprecated and prints `m_msg`.
  */
-#define WARN_DEPRECATED_MSG(m_msg)                                                                                                                                \
-	{                                                                                                                                                             \
-		static volatile bool warning_shown = false;                                                                                                               \
-		if (!warning_shown) {                                                                                                                                     \
-			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "This method has been deprecated and will be removed in the future.", m_msg, ERR_HANDLER_WARNING); \
-			warning_shown = true;                                                                                                                                 \
-		}                                                                                                                                                         \
-	}
+#define WARN_DEPRECATED_MSG(m_msg)                                                                                                                                           \
+	do {                                                                                                                                                                     \
+		static volatile bool warning_shown = false;                                                                                                                          \
+		if (!warning_shown) {                                                                                                                                                \
+			_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "This method has been deprecated and will be removed in the future.", DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \
+			warning_shown = true;                                                                                                                                            \
+		}                                                                                                                                                                    \
+	} while (0)
+
+/**
+ * Do not use.
+ * If the application should never reach this point use CRASH_NOW_MSG(m_msg) to explain why.
+ *
+ * The application crashes.
+ */
+#define CRASH_NOW()                                                                           \
+	do {                                                                                      \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method/Function Failed."); \
+		GENERATE_TRAP();                                                                      \
+	} while (0)
+
+/**
+ * Only use if the application should never reach this point.
+ *
+ * Prints `m_msg`, and then the application crashes.
+ */
+#define CRASH_NOW_MSG(m_msg)                                                                                    \
+	do {                                                                                                        \
+		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "FATAL: Method/Function Failed.", DEBUG_STR(m_msg)); \
+		GENERATE_TRAP();                                                                                        \
+	} while (0)
 
 #endif