Commit 3f978c0f9307e57fcbe7b167dc34ab9ef245f344

Ryan C. Gordon 2021-11-18T15:56:16

include: Improved documentation of SDL_RegisterApp and SDL_UnregisterApp.

diff --git a/include/SDL_main.h b/include/SDL_main.h
index 0717d6a..0d0af77 100644
--- a/include/SDL_main.h
+++ b/include/SDL_main.h
@@ -139,11 +139,45 @@ extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
 #ifdef __WIN32__
 
 /**
- * This can be called to set the application class at startup
+ * Register a win32 window class for SDL's use.
+ *
+ * This can be called to set the application window class at startup.
+ * It is safe to call this multiple times, as long as every call is
+ * eventually paired with a call to SDL_UnregisterApp, but a second
+ * registration attempt while a previous registration is still active
+ * will be ignored, other than to increment a counter.
+ *
+ * Most applications do not need to, and should not, call this directly;
+ * SDL will call it when initializing the video subsystem.
+ *
+ * \param name the window class name, in UTF-8 encoding. If NULL,
+ *        SDL currently uses "SDL_app" but this isn't guaranteed.
+ * \param style the value to use in WNDCLASSEX::style. If `name` is
+ *        NULL, SDL currently uses `(CS_BYTEALIGNCLIENT | CS_OWNDC)`
+ *        regardless of what is specified here.
+ * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero,
+ *        SDL will use `GetModuleHandle(NULL)` instead.
+ * \returns 0 on success, -1 on error. SDL_GetError() may have details.
  *
  * \since This function is available since SDL 2.0.2.
  */
 extern DECLSPEC int SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst);
+
+/**
+ * Deregister the win32 window class from an SDL_RegisterApp call.
+ *
+ * This can be called to undo the effects of SDL_RegisterApp.
+ *
+ * Most applications do not need to, and should not, call this directly;
+ * SDL will call it when deinitializing the video subsystem.
+ *
+ * It is safe to call this multiple times, as long as every call is
+ * eventually paired with a prior call to SDL_RegisterApp. The window
+ * class will only be deregistered when the registration counter in
+ * SDL_RegisterApp decrements to zero through calls to this function.
+ *
+ * \since This function is available since SDL 2.0.2.
+ */
 extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
 
 #endif /* __WIN32__ */