Heavy work on improving category documentation.

Still more to go!

Reference Issue #9440.

include/SDL3/SDL_error.h

@@ -178,8 +178,43 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ClearError(void);
  *  Private error reporting function - used internally.
  */
 /* @{ */
+
+/**
+ * A macro to standardize error reporting on unsupported operations.
+ *
+ * This simply calls SDL_SetError() with a standardized error string, for
+ * convenience, consistency, and clarity.
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_Unsupported()               SDL_SetError("That operation is not supported")
+
+/**
+ * A macro to standardize error reporting on unsupported operations.
+ *
+ * This simply calls SDL_SetError() with a standardized error string, for
+ * convenience, consistency, and clarity.
+ *
+ * A common usage pattern inside SDL is this:
+ *
+ * ```c
+ * bool MyFunction(const char *str) {
+ *     if (!str) {
+ *         return SDL_InvalidParamError("str");  // returns false.
+ *     }
+ *     DoSomething(str);
+ *     return true;
+ * }
+ * ```
+ *
+ * \threadsafety It is safe to call this macro from any thread.
+ *
+ * \since This macro is available since SDL 3.1.3.
+ */
 #define SDL_InvalidParamError(param)    SDL_SetError("Parameter '%s' is invalid", (param))
+
 /* @} *//* Internal error functions */
 
 /* Ends C function definitions when using C++ */