--- a/include/SDL_keyboard.h	Fri Jun 09 07:06:12 2006 +0000
+++ b/include/SDL_keyboard.h	Sat Jun 10 09:11:59 2006 +0000
@@ -41,82 +41,116 @@
 /* *INDENT-ON* */
 #endif
 
-/* Keysym structure
-   - The scancode is hardware dependent, and should not be used by general
-     applications.  If no hardware scancode is available, it will be 0.
-
-   - The 'unicode' translated character is only available when character
-     translation is enabled by the SDL_EnableUNICODE() API.  If non-zero,
-     this is a UNICODE character corresponding to the keypress.  If the
-     high 9 bits of the character are 0, then this maps to the equivalent
-     ASCII character:
-	char ch;
-	if ( (keysym.unicode & 0xFF80) == 0 ) {
-		ch = keysym.unicode & 0x7F;
-	} else {
-		An international character..
-	}
+/**
+ * \struct SDL_keysym
+ *
+ * \brief The SDL keysym structure, used in key events.
  */
 typedef struct SDL_keysym
 {
-    Uint8 scancode;             /* hardware specific scancode */
-    SDLKey sym;                 /* SDL virtual keysym */
-    SDLMod mod;                 /* current key modifiers */
-    Uint16 unicode;             /* translated character */
+    Uint8 scancode;             /**< keyboard specific scancode */
+    SDLKey sym;                 /**< SDL virtual keysym */
+    SDLMod mod;                 /**< current key modifiers */
 } SDL_keysym;
 
-/* This is the mask which refers to all hotkey bindings */
-#define SDL_ALL_HOTKEYS		0xFFFFFFFF
+/* Function prototypes */
+
+/**
+ * \fn int SDL_GetNumKeyboards(void)
+ *
+ * \brief Get the number of keyboard input devices available.
+ *
+ * \sa SDL_SelectKeyboard()
+ */
+extern DECLSPEC int SDLCALL SDL_GetNumKeyboards(void);
 
-/* Function prototypes */
-/*
- * Enable/Disable UNICODE translation of keyboard input.
- * This translation has some overhead, so translation defaults off.
- * If 'enable' is 1, translation is enabled.
- * If 'enable' is 0, translation is disabled.
- * If 'enable' is -1, the translation state is not changed.
- * It returns the previous state of keyboard translation.
+/**
+ * \fn int SDL_SelectKeyboard(int index)
+ *
+ * \brief Set the index of the currently selected keyboard.
+ *
+ * \return The index of the previously selected keyboard.
+ *
+ * \note You can query the currently selected keyboard by passing an index of -1.
+ *
+ * \sa SDL_GetNumKeyboards()
+ */
+extern DECLSPEC int SDLCALL SDL_SelectKeyboard(int index);
+
+/**
+ * \fn int SDL_EnableUNICODE(int enable)
+ *
+ * \brief Enable/Disable UNICODE translation of keyboard input.
+ *
+ * \param enable 1 to enable translation, 0 to disable translation, -1 to query translation
+ *
+ * \return The previous state of keyboard translation
+ *
+ * \note This translation has some overhead, so translation defaults off.
  */
 extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
 
-/*
- * Enable/Disable keyboard repeat.  Keyboard repeat defaults to off.
- * 'delay' is the initial delay in ms between the time when a key is
- * pressed, and keyboard repeat begins.
- * 'interval' is the time in ms between keyboard repeat events.
+/**
+ * \fn int SDL_EnableKeyRepeat(int delay, int interval)
+ * 
+ * \brief Enable keyboard repeat for the selected keyboard.
+ *
+ * \param delay The initial delay in milliseconds between the time when a
+ *              key is pressed and keyboard repeat begins.  Setting a delay
+ *              of 0 will disable keyboard repeat.
+ * \param interval The time in milliseconds between keyboard repeat events.
+ *
+ * \return 0 on success, or -1 if there was an error.
+ *
+ * \note Keyboard repeat defaults to off.
  */
 #define SDL_DEFAULT_REPEAT_DELAY	500
 #define SDL_DEFAULT_REPEAT_INTERVAL	30
-/*
- * If 'delay' is set to 0, keyboard repeat is disabled.
+ /**/
+    extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
+
+/**
+ * \fn void SDL_GetKeyRepeat(int *delay, int *interval)
+ *
+ * \brief Get the current keyboard repeat setting for the selected keyboard.
  */
-extern DECLSPEC int SDLCALL SDL_EnableKeyRepeat(int delay, int interval);
 extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
 
-/*
- * Get a snapshot of the current state of the keyboard.
- * Returns an array of keystates, indexed by the SDLK_* syms.
- * Used:
+/**
+ * \fn Uint8 *SDL_GetKeyState(int *numkeys)
+ *
+ * \brief Get a snapshot of the current state of the selected keyboard.
+ *
+ * \return An array of keystates, indexed by the SDLK_* syms.
+ *
+ * Example:
  * 	Uint8 *keystate = SDL_GetKeyState(NULL);
  *	if ( keystate[SDLK_RETURN] ) ... <RETURN> is pressed.
  */
 extern DECLSPEC Uint8 *SDLCALL SDL_GetKeyState(int *numkeys);
 
-/*
- * Get the current key modifier state
+/**
+ * \fn SDLMod SDL_GetModState(void)
+ *
+ * \brief Get the current key modifier state for the selected keyboard.
  */
 extern DECLSPEC SDLMod SDLCALL SDL_GetModState(void);
 
-/*
- * Set the current key modifier state
- * This does not change the keyboard state, only the key modifier flags.
+/**
+ * \fn void SDL_SetModState(SDLMod modstate)
+ *
+ * \brief Set the current key modifier state for the selected keyboard.
+ *
+ * \note This does not change the keyboard state, only the key modifier flags.
  */
 extern DECLSPEC void SDLCALL SDL_SetModState(SDLMod modstate);
 
-/*
- * Get the name of an SDL virtual keysym
+/**
+ * \fn const char *SDL_GetKeyName(SDLKey key)
+ * 
+ * \brief Get the name of an SDL virtual keysym
  */
-extern DECLSPEC char *SDLCALL SDL_GetKeyName(SDLKey key);
+extern DECLSPEC const char *SDLCALL SDL_GetKeyName(SDLKey key);
 
 
 /* Ends C function definitions when using C++ */