--- a/include/SDL_keyboard.h	Thu Jul 06 18:01:37 2006 +0000
+++ b/include/SDL_keyboard.h	Mon Jul 10 21:04:37 2006 +0000
@@ -20,7 +20,11 @@
     slouken@libsdl.org
 */
 
-/* Include file for SDL keyboard event handling */
+/**
+ * \file SDL_keyboard.h
+ *
+ * Include file for SDL keyboard event handling
+ */
 
 #ifndef _SDL_keyboard_h
 #define _SDL_keyboard_h
@@ -32,90 +36,133 @@
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
 #ifdef __cplusplus
+/* *INDENT-OFF* */
 extern "C" {
+/* *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 */
+typedef struct SDL_keysym
+{
+    Uint8 scancode;             /**< keyboard specific scancode */
+    Uint8 padding[3];           /**< alignment padding */
+    Uint16 sym;                 /**< SDL virtual keysym */
+    Uint16 mod;                 /**< current key modifiers */
+    Uint32 unicode;             /**< OBSOLETE, use SDL_TextInputEvent instead */
 } 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);
+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++ */
 #ifdef __cplusplus
+/* *INDENT-OFF* */
 }
+/* *INDENT-ON* */
 #endif
 #include "close_code.h"
 
 #endif /* _SDL_keyboard_h */
+
+/* vi: set ts=4 sw=4 expandtab: */