SDL_platform_defines.h: Added documentation, and a little whitespace.

wikiheaders needs the documentation in the first row of the line, at least
currently, so I've only indented things I could get away with, but it might
be a little easier to follow the preprocessor logic now.

docs/README-documentation-rules.md

@@ -64,6 +64,10 @@ Note the `/**` at the start of the comment. That's a "Doxygen-style" comment,
 and wikiheaders will treat this differently than a comment with one `*`, as
 this signifies that this is not just a comment, but _documentation_.
 
+These comments _must_ start in the first column of the line, or wikiheaders
+will ignore them, even with the "/**" start (we should improve the script
+someday to handle this, but currently this is a requirement).
+
 We do _not_ parse every magic Doxygen tag, and we don't parse them in `@param`
 format. The goal here was to mostly coexist with people that might want
 to run Doxygen on the SDL headers, not to build Doxygen from scratch. That

include/SDL3/SDL_platform_defines.h

@@ -29,180 +29,451 @@
 #define SDL_platform_defines_h_
 
 #ifdef _AIX
-#define SDL_PLATFORM_AIX    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for AIX.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_AIX 1
 #endif
+
 #ifdef __HAIKU__
-#define SDL_PLATFORM_HAIKU   1
+
+/**
+ * A preprocessor macro that is only defined if compiling for Haiku OS.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_HAIKU 1
 #endif
+
 #if defined(bsdi) || defined(__bsdi) || defined(__bsdi__)
-#define SDL_PLATFORM_BSDI    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for BSDi
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_BSDI 1
 #endif
+
 #if defined(__FreeBSD__) || defined(__FreeBSD_kernel__) || defined(__DragonFly__)
+
+/**
+ * A preprocessor macro that is only defined if compiling for FreeBSD.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
 #define SDL_PLATFORM_FREEBSD 1
 #endif
+
 #if defined(hpux) || defined(__hpux) || defined(__hpux__)
-#define SDL_PLATFORM_HPUX    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for HP-UX.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_HPUX 1
 #endif
+
 #if defined(sgi) || defined(__sgi) || defined(__sgi__) || defined(_SGI_SOURCE)
-#define SDL_PLATFORM_IRIX    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for IRIX.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_IRIX 1
 #endif
+
 #if (defined(linux) || defined(__linux) || defined(__linux__))
-#define SDL_PLATFORM_LINUX   1
+
+/**
+ * A preprocessor macro that is only defined if compiling for Linux.
+ *
+ * Note that Android, although ostensibly a Linux-based system, will not
+ * define this. It defines SDL_PLATFORM_ANDROID instead.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_LINUX 1
 #endif
+
 #if defined(ANDROID) || defined(__ANDROID__)
-#undef SDL_PLATFORM_LINUX /* do we need to do this? */
-#define SDL_PLATFORM_ANDROID    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for Android.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_ANDROID 1
+#undef SDL_PLATFORM_LINUX
 #endif
+
 #ifdef __NGAGE__
+
+/**
+ * A preprocessor macro that is only defined if compiling for Nokia N-Gage.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
 #define SDL_PLATFORM_NGAGE 1
 #endif
 
 #if defined(__unix__) || defined(__unix) || defined(unix)
-#define SDL_PLATFORM_UNIX   1
+
+/**
+ * A preprocessor macro that is only defined if compiling for a Unix-like
+ * system.
+ *
+ * Other platforms, like Linux, might define this in addition to their primary
+ * define.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_UNIX 1
 #endif
 
 #ifdef __APPLE__
-#define SDL_PLATFORM_APPLE  1
+
+/**
+ * A preprocessor macro that is only defined if compiling for Apple platforms.
+ *
+ * iOS, macOS, etc will additionally define a more specific platform macro.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_PLATFORM_MACOS
+ * \sa SDL_PLATFORM_IOS
+ * \sa SDL_PLATFORM_TVOS
+ * \sa SDL_PLATFORM_VISIONOS
+ */
+#define SDL_PLATFORM_APPLE 1
+
 /* lets us know what version of macOS we're compiling on */
 #include <AvailabilityMacros.h>
 #ifndef __has_extension /* Older compilers don't support this */
-#define __has_extension(x) 0
-#include <TargetConditionals.h>
-#undef __has_extension
+    #define __has_extension(x) 0
+    #include <TargetConditionals.h>
+    #undef __has_extension
 #else
-#include <TargetConditionals.h>
+    #include <TargetConditionals.h>
 #endif
 
 /* Fix building with older SDKs that don't define these
-   See this for more information:
-   https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets
+    See this for more information:
+    https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets
 */
 #ifndef TARGET_OS_MACCATALYST
