Apply macro documentation from #35521.

1 files changed, 268 insertions, 81 deletions

diff --git a/core/error_macros.h b/core/error_macros.h
index 664bff244f..80ceede043 100644
--- a/core/error_macros.h
+++ b/core/error_macros.h
@@ -80,10 +80,15 @@ 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
+/**
+ * Don't use GENERATE_TRAP() directly, should only be used be the macros below.
+ */
 #define GENERATE_TRAP() __debugbreak()
 #else
+/**
+ * Don't use GENERATE_TRAP() directly, should only be used be the macros below.
+ */
 #define GENERATE_TRAP() __builtin_trap()
 #endif
 
@@ -111,10 +116,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 // These macros should be used instead of `ERR_FAIL_COND` for bounds checking.
 
 // Integer index out of bounds error macros.
-// Ensures an integer index `m_index` is less than `m_size` and greater than or equal to 0.
-
-// The current function returns.
 
+/**
+ * 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 {                                                                                                            \
 		if (unlikely((m_index) < 0 || (m_index) >= (m_size))) {                                                     \
@@ -123,6 +132,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                           \
 	} while (0)
 
+/**
+ * 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 {                                                                                                                              \
 		if (unlikely((m_index) < 0 || (m_index) >= (m_size))) {                                                                       \
@@ -131,8 +144,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                             \
 	} while (0)
 
-// The current function returns m_retval.
-
+/**
+ * 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 {                                                                                                            \
 		if (unlikely((m_index) < 0 || (m_index) >= (m_size))) {                                                     \
@@ -141,6 +159,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                           \
 	} while (0)
 
+/**
+ * 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 {                                                                                                                              \
 		if (unlikely((m_index) < 0 || (m_index) >= (m_size))) {                                                                       \
@@ -149,8 +171,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                             \
 	} while (0)
 
-// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable.
-
+/**
+ * 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))) {                                                               \
@@ -159,6 +187,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                     \
 	} 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))) {                                                                             \
@@ -168,10 +203,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 	} while (0)
 
 // Unsigned integer index out of bounds error macros.
-// Ensures an unsigned integer index `m_index` is less than `m_size`
-
-// The current function returns.
 
+/**
+ * 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))) {                                                                      \
@@ -180,6 +219,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                           \
 	} 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))) {                                                                                        \
@@ -188,8 +231,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                             \
 	} while (0)
 
-// The current function returns m_retval.
-
+/**
+ * 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 {                                                                                                            \
 		if (unlikely((m_index) >= (m_size))) {                                                                      \
@@ -198,6 +246,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                           \
 	} while (0)
 
+/**
+ * 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 {                                                                                                                              \
 		if (unlikely((m_index) >= (m_size))) {                                                                                        \
@@ -206,8 +258,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                             \
 	} while (0)
 
-// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable.
-
+/**
+ * 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_UNSIGNED_INDEX(m_index, m_size)                                                                             \
 	do {                                                                                                                      \
 		if (unlikely((m_index) >= (m_size))) {                                                                                \
@@ -216,6 +274,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                     \
 	} while (0)
 
+/**
+ * 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_UNSIGNED_INDEX_MSG(m_index, m_size, m_msg)                                                                                \
 	do {                                                                                                                                    \
 		if (unlikely((m_index) >= (m_size))) {                                                                                              \
@@ -225,10 +290,14 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 	} while (0)
 
 // Null reference error macros.
-// Ensures a pointer `m_param` is not null.
-
-// The current function returns.
 
+/**
+ * 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)) {                                                                           \
@@ -237,6 +306,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                   \
 	} while (0)
 
+/**
+ * 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)) {                                                                                             \
@@ -245,8 +318,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                     \
 	} while (0)
 
-// The current function returns 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)) {                                                                           \
@@ -255,6 +333,10 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                   \
 	} while (0)
 
+/**
+ * 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)) {                                                                                             \
@@ -263,11 +345,15 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                     \
 	} while (0)
 
-// Error condition macros.
-// Ensures that `m_cond` is not true.
-
-// The current function returns.
-
+/**
+ * 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)) {                                                                            \
@@ -276,6 +362,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                  \
 	} while (0)
 
+/**
+ * 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)) {                                                                                              \
@@ -284,8 +377,15 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                    \
 	} while (0)
 
-// The current function returns 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)) {                                                                                                      \
@@ -294,6 +394,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                            \
 	} while (0)
 
+/**
+ * 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)) {                                                                                                                        \
@@ -302,44 +409,68 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                                                              \
 	} while (0)
 
-// The current loop continues.
-
-#define ERR_CONTINUE(m_cond)                                                                                             \
-	do {                                                                                                                 \
-		if (unlikely(m_cond)) {                                                                                          \
+/**
+ * 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;                                                                                                    \
-		}                                                                                                                \
+			continue;                                                                                                  \
+		}                                                                                                              \
 	} while (0)
 
-#define ERR_CONTINUE_MSG(m_cond, m_msg)                                                                                                    \
-	do {                                                                                                                                   \
-		if (unlikely(m_cond)) {                                                                                                            \
+/**
+ * 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;                                                                                                                      \
-		}                                                                                                                                  \
+			continue;                                                                                                                    \
+		}                                                                                                                                \
 	} while (0)
 
-// The current loop breaks.
-
-#define ERR_BREAK(m_cond)                                                                                              \
-	do {                                                                                                               \
-		if (unlikely(m_cond)) {                                                                                        \
+/**
+ * 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;                                                                                                     \
-		}                                                                                                              \
+			break;                                                                                                   \
+		}                                                                                                            \
 	} while (0)
 
-#define ERR_BREAK_MSG(m_cond, m_msg)                                                                                                     \
-	do {                                                                                                                                 \
-		if (unlikely(m_cond)) {                                                                                                          \
+/**
+ * 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;                                                                                                                       \
-		}                                                                                                                                \
+			break;                                                                                                                     \
+		}                                                                                                                              \
 	} while (0)
 
-// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable.
-
+/**
+ * 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 CRASH_COND(m_cond)                                                                                        \
 	do {                                                                                                          \
 		if (unlikely(m_cond)) {                                                                                   \
@@ -348,6 +479,13 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 		}                                                                                                         \
 	} while (0)
 
+/**
+ * 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 CRASH_COND_MSG(m_cond, m_msg)                                                                                               \
 	do {                                                                                                                            \
 		if (unlikely(m_cond)) {                                                                                                     \
@@ -358,43 +496,71 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 
 // Generic error macros.
 
-// The current function returns.
-
+/**
+ * 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()                                                                     \
 	do {                                                                               \
 		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed."); \
 		return;                                                                        \
 	} while (0)
 
+/**
+ * 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 ERR_FAIL_MSG(m_msg)                                                                              \
 	do {                                                                                                 \
 		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, "Method/Function Failed.", DEBUG_STR(m_msg)); \
 		return;                                                                                          \
 	} while (0)
 
-// The current function returns m_retval.
-
+/**
+ * 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 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)
 
-#define ERR_FAIL_V_MSG(m_value, m_msg)                                                                                              \
+/**
+ * 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_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_value;                                                                                                             \
+		return m_retval;                                                                                                            \
 	} while (0)
 
-// Print error message macros.
-
+/**
+ * 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_PRINT(m_msg)                                                      \
 	do {                                                                      \
 		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg)); \
 	} while (0)
 
-// Only prints the error message once.
-
+/**
+ * Prints `m_msg` once during the application lifetime.
+ */
 #define ERR_PRINT_ONCE(m_msg)                                                     \
 	do {                                                                          \
 		static bool first_print = true;                                           \
@@ -405,15 +571,22 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 	} while (0)
 
 // Print warning message macros.
