From 47ae4139085fa2224655b63fa6c9916eeda716d3 Mon Sep 17 00:00:00 2001
From: capitalistspz <keipitalists@proton.me>
Date: Sat, 1 Aug 2026 21:01:54 +0000
Subject: [PATCH] coreinit/debug: Add documentation to the functions that kill
 the console (#450)

* coreinit/debug: Add documentation to the functions that kill the console

* Add `WUT_NORETURN` and apply to relevant functions

* Add `OSSetPanicCallback`

* Remove `WUT_NORETURN`
---
 include/coreinit/debug.h | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/include/coreinit/debug.h b/include/coreinit/debug.h
index 70b0c936..6de02041 100644
--- a/include/coreinit/debug.h
+++ b/include/coreinit/debug.h
@@ -16,6 +16,7 @@ typedef struct OSFatalError OSFatalError;
 typedef void (*DisassemblyPrintFn)(const char *fmt, ...);
 
 typedef uint32_t (*DisassemblyFindSymbolFn)(uint32_t addr, char *symbolNameBuf, uint32_t symbolNameBufSize);
+typedef void (*OSPanicCallback)(void *userData);
 
 typedef enum DisassemblePPCFlags
 {
@@ -41,8 +42,11 @@ typedef enum OSFatalErrorMessageType
 struct OSFatalError
 {
    OSFatalErrorMessageType messageType;
+   //! Error code, displayed on screen as unsigned, and printed in log as signed
    uint32_t errorCode;
+   //! See \link OSGetUPID \endlink
    uint32_t processId;
+   //! Internal error code printed in log
    uint32_t internalErrorCode;
    uint32_t line;
    char functionName[64];
@@ -83,7 +87,14 @@ void
 OSReportWarn(const char *fmt, ...)
    WUT_FORMAT_PRINTF(1, 2);
 
-
+/**
+ * Halts the system and logs the cause, traps if debugger is present
+ * \param file name of the file where the panic occurred
+ * \param line position in the file where the panic occurred
+ * \param fmt printf-style format string for logging
+ *
+ * \sa OSSetPanicCallback
+ */
 void
 OSPanic(const char *file,
         uint32_t line,
@@ -91,10 +102,30 @@ OSPanic(const char *file,
         ...)
    WUT_FORMAT_PRINTF(3, 4);
 
+/**
+ * Set a callback to be triggered when an \link OSPanic \endlink occurs
+ * \param userData data to pass to the callback
+ */
+void
+OSSetPanicCallback(OSPanicCallback callback,
+                   void *userData);
 
+/**
+ * Displays a message on TV and gamepad screens via OSScreen, and halts the system via \link OSPanic \endlink
+ * \param msg message to be displayed and logged
+ * \sa coreinit_screen
+ */
 void
 OSFatal(const char *msg);
 
+/**
+ * Switch to the fatal error process ("An error has occured." screen)
+ * \param error structure describing the error
+ * \param functionName function name printed in log
+ * \param line line number printed in log
+ *
+ * The fatal error process displays the error code, firmware version, Wii U model, serial number and status code
+ */
 void
 OSSendFatalError(OSFatalError *error,
                  const char *functionName,