-#define TARGET_OS_MACCATALYST 0
+    #define TARGET_OS_MACCATALYST 0
 #endif
 #ifndef TARGET_OS_IOS
-#define TARGET_OS_IOS 0
+    #define TARGET_OS_IOS 0
 #endif
 #ifndef TARGET_OS_IPHONE
-#define TARGET_OS_IPHONE 0
+    #define TARGET_OS_IPHONE 0
 #endif
 #ifndef TARGET_OS_TV
-#define TARGET_OS_TV 0
+    #define TARGET_OS_TV 0
 #endif
 #ifndef TARGET_OS_SIMULATOR
-#define TARGET_OS_SIMULATOR 0
+    #define TARGET_OS_SIMULATOR 0
 #endif
 #ifndef TARGET_OS_VISION
-#define TARGET_OS_VISION 0
+    #define TARGET_OS_VISION 0
 #endif
 
 #if TARGET_OS_TV
-#define SDL_PLATFORM_TVOS   1
+
+/**
+ * A preprocessor macro that is only defined if compiling for tvOS.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_PLATFORM_APPLE
+ */
+#define SDL_PLATFORM_TVOS 1
 #endif
+
 #if TARGET_OS_VISION
+
+/**
+ * A preprocessor macro that is only defined if compiling for VisionOS.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_PLATFORM_APPLE
+ */
 #define SDL_PLATFORM_VISIONOS 1
 #endif
+
 #if TARGET_OS_IPHONE
-#define SDL_PLATFORM_IOS    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for iOS.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_PLATFORM_APPLE
+ */
+#define SDL_PLATFORM_IOS 1
+
 #else
-#define SDL_PLATFORM_MACOS  1
+
+/**
+ * A preprocessor macro that is only defined if compiling for macOS.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_PLATFORM_APPLE
+ */
+#define SDL_PLATFORM_MACOS 1
+
 #if MAC_OS_X_VERSION_MIN_REQUIRED < 1070
-# error SDL for macOS only supports deploying on 10.7 and above.
+    #error SDL for macOS only supports deploying on 10.7 and above.
 #endif /* MAC_OS_X_VERSION_MIN_REQUIRED < 1070 */
 #endif /* TARGET_OS_IPHONE */
-#endif /* defined(SDL_PLATFORM_APPLE) */
+#endif /* defined(__APPLE__) */
 
 #ifdef __EMSCRIPTEN__
+
+/**
+ * A preprocessor macro that is only defined if compiling for Emscripten.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
 #define SDL_PLATFORM_EMSCRIPTEN 1
 #endif
+
 #ifdef __NetBSD__
+
+/**
+ * A preprocessor macro that is only defined if compiling for NetBSD.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
 #define SDL_PLATFORM_NETBSD 1
 #endif
+
 #ifdef __OpenBSD__
-#define SDL_PLATFORM_OPENBSD    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for OpenBSD.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_OPENBSD 1
 #endif
+
 #if defined(__OS2__) || defined(__EMX__)
-#define SDL_PLATFORM_OS2    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for OS/2.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_OS2 1
 #endif
+
 #if defined(osf) || defined(__osf) || defined(__osf__) || defined(_OSF_SOURCE)
-#define SDL_PLATFORM_OSF    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for Tru64 (OSF/1).
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_OSF 1
 #endif
+
 #ifdef __QNXNTO__
+
+/**
+ * A preprocessor macro that is only defined if compiling for QNX Neutrino.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
 #define SDL_PLATFORM_QNXNTO 1
 #endif
+
 #if defined(riscos) || defined(__riscos) || defined(__riscos__)
+
+/**
+ * A preprocessor macro that is only defined if compiling for RISC OS.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
 #define SDL_PLATFORM_RISCOS 1
 #endif
+
 #if defined(__sun) && defined(__SVR4)
-#define SDL_PLATFORM_SOLARIS    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for SunOS/Solaris.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_SOLARIS 1
 #endif
 
 #if defined(__CYGWIN__)
+
+/**
+ * A preprocessor macro that is only defined if compiling for Cygwin.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
 #define SDL_PLATFORM_CYGWIN 1
 #endif
 
 #if defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN)
-#define SDL_PLATFORM_WINDOWS  1    /* Win32 api and Windows-based OSs */
+
+/**
+ * A preprocessor macro that is only defined if compiling for Windows.
+ *
+ * This also covers several other platforms, like Microsoft GDK, Xbox, WinRT,
+ * etc. Each will have their own more-specific platform macros, too.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ *
+ * \sa SDL_PLATFORM_WIN32
+ * \sa SDL_PLATFORM_XBOXONE
+ * \sa SDL_PLATFORM_XBOXSERIES
+ * \sa SDL_PLATFORM_WINGDK
+ * \sa SDL_PLATFORM_GDK
+ */
+#define SDL_PLATFORM_WINDOWS 1
 
 /* Try to find out if we're compiling for WinRT, GDK or non-WinRT/GDK */
 #if defined(_MSC_VER) && defined(__has_include)