-// To warn about deprecated usage, use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead.
 
+/**
+ * Prints `m_msg`.
+ *
+ * If warning about deprecated usage, use `WARN_DEPRECATED` or `WARN_DEPRECATED_MSG` instead.
+ */
 #define WARN_PRINT(m_msg)                                                                          \
 	do {                                                                                           \
 		_err_print_error(FUNCTION_STR, __FILE__, __LINE__, DEBUG_STR(m_msg), ERR_HANDLER_WARNING); \
 	} while (0)
 
-// Only prints the warning message once.
-
+/**
+ * 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_msg)                                                                         \
 	do {                                                                                               \
 		static bool first_print = true;                                                                \
@@ -424,34 +597,48 @@ void _err_print_index_error(const char *p_function, const char *p_file, int p_li
 	} while (0)
 
 // Print deprecated warning message macros.
-// Only prints the warning message once.
 
-#define WARN_DEPRECATED                                                                                                                                   \
-	do {                                                                                                                                                  \
-		static volatile bool warning_shown = false;                                                                                                       \
-		if (!warning_shown) {                                                                                                                             \
+/**
+ * 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;                                                                                                                         \
-		}                                                                                                                                                 \
+			warning_shown = true;                                                                                                                          \
+		}                                                                                                                                                  \
 	} while (0)
 
-#define WARN_DEPRECATED_MSG(m_msg)                                                                                                                                          \
-	do {                                                                                                                                                                    \
-		static volatile bool warning_shown = false;                                                                                                                         \
-		if (!warning_shown) {                                                                                                                                               \
+/**
+ * Warns that the current function is deprecated and prints `m_msg`.
+ */
+#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;                                                                                                                                           \
-		}                                                                                                                                                                   \
+			warning_shown = true;                                                                                                                                            \
+		}                                                                                                                                                                    \
 	} while (0)
 
-// Only use CRASH macros if there is no sensible fallback, that is, the error is unrecoverable.
-
+/**
+ * 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)); \