--- a/include/SDL_version.h	Sun May 21 17:27:13 2006 +0000
+++ b/include/SDL_version.h	Sun May 28 13:04:16 2006 +0000
@@ -20,7 +20,11 @@
     slouken@libsdl.org
 */
 
-/* This header defines the current SDL version */
+/**
+ * \file SDL_version.h
+ *
+ * This header defines the current SDL version
+ */
 
 #ifndef _SDL_version_h
 #define _SDL_version_h
@@ -30,29 +34,58 @@
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
 #ifdef __cplusplus
+/* *INDENT-OFF* */
 extern "C" {
+/* *INDENT-ON* */
 #endif
 
+/**
+ * \struct SDL_version
+ * \brief Information the version of SDL in use.
+ *
+ * Represents the library's version as three levels: major revision
+ *  (increments with massive changes, additions, and enhancements),
+ *  minor revision (increments with backwards-compatible changes to the
+ *  major revision), and patchlevel (increments with fixes to the minor
+ *  revision).
+ *
+ * \sa SDL_VERSION
+ * \sa SDL_GetVersion
+ */
+typedef struct SDL_version
+{
+    Uint8 major;        /**< major version */
+    Uint8 minor;        /**< minor version */
+    Uint8 patch;        /**< update version */
+} SDL_version;
+
 /* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
 */
 #define SDL_MAJOR_VERSION	1
 #define SDL_MINOR_VERSION	3
 #define SDL_PATCHLEVEL		0
 
-typedef struct SDL_version {
-	Uint8 major;
-	Uint8 minor;
-	Uint8 patch;
-} SDL_version;
-
-/* This macro can be used to fill a version structure with the compile-time
- * version of the SDL library.
+/**
+ * \def SDL_VERSION(x)
+ * \brief Macro to determine SDL version program was compiled against.
+ *
+ * This macro fills in a SDL_version structure with the version of the
+ *  library you compiled against. This is determined by what header the
+ *  compiler uses. Note that if you dynamically linked the library, you might
+ *  have a slightly newer or older version at runtime. That version can be
+ *  determined with SDL_GetVersion(), which, unlike SDL_VERSION,
+ *  is not a macro.
+ *
+ * \param x A pointer to a SDL_version struct to initialize.
+ *
+ * \sa SDL_version
+ * \sa SDL_GetVersion
  */
-#define SDL_VERSION(X)							\
+#define SDL_VERSION(x)							\
 {									\
-	(X)->major = SDL_MAJOR_VERSION;					\
-	(X)->minor = SDL_MINOR_VERSION;					\
-	(X)->patch = SDL_PATCHLEVEL;					\
+	(x)->major = SDL_MAJOR_VERSION;					\
+	(x)->minor = SDL_MINOR_VERSION;					\
+	(x)->patch = SDL_PATCHLEVEL;					\
 }
 
 /* This macro turns the version numbers into a numeric value:
@@ -70,16 +103,42 @@
 #define SDL_VERSION_ATLEAST(X, Y, Z) \
 	(SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z))
 
-/* This function gets the version of the dynamically linked SDL library.
-   it should NOT be used to fill a version structure, instead you should
-   use the SDL_Version() macro.
+/**
+ * \fn void SDL_GetVersion(SDL_version *ver)
+ * \brief Get the version of SDL that is linked against your program.
+ *
+ * If you are using a shared library (DLL) version of SDL, then it is
+ *  possible that it will be different than the version you compiled against.
+ *
+ * This is a real function; the macro SDL_VERSION tells you what version
+ *  of SDL you compiled against:
+ *
+ * \code
+ * SDL_version compiled;
+ * SDL_version linked;
+ *
+ * SDL_VERSION(&compiled);
+ * SDL_GetVersion(&linked);
+ * printf("We compiled against SDL version %d.%d.%d ...\n",
+ *           compiled.major, compiled.minor, compiled.patch);
+ * printf("But we linked against SDL version %d.%d.%d.\n",
+ *           linked.major, linked.minor, linked.patch);
+ * \endcode
+ *
+ * This function may be called safely at any time, even before SDL_Init().
+ *
+ * \sa SDL_VERSION
  */
-extern DECLSPEC const SDL_version * SDLCALL SDL_Linked_Version(void);
+extern DECLSPEC void SDLCALL SDL_GetVersion (SDL_version * ver);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
+/* *INDENT-OFF* */
 }
+/* *INDENT-ON* */
 #endif
 #include "close_code.h"
 
 #endif /* _SDL_version_h */
+
+/* vi: set ts=4 sw=4 expandtab: */