-#if __has_include(<winapifamily.h>)
-#define HAVE_WINAPIFAMILY_H 1
-#else
-#define HAVE_WINAPIFAMILY_H 0
-#endif
+    #if __has_include(<winapifamily.h>)
+        #define HAVE_WINAPIFAMILY_H 1
+    #else
+        #define HAVE_WINAPIFAMILY_H 0
+    #endif
 
-/* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */
+    /* If _USING_V110_SDK71_ is defined it means we are using the Windows XP toolset. */
 #elif defined(_MSC_VER) && (_MSC_VER >= 1700 && !_USING_V110_SDK71_)    /* _MSC_VER == 1700 for Visual Studio 2012 */
-#define HAVE_WINAPIFAMILY_H 1
+    #define HAVE_WINAPIFAMILY_H 1
 #else
-#define HAVE_WINAPIFAMILY_H 0
+    #define HAVE_WINAPIFAMILY_H 0
 #endif
 
 #if HAVE_WINAPIFAMILY_H
-#include <winapifamily.h>
-#define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP))
+    #include <winapifamily.h>
+    #define WINAPI_FAMILY_WINRT (!WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP) && WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_APP))
 #else
-#define WINAPI_FAMILY_WINRT 0
+    #define WINAPI_FAMILY_WINRT 0
 #endif /* HAVE_WINAPIFAMILY_H */
 
 #if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H
-#define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP)
+    #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP)
 #else
-#define SDL_WINAPI_FAMILY_PHONE 0
+    #define SDL_WINAPI_FAMILY_PHONE 0
 #endif
 
 #if WINAPI_FAMILY_WINRT
 #error Windows RT/UWP is no longer supported in SDL
+
 #elif defined(_GAMING_DESKTOP) /* GDK project configuration always defines _GAMING_XXX */
+
+/**
+ * A preprocessor macro that is only defined if compiling for Microsoft GDK
+ * for Windows.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
 #define SDL_PLATFORM_WINGDK 1
+
 #elif defined(_GAMING_XBOX_XBOXONE)
-#define SDL_PLATFORM_XBOXONE    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for Xbox One.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_XBOXONE 1
+
 #elif defined(_GAMING_XBOX_SCARLETT)
+
+/**
+ * A preprocessor macro that is only defined if compiling for Xbox Series.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
 #define SDL_PLATFORM_XBOXSERIES 1
+
 #else
-#define SDL_PLATFORM_WIN32      1
+
+/**
+ * A preprocessor macro that is only defined if compiling for desktop Windows.
+ *
+ * Despite the "32", this also covers 64-bit Windows; as an informal
+ * convention, its system layer tends to still be referred to as "the Win32
+ * API."
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_WIN32 1
+
 #endif
-#endif /* defined(WIN32) || defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */
+#endif /* defined(_WIN32) || defined(SDL_PLATFORM_CYGWIN) */
+
 
 /* This is to support generic "any GDK" separate from a platform-specific GDK */
 #if defined(SDL_PLATFORM_WINGDK) || defined(SDL_PLATFORM_XBOXONE) || defined(SDL_PLATFORM_XBOXSERIES)
-#define SDL_PLATFORM_GDK    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for Microsoft GDK on
+ * any platform.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_GDK 1
 #endif
+
 #if defined(__PSP__) || defined(__psp__)
-#define SDL_PLATFORM_PSP    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for Sony PSP.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_PSP 1
 #endif
+
 #if defined(__PS2__) || defined(PS2)
-#define SDL_PLATFORM_PS2    1
+
+/**
+ * A preprocessor macro that is only defined if compiling for Sony PlayStation
+ * 2.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_PS2 1
 #endif
 
 #if defined(__vita__) || defined(__psp2__)
-#define SDL_PLATFORM_VITA   1
+
+/**
+ * A preprocessor macro that is only defined if compiling for Sony Vita.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_VITA 1
 #endif
 
 #ifdef __3DS__
+
+/**
+ * A preprocessor macro that is only defined if compiling for Nintendo 3DS.
+ *
+ * \since This macro is available since SDL 3.0.0.
+ */
+#define SDL_PLATFORM_3DS 1
+
 #undef __3DS__
-#define SDL_PLATFORM_3DS    1
 #endif
 
 #endif /* SDL_platform_defines_h_ */